Create an order under a specific account
Use the following endpoint to create a reward order under a specific account. Once the reward order is created, you can send it to a recipient using a supported delivery method, such as EMAIL, PHONE, ADDRESS, and EMBEDDED, etc. Learn more about Reward delivery methods.
If you need to resend the reward, use our Resend endpoint to send the reward to the original recipient but a different email address or phone number. Resend an email or text via the same or different method of delivery using POST /orders/{referenceOrderID}/resends. See Resend a specific order.
| Endpoint | Purpose |
|---|---|
POST {URI}/orders | Create an Order under a specific Account. |
Note:
- The
POST {URI}/ordersendpoint has a 1 TPS rate limit. If you receive an error when placing an order, wait for 1 second and try again with the sameexternalRefID.- We highly recommend including the
externalRefIDwith the POST order endpoint to ensure duplicate orders are not created when you retry a failed order. 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.
Here is a list of body parameters to help you create an order under a specific account. The recipient address object is required for physical rewards only. For digital orders, the recipient address must be excluded or set to null.
Body params | Data type | Requirement | Description |
|---|---|---|---|
externalRefID | string | optional | An idempotent field that can be used for your order cross-reference and to prevent accidental order duplication. This value is returned in 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 |
accountIdentifier | string | required | Specify the account from which this order will be deducted. The string must be 5-100 characters long. |
utid | string | required | The unique identifier for the reward you are sending, as provided in the |
deliveryMethod | string | required | Please specify the delivery method for your order. We have introduced various ways of reward delivery to your recipients through deliveryMethod:
|
amount | double | required | Specify the face value of the reward. Always required, including for fixed-value items. The amount is stored as a double-precision floating-point number. |
ptid | string | required | Only required for Printed Reward Links. PTID is a unique identifier for the Printed Reward Link Template provided in the Tango portal on the Printed Template page. |
sender | object | optional | Use to set the sender’s name and email address if they differ from the default platform setting. This information is for tracking purposes only and doesn’t change the email address the reward is sent from when |
SENDER DETAILS OBJECT | |||
-firstName | string | optional | always optional, string, 100 characters max |
-lastName | string | optional | always optional, string, 100 characters max |
string | optional | always optional, string | |
recipient | object | required | Required if |
RECIPIENT DETAILS OBJECT | |||
-firstName | string | required | Required if |
-lastName | string | required | Required for a physical gift card when |
string | required | Required if | |
-mobileNumber | string | required | Required if -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. |
-address | object | required | Required for physical rewards if -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. |
RECIPIENT ADDRESS OBJECT | |||
companyName | string | optional | Typically used when shipping to a corporate address. |
-streetLine1 | 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 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 |
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. |
etid | string | optional | Template ID (ETID) is optional for email and mobile orders. In |
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 | The Purchase Order Number associated with this order. The string may have up to 100 characters. | |
notes | string | optional | Order notes. The string may have up to 150 characters. |
expirationDate | date-time | optional | This is optional for Promo Links; the exact calendar date the Promo Link will expire. See the Promo Link acceptance criteria. |
*See the description for more information.
Reference line item ID
referenceLineItemID in the Tango API is a unique identifier for a specific line item within an order. It's been included in the return 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. When a reward is sent to the wrong email address, you can use the referenceLineItemID to locate the reward and resend to the correct email using the appropriate endpoint.
**Note: **
For single-item orders, just return the one
referenceLineItemID. But, for multi-item orders, the API returns the first line item, the one with lineNumber == 1.
referenceLineItemID is used to:
- Update line item details such as campaign name, purchase order number, and notes via
PATCH /lineItems/{referenceLineItemID}. - Retrieve line item information using
GET /lineItems/{referenceLineItemID}. - Perform actions like cancel, freeze, unfreeze, or reissue a reward using cancel and reissue endpoints.
Credential list
credentialList is a list of reward details or attributes that are returned in the payload and show how the user can redeem their reward. credentailList contains credential type, label, value, and other stable parameters. We no longer use credentials . See how to Get credential type.
credentialList tells your system how to display or deliver the reward. It supports multiple formats, making it flexible for different reward types, and enables custom experiences, like branded redemption pages via customUrl.
"credentialList": [
{
"label": "Redemption Link",
"value": "https://rewards.example.com/redeem?user=abc123",
"type": "url",
"credentialType": "customUrl"
}
]
``
Note:
credentialsis deprecated and should no longer be used. UsecredentialListinstead.
Payload example
The following example illustrates the payload for using this endpoint and its body parameters.
{
"referenceOrderID": "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-10-23T21:52:43.041Z",
"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.
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. |
| 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. |
Updated 5 days ago
