Create async orders

🚧
Closed Release:
This feature is available for a limited number of customers with specific use cases only.

This endpoint enables you to create asynchronous orders for distributing rewards under a specific account. It's designed for multiple line items, where you need to send rewards to recipients with various delivery methods. The asynchronous orders are efficient and suitable for large-scale reward campaigns.

Use the following endpoint to create a batch of asynchronous orders:

Endpoint	Purpose
`POST {URI}/asyncOrders`	Create a batch of reward orders that will be processed asynchronously.

Use case

Acme Corp runs quarterly employee recognition and customer loyalty programs. Each cycle, they distribute hundreds of digital and physical rewards to recipients across different regions and departments. They use async order placement with this endpoint to submit reward orders with multiple line items in a single request. They can track delivery status via the GET /asyncOrders endpoints without exposing reward credentials while customizing delivery methods per recipient (email, SMS, physical mail). They can receive webhook notifications when orders are completed.

The following body parameters are used with this endpoint:

Body params	Data type	Requirement	Description
externalRefID	string	required	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.
customerIdentifier	string	required	Specifies the customer associated with the Order. Must be the customer that the `accountIdentifier` is associated with. The string must be 5-100 characters long.
accountIdentifier	string	required	Specifies the account from which this order will be deducted. The string must be 5-100 characters long.
sender	object	optional	Use to set the sender’s name and email address if they differ from the default platform setting. The sender overrides the default platform sender settings.
-firstName	string	optional	Always optional, string, 100 characters max
-lastName	string	optional	Always optional, string, 100 characters max
-email	string	optional	Always optional, string
campaign	string	optional	Campaign that may be used to group orders under a particular campaign. The maximum length is 1024 characters, including special characters such as @, #, %, etc.
purchaseOrderNumber	string	optional	Associates a purchase order number with the order. The string may have up to 100 characters.
notes	string	optional	Additional order-level notes. The string may have up to 150 characters.
lineItems	array	required	Contains the order details, including recipient, reward, and delivery method. At least one line item is required.
-externalRefLineItemID	string	required	Idempotent field for client-side line item cross-reference. The string may have up to 150 characters.
-recipient	object	required	Required if `sendEmail` is true. Use to set and store the recipient name and email address. When `sendEmail` is false, setting these parameters will allow the platform to store this information for reporting, auditing, and reconciliation.
-firstName	string	required	Required if `sendEmail` is true, or when ordering physical rewards. The `recipientFirstName` may have up to 100 characters for digital rewards. You cannot use < or > or / in the name. If a physical reward, it may have up to 25 characters, cannot be blank, and no mustache tag is allowed. Can use digits (0-9), alphabet (a-z, A-Z), space, period (.), comma (,), ampersand (&), and hyphen (-).
-lastName	string	required	Required for physical gift card, otherwise optional. The `recipientLastName` may have up to 100 characters for digital rewards. You cannot use < or > or / in the name. If a physical reward, it may have up to 25 characters, cannot be blank, and no mustache tag is allowed. Can use digits (0-9), alphabet (a-z, A-Z), space, period (.), comma (,), ampersand (&), and hyphen (-).
-email	string	required	Required if `sendEmail` is true, or deliveryMethod is EMAIL. The email address is limited to 100 characters.
-mobileNumber	string	required	Required if `deliveryMethod` is PHONE. The following validation rules apply to mobile numbers for SMS delivery: -Country code: Must be included. -Format: +CCCPPPPPPPPPPPP (where C is the country code, 1-3 digits, and P is the phone number, up to 12 digits). -Initial release: Only accepts US phone numbers (Country code = +1) and 10 digits for the phone number. -Standard: Follows ITU E.164, allowing (+) and up to 15 digits for the combined country code and phone number.
-address	object	required	Required for physical rewards. The following validation rules apply to addresses: -Physical rewards: Address is required. -Digital orders: Address field must be excluded or set to null. Providing an address for digital orders will result in validation failure. -❗️Disclaimer: When ordering a physical gift card, ensure the physical address of your reward recipients is validated before sending it to Tango. Tango does not accept responsibility for incorrect addresses. -NOTE: Do not pass an address object when the reward is digital.
-companyName	string	required	Required if deliveryMethod is ADDRESS, not applicable for digital rewards.
-streetLine1	string	required for physical rewards, not applicable for digital rewards	Recipient address object has the following validation rules: -Physical Rewards: Address is required. -Digital rewards: Address is not applicable. -Character limit: Address may have up to 35 characters. -Content: Address cannot be blank and can include digits (0-9), alphabet (a-z, A-Z), space, period, comma, hyphen, forward slash (/), ampersand (&), percent (%), pound (#), at (@), and apostrophe (').
-streetLine2	string	optional for physical rewards, not applicable for digital rewards	The following validation rules apply: -Physical rewards: Address is optional. -Digital rewards: Address is not applicable. -Character limit: Address may have up to 35 characters. -Content: Address cannot be blank and can include digits (0-9), alphabet (a-z, A-Z), space, period, comma, hyphen, forward slash (/), ampersand (&), percent (%), pound (#), at (@), and apostrophe (').
-city	string	required for physical rewards, not applicable for digital rewards	The following validation rules apply: -Physical rewards: Address is required. -Digital rewards: Address is not applicable. -Character limit: Address may have up to 30 characters. -Content: Address cannot be blank and can include digits (0-9), alphabet (a-z, A-Z), space, period, hyphen, ampersand (&), and apostrophe (').
-stateOrProvince	string	required for physical rewards, not applicable for digital rewards	The following validation rules apply: -Physical rewards: Address is required. -Digital rewards: Address is not applicable. -Address region: Must be a valid 2-character uppercase abbreviation for a US state, territory, or military base, a Canadian province, or contain an international region less than 36 characters.
-postalCode	string	required for physical rewards, not applicable for digital rewards	The following validation rules apply: -Physical rewards: Address is required. -Digital rewards: Address is not applicable. -Content: Address cannot be blank and may include digits (0-9) and alphabet (a-z, A-Z). -US addresses: Must include the five-digit US ZIP Code only.
-country	string	required for physical rewards, not applicable for digital rewards	-Physical rewards: Country is required. -Digital rewards: Country is not applicable. -Country: Must be a valid 2-character abbreviation
utid	string	required	The unique identifier for the reward you are sending, as provided in the Get Catalog call
amount	number	required	Specify the face value of the reward. Always needed, including for fixed value items.
deliveryMethod	string	required	Please specify the delivery method for your order. We have introduced various ways of reward delivery to your recipients through deliveryMethod: -NONE: You are responsible for delivering the rewards to your recipient. This option is similar to `sendEmail=false`. -EMAIL: Tango sends an email to deliver the rewards to your recipient. This option is similar to `sendEmail=true`. -PHONE: Tango sends SMS to deliver the rewards to your recipient. -ADDRESS: Tango delivers the physical rewards via carriers such as the post office, FedEx, UPS, etc. -EMBEDDED: You will embed Tango's landing page into your application.
deliveryDate	date	optional	Schedule delivery for a future date. Can schedule up to XX days in advance. The default is immediate delivery if the `deliveryDate` is NULL.
etid	string	optional	Template ID (ETID) is optional for email and mobile orders. In `POST {URI}/asyncOrders` if ETID is not provided, the system uses the default ETID configured in the following order: account, group, or platform level. If no default ETID is found, the standard template ID (E000000) is used. See Create digital templates.
ptid	string	conditional	Printed Reward Link Template identifier is used only for Printed Reward Links.
expirationDate	datetime	optional	The expiration date for Promo Links. Sets the exact calendar date the Promo Link will expire, following the ISO 8601 format. See the Promo Link acceptance criteria .
emailSubject	string	optional	If not specified, a default email subject will be used for the specified reward.
message	string	optional	Gift message. The string may have up to 1024 characters.
lineItemNote	string	optional	Optional line item notes (up to 150 characters)
shippingMethod	string	optional	It is used to specify how a reward should be shipped to the recipient.
phyiscalMethod	string	optional	Is used to specify the reward physical delivery.

*See the description for more information.

External reference ID

To prevent duplicate order submissions, added validation logic to the POST {URI}/asyncOrders endpoint to detect and block duplicate externalRefIDs . If the externalRefID was previously used in POST {URI}/Orders, the request fails with a descriptive error message. If the externalRefID was previously used in POST {URI}/asyncOrders , the endpoint returns the status of the existing order.

The following example illustrates the payload for using this endpoint and its parameters.

{
  "externalRefID": "string",
  "status": "string",
  "totalLineItems": 0,
  "createdAt": "2025-10-23T21:52:43.041Z",
  "failedLineItems": [
    {
      "lineItemId": "string",
      "externalRefLineItemID": "string",
      "utid": "string",
      "errors": [
        {
          "field": "string",
          "errorCodeValue": 0,
          "errorCodeName": "string",
          "message": "string"
        }
      ]
    }
  ],
  "duplicateLineItemRefIds": {
    "additionalProp": 0
  }
}

Here is the successful response example:

{
  "externalRefID": "ORDER-2025-001",
  "order": {
    "externalRefID": "ORDER-2025-001",
    "status": "pending",
    "totalLineItems": "2",
    "created_at": "2025-05-07T10:00:00Z"
  }
}

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.
201	A new resource has been successfully created in response to the request.
400	The server could not understand the request due to invalid syntax.
401	Authentication is required and has either not been provided or failed.
402	There are insufficient funds.
403	The server understood the request but refused to authorize it.
422	The server understands the request but cannot process it due to semantic errors.
429	Exceeded the allowable TPS rate limit. It indicates that the user has sent too many requests within a given time frame, and the server is rate-limiting further requests.
500	An error occurred on the server, but the server cannot provide a more specific description of the exact problem.
503	The server is currently unable to handle the request due to temporary overload or maintenance.