Update async orders

This endpoint in the Tango API allows you to update an asynchronous order. Use this endpoint to update only non‑fulfillment fields such as: campaign, purchase order number, and notes. You can correct or enhance information associated with the order for internal tracking, reporting, PO reconciliation, or program categorization, but not the reward amount, recipients, reward credentials, etc.

Use the following endpoint to update async orders placed under your platform:

Endpoint	Purpose
`PATCH {URI}/asyncOrders/customers/{customerIdentifier}/ accounts/{accountIdentifier}/{externalRefID}`	To update an async order under a specific account.

Benefits

Ability to update or correct metadata like campaign names, purchase order numbers, or notes associated with the order, which is useful for tracking and reporting.
Ensures accurate records for compliance, auditing, and reconciliation.

Use case

Acme Health offers a wellness program in which patients who complete annual check-ups receive a $25 digital gift card. Orders are created asynchronously in batches at the end of each week. Sometimes metadata associated with these orders—such as campaign tags, purchase order numbers, or notes—may be incorrect or missing. To fix this, Acme Health uses the PATCH endpoint to update specific fields of an existing order without reissuing the reward.

The following path parameter indicates which specific asynchronous order the request is acting upon:

Path params	Data type	Requirement	Description
customerIdentifier	string	required	Unique ID for the customer.
accountIdentifier	string	required	Unique ID for the account under the customer.
externalRefID	string	required	Reference ID of the original order to be updated. An idempotent field that can be used for your order cross-reference and to prevent accidental order duplication. This value is returned in the order response, order details, and order history. The string has a maximum of 100 alphanumeric characters.

The following body params can be modified using the PATCH endpoint:

Body params	Data type	Description
campaign	string	The campaign field can be used to administratively categorize a specific order. Must be between 0 and 1024 characters in length. (Optional)
purchaseOrderNumber	string	The Purchase Order Number associated with this order.
notes	string	Order notes up to 150 characters. (Optional)

Response message

The following example shows the payload for when you use this endpoint with a successful response:

{
  "referenceOrderID": "string",
  "externalRefID": "string",
  "orderStatus": "COMPLETE",
  "createdAt": "date",
  "completedAt": null,
  "customerIdentifier": "string",
  "accountIdentifier": "string",
  "sender": null,
  "amountCharged": null,
  "campaign": "string",
  "purchaseOrderNumber": "string",
  "notes": "string",
  "totalLineItems": integer,
  "pagination": null,
  "orderErrors": null,
  "lineItems": []
}

The response body provides:

Field	What does it tell you
`externalRefID`	(Required) The external reference ID of the async order you updated. This is the unique idempotency key you originally provided when creating the async order.
`status`	The current async processing status (e.g., pending, queued, completed, failed). Returned after the update request.
`totalLineItems`	Total number of line items associated with this async order.
`createdAt`	Timestamp showing when the async order was originally created.
failedLineItems	List of line items that failed validation during the update request. Each entry includes: lineItemId, externalRefLineItemID, utid, and an errors[] array with field, errorCodeValue, errorCodeName, and message.
lineItemId	Tango’s internal identifier for the line item that failed validation.
externalRefLineItemID	Your idempotent reference ID for this line item.
utid	Reward UTID for the line item.
errors	One or more validation errors associated with this line item.
field	The specific field that failed validation, such as: amount, recipient.email, etc.
errorCodeValue	Numeric error code for the validation failure.
errorCodeName	Readable and internal code name for the error type.
message	Human‑readable explanation of the error.
duplicateLineItemRefIds	An object containing any duplicate line item reference IDs detected during the update request (keys are line item reference IDs, values are counts).

The possible response codes for this endpoint are as follows. For details, see i18nkey codes and their error messages:

Response code	Meaning
200	The request was successful.
400	The server could not understand the request due to invalid syntax.
401	Authentication is required and has either not been provided or failed.
429	Exceeded the allowable TPS rate limit. It indicates that the user has sent too many requests in a given amount of time, and the server is rate-limiting further requests
500	Something went wrong on the server, but the server cannot be more specific about the exact problem.
503	The server is currently unable to handle the request due to temporary overload or maintenance.