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.

📘
Note:

Order requests receiving a 5XX error may occasionally process after a network connection is lost. We strongly recommend you use the externalRefID idempotent parameter to ensures duplicate orders are not created when you retry a failed order. See our Best practices topic regarding External Reference ID idempotent parameter.

Digital orders do not require a shipping address. Including an address for digital orders will result in a validation error.

🚧
Coming soon:
This endpoint will soon be modified to include body parameters: deliveryMethod and recipient's MobileNumber . Once released, you can deliver rewards to your recipients using delivery methods such as SMS, CARRIER, and EMBEDDED besides EMAIL.

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 `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 {URI}/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	*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.
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	optional	always optional, string, 100 characters max
-lastName	string	optional	always optional, string, 100 characters max
-email	string	optional	always optional, string
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, 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, 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 up to 100 characters max.
-MobileNumber (🚧 Coming soon)	string	*required	Required if `deliveryMethod` is SMS. 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.
-streetLine1	string	*required	The following validation rules apply: -Physical Rrewards: 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	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	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	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	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	-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.
sendEmail	boolean	-	Specify if sendEmail is true or false, in other words, will Tango send the email to recipients? -Tango does not deliver the reward email when `sendEmail=false`. When placing orders, you are responsible for delivering rewards if `sendEmail=false`. -🚧 Coming soon: `sendEmail` will be deprecated soon. It will only appear in the payload once the `deliveryMethod` parameter is released.
deliveryMethod (🚧 Coming soon)	string	-	Specify delivery method for the order. We have introduced various ways of reward delivery to your recipients through deliveryMethod: -NONE: You are responsible to deliver the rewards to your recipient. This option is similar to `sendEmail=false`. -EMAIL: Tango sends email to deliver the rewards to your recipient. This option is similar to `sendEmail=true`. -SMS: Tango sends SMS to deliver the rewards to your recipient. -CARRIER: Tango delivers the rewards via physical carriers such as the post office, FexEx, UPS, etc. -EMBEDDED: You will embed Tango's lading page into your application.
etid	string	optional	ETID is the unique identifier for the email template you would like to use. Only applicable if `sendEmail=true`.
campaign	string	optional	Campaign may be used to administratively categorize a specific Order. The string may have up to 100 characters.
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.

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:
credentials is deprecated and should no longer be used. Use credentialList instead.

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

Create an order under a specific account

📘
Note:

🚧
Coming soon:

📘
Note:

📘
Note:

📘
Note:

📘Note:

🚧Coming soon:

📘Note:

📘Note:

📘Note:

📘
Note:

🚧
Coming soon:

📘
Note:

📘
Note:

📘
Note: