Create an order under a specific account

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 PHONE. 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 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.

sendEmail

boolean

Specify whether sendEmail is set to 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

required

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.
-PHONE: Tango sends SMS to deliver the rewards to your recipient.
-ADDRESS: Tango delivers the physical rewards via 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 that may be used to group orders under a particular campaign. The maximum length is 1024 characters including the 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.