Create an order under a specific account
Use the following endpoint to create an order under a specific account. The POST {URI}/orders endpoint has a 1 TPS rate limit. If you receive an error when placing an order, wait for 1 second and try again with the same externalRefID.
| Endpoint | Purpose |
|---|---|
POST {URI}/orders | Create an Order under a specific Account. |
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.
Note:
Providing an address for digital orders will result in validation failure.
| Body params | Data type | Description |
|---|---|---|
| externalRefID | string | (Optional) An idempotent field that can be used for client-side Order cross reference and prevent accidental order duplication. Will be returned in order response, order details, and order history. This string has a maximum of 100 alphanumeric characters. |
| customerIdentifier | string | (Required) Specify the customer associated with the Order. Must be the customerIdentifier the accountIdentifier is associated with.The string must have 5-100 characters. |
| accountIdentifier | string | (Required) Specify the account this order will be deducted from. The string must have 5-100 characters. |
| utid | string | (Required) The unique identifier for the reward you are sending as provided in the GET /catalogs endpoint. The UTID must be in your platform catalog (and not just in a Tango Choice product catalog) to place the order. |
| ptid | string | Only required when ordering a Printed Reward Link. Ptid is a unique identifier for the Printed Reward Link Template provided in the Tango Portal on the Printed Template page. |
| 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. |
| sender | object | (Optional) Use to set the sender’s name and email address if different than the default platform setting. This information is for tracking purposes only and doesn’t change the email address the reward is sent from when sendEmail: true. You cannot use < or > or / in the name. |
| -firstName | string | always optional, string, 100 characters max |
| -lastName | string | always optional, string, 100 characters max |
| string | always optional, string | |
| recipient | object | 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 if sendEmail is true, or ordering a physical reward. 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 and can use Digits 0-9, alpha (a-z, A-Z), space period, comma, or hyphen. |
| -LastName | string | Required if ordering a physical gift card, for digital rewards it is optional. The recipientLastName may have up to 25 characters for physical, or 100 characters for digital. You cannot use < or > or / in the name. If a physical reward, it may include Digits 0-9, alpha (a-z, A-Z), space period, comma, or hyphen. |
| string | Required if sendEmail is true. (100 characters max). | |
| -address | object | Required for physical rewards. For digital orders, this 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, make sure to validate the physical address of your reward recipients before sending it to Tango. Tango does not accept any responsibility for the incorrect addresses. NOTE: Do not pass an address object when the reward is digital. |
| -streetLine1 | string | Required for physical rewards, not applicable for digital rewards (35 characters max). May include Digits 0-9, alpha (a-z, A-Z), space, period, comma, hyphen, forward slash (/), and apostrophe |
| -streetLine2 | string | (Optional) for physical rewards, not applicable for digital rewards (35 characters max). May include Digits 0-9, alpha (a-z, A-Z), space, period, comma, hyphen, forward slash (/), and apostrophe |
| -city | string | Required for physical rewards, not applicable for digital rewards (30 characters max). May include Digits 0-9, alpha (a-z, A-Z), space, period, hyphen, and apostrophe |
| -stateOrProvince | string | Required for physical rewards, not applicable for digital rewards (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 for physical rewards, not applicable for digital rewards may include 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 for physical rewards, not applicable for digital rewards (2 characters). |
| 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 3000 characters. |
| sendEmail | boolean | (Required) Should Tango send the email to the recipient? |
| etid | (Optional) Etid is the unique identifier for the email template you would like to use. Only applicable if sendEmail is true. | |
| campaign | string | (Optional) Campaign may be used to administratively categorize a specific Order. The string may have up to 100 characters. |
| purchaseOrderNumber | string | (Optional) 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. |
We use credentailList instead of credentials . credentailList is a set of attributes that is returned on an order specifying how to access the purchased reward. credentailList contains credential type, label, value, and other stable parameters. See how to Get credential type.
Note:
credentialsis deprecated and should no longer be used. UsecredentialListinstead.
The following example shows the payload for when you use this endpoint and the body parameters above. Perform a call to order one of the UTIDs that's returned in your GET {URI}/catalogs call.
{
"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": {
"email": "string",
"firstName": "string",
"lastName": "string",
"address": {
"streetLine1": "string",
"streetLine2": "string",
"city": "string",
"stateOrProvince": "string",
"postalCode": "string",
"country": "string"
}
},
"emailSubject": "string",
"message": "string",
"sendEmail": true,
"status": "string",
"campaign": "string",
"purchaseOrderNumber": "string",
"createdAt": "2023-10-12T16:28:34.439Z",
"redemptionInstructions": "string"
}
Here is a payload example for when you use POST {URI}/orders to create an order with Promo link. You can set expiration date for 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 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:
- 200 Ok
- 201 Created
- 400 Bad Request
- 401 Unauthorized
- 402 Insufficient Funds
- 403 Forbidden
- 422 Unprocessable entity
- 429 Exceeded the allowable TPS rate limit (Wait 1 second and try again)
- 503 Service Unavailable
Updated about 1 month ago