Update redemption instructions or voucher details
PATCH
/v1/purchase-histories/{purchaseHistoryID}
What this endpoint does
INFO
Quick start
Authentication and permission
| Send | Permission | Community scope |
|---|---|---|
Authorization: Bearer <apiKey> | customerSuccess | Community scope is derived from the key; do not send a community identifier. |
Complete examples
{
"redemptionInstructions": "Deliver to synthetic account AGENT-001"
}Success and readback
meta.code = PURCHASE_HISTORY_UPDATED{
"meta": {
"status": "success",
"statusCode": 200,
"code": "PURCHASE_HISTORY_UPDATED"
},
"message": "Update redemption instructions or voucher details successfully",
"data": {
"_id": "hist_agent_01",
"redemptionId": "ORD202607220001",
"productName": "Agent Test Voucher",
"price": 100,
"quantity": 1,
"status": "New Purchase",
"redemptionInstructions": "Deliver to synthetic account AGENT-001"
}
}CHECK
Errors and recovery
meta.code, never message text.| HTTP | Machine code | What the caller should do | Retry? |
|---|---|---|---|
| 400 | VALIDATION_FAILED | Repair errors[]. | No, fix first |
| 401 | AUTH_API_KEY_REQUIRED | Add the Authorization header. | No, fix first |
| 401 | AUTH_API_KEY_INVALID | Replace or rotate the key. | No, fix first |
| 401 | AUTH_API_KEY_VALIDATION_FAILED | Authentication could not be completed. | Yes, with backoff |
| 403 | AUTH_PERMISSION_REQUIRED | Request the customerSuccess permission; no resource data is returned. | No, fix first |
| 404 | STORE_RESOURCE_NOT_FOUND | Refresh through order detail. | After refreshing the ID |
| 409 | STORE_RESOURCE_CONFLICT | Re-read status before retrying. | After reconciliation |
| 500 | INTERNAL_ERROR | Retry with exponential backoff and the same request context, then escalate. | Yes, with backoff |
| 502 | STORE_DEPENDENCY_UNAVAILABLE | Retry with backoff and the same request context. | Yes, with backoff |
Retry safety
WARNING
Gotchas
Next steps
Request
Path Params
Header Params
Body Params application/jsonRequired
Responses
Request Request Example
Shell
JavaScript
Java
Swift
cURL
curl --location --request PATCH 'https://api.returning.ai/v1/purchase-histories/ORD202641612055614747' \
--header 'Authorization: Bearer XXXXXX' \
--header 'Content-Type: application/json' \
--data '{
"redemptionInstructions": "Collect at the main counter between 10am and 6pm. Present your order ID and a valid photo ID.",
"voucherCode": "UPDATED-VOUCHER-2026",
"voucherExpiryDate": "31/12/2026"
}'Response Response Example
200 - Success Example
{
"meta": {
"status": "success",
"statusCode": 200
},
"message": "Update purchase history success.",
"data": {
"_id": "507f1f77bcf86cd799439012",
"purchaseID": "ORD202641612055614747",
"communityID": "507f1f77bcf86cd799439013",
"userID": "507f1f77bcf86cd799439014",
"voucherCode": "UPDATED-VOUCHER-2026",
"voucherExpiryDate": "2026-12-31T00:00:00.000Z",
"product": {
"_id": "507f1f77bcf86cd799439015",
"name": "Gold Voucher",
"redemptionInstructions": "Collect at the main counter between 10am and 6pm. Present your order ID and a valid photo ID."
},
"voucher": {
"_id": "507f1f77bcf86cd799439016",
"code": "UPDATED-VOUCHER-2026",
"status": "redeemed",
"expiryDate": "2026-12-31T00:00:00.000Z"
},
"createdAt": "2026-04-01T00:00:00.000Z",
"updatedAt": "2026-04-20T00:00:00.000Z"
}
}Modified at 2026-08-08 01:52:17