Create an order under a specific account

Use this endpoint to create a reward order under a specific account. After an order is successfully created, you can deliver the reward to the intended recipient using any supported delivery method, such as EMAIL, PHONE, ADDRESS, EMBEDDED, and more. See Delivery methods in Tango API for more information.

If you ever need to resend a reward, you can do so using the Resend a specific order endpoint. This operation sends the reward again to the same recipient information, but allows updating the email address or phone number used for delivery. Resends can also be issued through the same or a different delivery method. See Resend a specific order.

Use case

Acme Health, a wellness‑focused healthcare organization, uses the POST {URI}/orders endpoint to deliver digital rewards to members who complete specific health activities, such as, completing a health risk assessment. When a member qualifies for an incentive, Acme Health’s system automatically creates a reward order through the Tango API. The order includes a unique externalRefID, specifies the reward’s utid, and delivers it via email or SMS. The API responds with referenceOrderID and referenceLineItemID, which Acme Health uses for tracking, support, and resending rewards if needed.

Endpoint

Use the following endpoint to create an order under specific account.

Endpoint	Purpose
`POST {URI}/orders`	Create an order under a specific account.

📘
Note:

We use i18nKey responses to provide more specific error messages to Tango API users in order to get a clear, helpful feedback when something isn’t working. See i18nkey codes and their error messages.

The POST {URI}/orders endpoint has a 1 Transactions Per Second (TPS) rate limit. The rate limiting error can occur when you exceed the allowed number of requests per second. If you receive an error when placing an order, wait for 1 second and try again with the same externalRefID.

Include the externalRefID with the POST {URI}/orders endpoint to ensure duplicate orders are not created when you retry a failed order. If you submit POST orders with an externalRefID that already exists for the same account, the API does not create a duplicate order. Instead, it returns the existing order with status code 200 OK. Order requests receiving a 5XX error may occasionally process after a network connection is lost. See our Best practices topic regarding External Reference ID idempotent parameter.

Parameters

The following list are the body parameters to help you create an order under a specific account. The recipient address object is required for physical rewards only. If you include a recipient's mailing address in your order, the system assumes the item should be physically delivered and sets deliveryMethod = ADDRESS automatically. If no mailing address is provided, the system will use the specified deliveryMethod (like EMAIL or TEXT) or wait for you to define it. For digital (not physical) orders, the recipient address is excluded or set to null. See Delivery methods in Tango API for more information.

