Update purchase history redemption instructions

Updates the redemption instructions for a specific purchase history record and returns the updated document.

Use this when a partner integration needs to amend the redemption instructions attached to a customer's order (e.g. adding a shipping note, updating a voucher redemption flow, or correcting delivery details after purchase).

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/invalid, 403 if the key lacks the permission

Side effects:

Snapshots the product into PurchaseHistory.product and overwrites product.redemptionInstructions on the purchase history document

The Product collection is not modified — only the per-order snapshot

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

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 order ID (e.g. ORD202641612055614747)

redemptionInstructions: required, non-empty string, trimmed, max 10000 chars

Returns 404 if the purchase history does not exist in this community

Validation violations return 400

Example — update:

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

Related endpoints:

(none — this module currently exposes a single endpoint)

curl --location --request PATCH 'https://api.returning.ai/v1/purchase-histories/ORD202641612055614747' \ --header 'Authorization: Bearer XXXXXX' \ --header 'Content-Type: application/json' \ --data-raw '{ "redemptionInstructions": "Collect at the main counter between 10am and 6pm. Present your order ID and a valid photo ID." }'

{ "meta": { "status": "success", "statusCode": 200 }, "message": "Update purchase history success.", "data": { "_id": "507f1f77bcf86cd799439012", "orderID": "ORD202641612055614747", "communityID": "507f1f77bcf86cd799439013", "userID": "507f1f77bcf86cd799439014", "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." }, "createdAt": "2026-04-01T00:00:00.000Z", "updatedAt": "2026-04-20T00:00:00.000Z" } }

Update purchase history redemption instructions

Request

Responses