Create an order under a specific account

externalRefID

string

optional

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.

customerIdentifier

string

required

Specify the customer associated with the Order. This must be the same customer associated with the accountIdentifier . 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.

utid

string

required

The unique identifier for the reward you are sending, as provided in the GET {URI}/catalogs call. The UTID must be in your platform catalog (and not just in a Tango Choice product catalog) to place the order.

deliveryMethod

string

required

Specify the delivery method 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.

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 deliveryMethod=EMAIL. You cannot use < or > or / in the name.

SENDER DETAILS OBJECT

-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 if

Required if deliveryMethod is set to EMAIL, PHONE, or ADDRESS. May be required for some UTIDs. Use to set and store the recipient name and email address. When deliveryMethod is set to NONE and EMBEDDED, setting these parameters will allow the platform to store this information for reporting, auditing, and reconciliation.

RECIPIENT DETAILS OBJECT

-firstName

string

required if

Required if deliveryMethod is EMAIL, PHONE, or ADDRESS. 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.

-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 deliveryMethod=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=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: 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 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 including an address. 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.

RECIPIENT ADDRESS OBJECT

companyName

string

optional

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

emailSubject

string

optional

Used with deliveryMethod is EMAIL. The ETID email subject will be used for the specified reward if not specified.

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. Used with deliveryMethod of EMAIL or PHONE. The unique identifier for the electronic template you would like to use. In POST {URI}/orders if ETID is not provided, the system uses the default ETID configured at either the account, group, or platform level, in that order. If no default ETID is found, E000000 is used.

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.