Body params	Data type	Requirement	Description
externalRefID	string	optional	Specifies a client-defined reference ID for the order. Use this value for idempotency, order cross-check, and duplicate-order prevention. The value is returned in order responses, order details, and order history.
customerIdentifier	string	required	Identifies the customer associated with the order. This value must match the customer associated with the specified `accountIdentifier`. The value must contain 5 to 100 characters.
accountIdentifier	string	required	Identifies the account from which the order is funded. The value must contain 5 to 100 characters.
utid	string	required	Tango unique template ID (UTID) identifies the reward being ordered. The UTID must be present in your platform catalog and returned by the Catalogs API. To retrieve available UTIDs, call the `GET {URI}/catalogs` endpoint.
deliveryMethod	string	required	Specifies how the reward is delivered to the recipient. Supported delivery methods vary by reward. See Delivery methods in Tango API for more information.
amount	double	required	Specifies the reward face value. This field is required, including for fixed-value rewards. The amount is stored as a double-precision floating-point number.
ptid	string	required	Identifies the printed reward template used for fulfillment. Required only for Printed Reward Links.
sender	object	optional	Provides sender information for the order. Use this object to override the default sender name and email configured for the platform. This information is used for reporting and tracking purposes and does not change the email address used for reward delivery. Do not use < or > or / in the name.
SENDER DETAILS OBJECT
sender.firstName	string	optional	Specifies the sender's first name. The value can contain up to 100 characters and cannot include , `>`, or `/`.
sender.lastName	string	optional	Specifies the sender's last name. The value can contain up to 100 characters and cannot include , `>`, or `/`.
sender.email	string	optional	Specifies the sender's email address.
recipient	object	required if	Provides recipient information for the order. Required when `deliveryMethod` is `EMAIL`, `PHONE`, `WHATSAPP` (🚧Coming soon) or `ADDRESS`. Recipient information may also be required for specific rewards. When `deliveryMethod` is `NONE` or `EMBEDDED`, recipient data can be provided for reporting, auditing, and reconciliation. See Delivery methods in Tango API.
RECIPIENT DETAILS OBJECT
recipient.firstName	string	required if	Specifies the recipient's first name. Required for physical deliveries and some reward types. Digital rewards allow up to 100 characters and do not permit , >, or /. Physical rewards allow up to 25 characters and support letters, numbers, spaces, commas, periods, ampersands, and hyphens. See Delivery methods in Tango API.
recipient.lastName	string	required if	Specifies the recipient's last name. Required if `deliveryMethod` is `ADDRESS`, otherwise optional. May be required for some UTIDs. Validation rules are the same as `recipient.firstName`.
recipient.email	string	required if	Specifies the recipient's email address. Required when`deliveryMethod=EMAIL`. May also be required for some UTIDs. The value can contain up to 100 characters.
recipient.mobileNumber	string	required if	Specifies the recipient's mobile phone number. Required when `deliveryMethod` is `PHONE` or `WHATSAPP` (when available). The value must be provided in E.164 format, including the country code. 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: Current only 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.
recipient.address	object	required if	Provides the recipient's mailing address. Required for physical deliveries and optional only when explicitly supported by a digital reward. Do not include this object for digital rewards unless required by the reward. The following 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.
RECIPIENT ADDRESS OBJECT
recipient.address.companyName	string	optional	Specifies the recipient's company name. Use when shipping to a business address.
recipient.address.streetLine1	string	required when `deliveryMethod` is `ADDRESS`	Specifies the primary or first address line for physical reward delivery. Omit it for digital rewards. Maximum 35 characters; cannot be blank. Allowed characters include letters, numbers, spaces, periods, commas, hyphens, forward slashes (/), ampersands (&), percent signs (%), number signs (#), at signs (@), and apostrophes.
recipient.address.streetLine2	string	optional when `deliveryMethod` is `ADDRESS`	Specifies additional or second address line, such as an apartment, suite, or unit number. Omit it for digital rewards. Maximum 35 characters; cannot be blank when provided. It supports the same characters as streetLine1 above.
recipient.address.city	string	required when `deliveryMethod` is `ADDRESS`	Specifies the city associated with the delivery 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.
recipient.address.stateOrProvince	string	required if when `deliveryMethod` is `ADDRESS`	Specifies the state, province, territory, or region associated with the delivery 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.
recipient.address.postalCode	string	required if when `deliveryMethod` is `ADDRESS`	Specifies the postal or ZIP code associated with the delivery address. Not applicable for digital rewards. Allows 5 to 10 characters, not blank, Digits 0-9, and alpha (a-z, A-Z). For US addresses, this must include only the five-digit US ZIP Code.
recipient.address.country	string	required if when `deliveryMethod` is `ADDRESS`	Specifies the country associated with the delivery address. Not applicable for digital rewards. Must be a valid 2-character abbreviation
emailSubject	string	optional	Specifies the email subject for rewards delivered with `deliveryMethod` set to `EMAIL`. If omitted, the API uses the email subject configured in the selected electronic template (`etid`).
message	string	optional	Specifies the gift message included with the reward. The value can contain up to 1,024 characters.
etid	string	optional	Identifies the Template ID (ETID) used for rewards delivered when `deliveryMethod` is `EMAIL` or `PHONE`. If you omit `etid`, the API uses the default Template ID configured for the account, then the group, then the platform. If no default Template ID is configured, the system uses `E000000`.
campaign	string	optional	Specifies the campaign used to group related orders. The value can contain up to 1,024 characters, including special characters such as `@`, `#`, and `%`.
purchaseOrderNumber	string		Specifies the purchase order number associated with this order. The value can contain up to 100 characters.
notes	string	optional	Specifies internal notes associated with the order. The value can contain up to 150 characters.
expirationDate	date-time	optional	Specifies the calendar date and time when a Promo Link expires. This field applies only to Promo Links and must use the `date-time` format. See the Promo Link acceptance criteria.

*See the description for more information.

What is Reference line item ID?

The referenceLineItemID in the Tango API is a unique identifier for a specific line item within an order. It's included in the response payload to uniquely identify a reward transaction or line item. With referenceLineItemID , there's no need to use a GET endpoint call to retrieve such info.

For example, if a reward is sent to the wrong email address, you can use the referenceLineItemID to locate the specific reward and resend it to the correct email using the appropriate endpoint.

📘
Note:

For single-item orders, just return the one referenceLineItemID.

For multi-item orders, the API returns the line item associated with lineNumber == 1.

The referenceLineItemID is used to:

Update line item details such as campaign name, purchase order number, and notes using PATCH /lineItems/{referenceLineItemID}.
Retrieve line item information using GET /lineItems/{referenceLineItemID}.
Manage reward actions, such as canceling, freezing, unfreezing, or reissuing a reward using the corresponding cancel and reissue endpoints.

What is Credential list?

The credentialList is a collection of reward attributes returned in the response payload that describe how a recipient can redeem their reward. Each item includes details such as the credential type, label, value, and other stable parameters. See how you can Get credential type.

The credentialList helps your system understand how to display or deliver the reward. It supports multiple formats to accommodate different reward types and enables customized redemption experiences—for example, branded redemption pages using customUrl.


"credentialList": [
  {
    "label": "Redemption Link",
    "value": "https://rewards.example.com/redeem?user=abc123",
    "type": "url",
    "credentialType": "customUrl"
  }
]
``

📘
Note:
credentials is deprecated and should no longer be used. Use credentialList instead.

Examples

The following example illustrates the payload for using this endpoint and the body parameters. The delivery method, delivery status and other delivery details are included in the payload.

{
  "referenceOrderID": "string",
  "referenceLineItemID": "string",
  "externalRefID": "string",
  "customerIdentifier": "string",
  "accountIdentifier": "string",
  "amountCharged": {
    "value": 0,
    "currencyCode": "string",
    "exchangeRate": 0,
    "fee": 0,
    "total": 0
  },
  "denomination": {
    "value": 0,
    "currencyCode": "string",
    "exchangeRate": 0,
    "fee": 0,
    "total": 0
  },
  "utid": "string",
  "ptid": "string",
  "rewardName": "string",
  "reward": {
    "credentials": {
      "additionalProp": "string"
    },
    "credentialList": [
      {
        "label": "string",
        "value": "string",
        "type": "string",
        "credentialType": "string"
      }
    ],
    "redemptionInstructions": "string"
  },
  "sender": {
    "firstName": "string",
    "lastName": "string",
    "email": "string"
  },
  "recipient": {
    "firstName": "string",
    "lastName": "string",
    "email": "string",
    "mobileNumber": "string",
    "address": {
      "companyName": "string",
      "streetLine1": "string",
      "streetLine2": "string",
      "city": "string",
      "stateOrProvince": "string",
      "postalCode": "string",
      "country": "string"
    }
  },
  "emailSubject": "string",
  "message": "string",
  "deliveryMethod": "NONE",
  "status": "string",
  "campaign": "string",
  "purchaseOrderNumber": "string",
  "createdAt": "2025-11-03T23:25:29.857Z",
  "redemptionInstructions": "string"
}

Here is a payload example for when you use POST {URI}/orders to create an order with Promo link. You can set an expiration date for the Promo Link at the time of the order:

📘
Note:
Expiration date only applies to Promo Links.

{
  "referenceOrderID": "string",
  "externalRefID": "string", (100 chars)
  "customerIdentifier": "string", (5-100 chars)
  "accountIdentifier": "string", (5-100 chars)
  "accountNumber": "string", (5-100 chars)
  "amountCharged": {
    "value": 10.00,
    "currencyCode": "USD",
    "total": 10.0
  },
  "denomination": {
    "value": 10.0,
    "currencyCode": "USD"
  },
  "utid": "string",
  "rewardName": "Promo Link",
  "sender": {
    "firstName": "string",
    "lastName": "string",
    "email": "string"
  },
  "recipient": {
    "email": "string",
    "firstName": "string", (100 chars)
    "lastName": "string", (100 chars)
    "address": null
  },
  "sendEmail": false,
  "status": "COMPLETE",
  "createdAt": "2023-10-11T23:10:55.284Z",
  "reward": {
    "credentials": {
      "redemptionUrl": "https://gamma.rewardlink.io/r/1/Cl4e2dX_qz3zyUbSTb4dZgrbQta9qg-oBd6sPkywiIk",
      "expirationDate": "2024-12-31T06:59:59Z"
    },
    "credentialList": [
      {
        "label": "redemptionUrl",
        "value": "https://gamma.rewardlink.io/r/1/Cl4e2dX_qz3zyUbSTb4dZgrbQta9qg-oBd6sPkywiIk",
        "type": "url",
        "credentialType": "redemptionUrl"
      },
      {
        "label": "expirationDate",
        "value": "2024-12-31T06:59:59Z",
        "type": "date",
        "credentialType": "expirationDate"
      }
    ],
    "redemptionInstructions": "string"
  }
}

Here's a payload example for a 422 (Unprocessable entity) response, including i18nkey for internationalization. The 422 response is returned when you try to place an order with a frozen account.

{
  “timestamp”: “2025-01-15T19:12:42.059287141Z”,
  “requestId”: “08f50da4-aa93-40ba-968d-375b76085af6",
  “path”: “/raas/v2/orders”,
  “httpCode”: 422,
  “httpPhrase”: “Unprocessable Entity”,
  “errors”: [
    {
      “code”: 422001,
      “i18nKey”: “404.142”,
      “message”: “Account has been frozen, please contact your Tango CSM or email [email protected]”
    }
  ]
}

📘
Note:
An account may be frozen when detecting a fraudulent activity. Reach out to [email protected] or dial 1 (855)-257-2581 should you notice any fraudulent activity on your account.

Response body

On a successful request (200 OK), the response body includes several important fields. Below are key notes and considerations to help you understand field behaviors and best practices:

credentialList may contain multiple credential objects depending on reward type (e.g., code + PIN, URL + instructions). Your integration should not assume a single credential.
Some credential entries may include customUrl or HTML-formatted instructions. Ensure your UI safely handles these formats.
The externalRefID is returned exactly as provided. Use it to safely retry failed order requests without creating duplicates.
referenceOrderID uniquely identifies the order.
referenceLineItemID uniquely identifies the reward within the order and is required for: Resending, Canceling, Freezing/unfreezing, Reissuing, and Updating metadata (campaign, PO number, notes).
deliveryMethod reflects how the reward was actually delivered. Example: EMAIL, PHONE, ADDRESS, EMBEDDED, etc.
The address field appears only for rewards that require physical shipping. If deliveryMethod = ADDRESS, ensure your system handles the necessary address fields.
The top-level redemptionInstructions is provided for convenience. However, detailed instructions may also appear per‑credential within credentialList.
amountCharged represents the billed amount (including fees, currency conversion, and exchange rate). denomination represents the reward value to the recipient. These may differ depending on markup, program rules, or exchange rates.
createdAt follows ISO 8601 format (such as 2013-02-21T20:37:07-07:00) and is always returned in Coordinated Universal Time (UTC).

Response codes

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

Response	Description
200	The request was successful. This also means that an order with the given `externalRefId` exists for the account, so the existing order is returned instead of creating a new one.
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	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.