Update purchase history redemption instructions or voucher details

Updates purchase-history correction fields for an existing order and returns the updated purchase history.

Use this when a partner integration needs to correct the redemption instructions, voucher code, or voucher expiry date shown for a customer's order after purchase. Redemption instructions remain an order-level product snapshot correction. Voucher code and voucher expiry date are a paired correction and also update the source Voucher record.

Authentication:

Bearer API key in Authorization header

API key must have the purchase-history permission

Community is resolved from the API key token — do not pass communityID

Returns 401 if the key is missing or invalid, and 403 if the key lacks the permission

Side effects:

Publishes the update:purchase-history pub/sub event; the store service processes it and performs the database write

redemptionInstructions, when provided, updates PurchaseHistory.product.redemptionInstructions only; the source Product record is not modified

voucherCode and voucherExpiryDate, when provided together, update the source Voucher record (code, expiryDate) through the normal voucher update service path

The source Voucher update and PurchaseHistory snapshot update are committed in the same store database transaction; if either write fails, neither write is committed

After a successful voucher update, the store service runs the normal voucher update side effects: voucher:update socket event, HOT content-hash stamping, and HOT-to-legacy voucher sync when enabled

The paired voucher fields are also stored on the PurchaseHistory snapshot (voucherCode, voucherExpiryDate) so historical order views stay stable

Returns 502 if the upstream store service is unreachable or the publisher times out

Rate limits:

Standard API rate limits apply

Constraints:

purchaseHistoryID accepts either the Mongo _id or the human-readable purchase/order ID (e.g. ORD202641612055614747)

Send redemptionInstructions by itself, or send voucherCode and voucherExpiryDate together, or send all three fields

If either voucherCode or voucherExpiryDate is provided, both are required

At least one valid update group must be provided

redemptionInstructions: optional, trimmed, non-empty when provided, max 10000 chars

voucherCode: trimmed, non-empty when provided, max 512 chars

voucherExpiryDate: trimmed, valid calendar date in DD/MM/YYYY format

Returns 409 if the new voucher code already exists for another voucher in the same product and community

Returns 404 if the purchase history, product snapshot target, or voucher target does not exist in this community

Validation violations return 400

Example — update voucher details:

{
  "voucherCode": "UPDATED-VOUCHER-2026",
  "voucherExpiryDate": "31/12/2026"
}

Example — update redemption instructions only:

{
  "redemptionInstructions": "Collect at the main counter between 10am and 6pm. Present your order ID and a valid photo ID."
}

Example — update all correction fields:

{
  "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"
}

Related endpoints:

(none — this module currently exposes a single endpoint)

What it is for: Update purchase history redemption instructions or voucher details. Use this for fulfillment, voucher, redemption instruction, and purchase-state updates.
How to use it: Send a PATCH request to /purchase-histories/{purchaseHistoryID} with the request body, query parameters, or multipart fields shown below. Partner API key required when this surface is enabled for the community. Confirm gateway access before using in production.
Successful response: HTTP 200. The body follows the endpoint schema; many integration endpoints wrap the useful payload under data with status and message.
Common error states:

400 invalid request body, query, ObjectId, pagination, file format, or missing required field.

401 missing, invalid, expired, or insufficient API key/token.

403 key is valid but cannot access this community/channel/user/resource, where supported by the service.

404 target resource, route, or community-scoped record was not found.

409 duplicate or conflicting state for create/update operations, where applicable.

500 unexpected Returning.AI service error.

curl --location --request PATCH 'https://api.returning.ai/purchase-histories/ORD202641612055614747' \ --header 'Authorization: Bearer XXXXXX' \ --header 'Content-Type: application/json' \ --data '{ "voucherCode": "UPDATED-VOUCHER-2026", "voucherExpiryDate": "31/12/2026" }'

{ "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" } }

Update purchase history redemption instructions or voucher details

Request

Responses