Create async orders

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	Specify 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	Specify 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 that can be used for client-side order line item cross reference and used to map failed and success line items on client side. The string may have up to 150 characters.
-recipient	object	required	Required if `deliveryMethod` is EMAIL, PHONE, or ADDRESS. May be required for some UTIDs. Use to set and store the recipient’s contact information. When `deliveryMethod` is NONE or EMBEDDED, setting these parameters will allow the platform to store this information for reporting, auditing, and reconciliation. Per new validation rules: The recipient object is required when `deliveryMethod` is EMAIL, PHONE, or ADDRESS (because these methods need recipient info). The recipient object is optional when `deliveryMethod` is NONE or EMBEDED.
-firstName	string	required if	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 if	Required if `deliveryMethod` is ADDRESS, otherwise optional. May be required for some UTIDs. Digital rewards: allows 100 characters, cannot use < or > or / in the name. Physical rewards: allows 25 characters max, Digits 0-9, alpha (a-z, A-Z), space period, comma, ampersand, and hyphen.
-email	string	required if	Required if `sendEmail` is true, or `deliveryMethod` is EMAIL. May be required for some UTIDs. It is useful to include when `deliveryMethod` is PHONE to easily switch between email and phone delivery. The email address is limited to 100 characters.
-mobileNumber	string	required if	Required if `deliveryMethod` is PHONE. May be required for some UTIDs. 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 if	Required if `deliveryMethod` is ADDRESS. May be required for some UTIDs. This field is optional for digital orders. NOTE: Some digital cash options may require an address. The following validation rules apply to addresses: 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.
-companyName	string	optional	Optional, Typically used when shipping to a corporate address.
-streetLine1	string	required if	Required if `deliveryMethod` is ADDRESS, not applicable for digital rewards. Allows 35 characters max, not blank, Digits 0-9, alpha (a-z, A-Z), space, period, comma, hyphen, forward slash (/), ampersand, percent, pound (#), at (@), and apostrophe.
-streetLine2	string	optional if	Optional if `deliveryMethod` is ADDRESS, not applicable for digital rewards. Allows 35 characters max, not blank, Digits 0-9, alpha (a-z, A-Z), space, period, comma, hyphen, forward slash (/), ampersand, percent, pound (#), at (@), and apostrophe.
-city	string	required if	Required if `deliveryMethod` is ADDRESS, not applicable for digital rewards. Allows 30 characters, not blank, Digits 0-9, alpha (a-z, A-Z), space, period, hyphen, ampersand, and apostrophe.
-stateOrProvince	string	required if	Required if `deliveryMethod` is ADDRESS, not applicable for digital rewards. Address region must be a valid 2-character uppercase abbreviation for a U.S. state, territory, or military base; a Canadian province; or contain an international region less than 36 characters.
-postalCode	string	required if	Required if `deliveryMethod` is ADDRESS, not applicable for digital rewards. Allows 5 characters, not blank, Digits 0-9 and alpha (a-z, A-Z). For US addresses this must include the five digit US ZIP Code only.
-country	string	required if	Required if `deliveryMethod` is ADDRESS, not applicable for digital rewards. 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	Specify the `deliveryMethod` 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	Specify the date to deliver the reward to the recipient. It must be at least 7 days in the future. If not specified, the reward will be immediately send.
etid	string	optional	Used with `deliveryMethod` of EMAIL or PHONE. The unique identifier for the electronic template you would like to use. If not specified, the system will use the default etid. 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	required if	Printed Reward Link Template identifier is used only for Printed Reward Links. It's provided in the Tango Portal on the Printed Template page.
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 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)
(🚧coming soon) shippingMethod	string	optional	It is used to specify how a reward should be shipped to the recipient.
(🚧coming soon) 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.