Manage orders

Tango's API allows you to automate and manage reward orders—whether you're sending digital gift cards, physical items, or using custom delivery methods like text messages. Using the Tango API, you can send rewards to recipients, get the list of orders placed under your platform, and resend digital rewards.

See how to Create an order under a specific account in Tango API. Once you create an order, you can retrieve order information using GET {URI}/orders/{referenceOrderId} . See how to Get details for a specific order.

Reward delivery methods

The reward delivery method, such as EMAIL, PHONE, etc. is used to specify how a reward should be delivered to the recipient. Tango uses deliveryMethod to deliver rewards. deliveryMethod is replacing the legacy sendEmail for more flexibility and clarity. If deliveryMethod is not provided, but a recipient address is present, the API sets the deliveryMethod=ADDRESS before processing the order. Some digital cash options may still require a physical address. If deliveryMethod is ADDRESS, then the system expects a valid physical address to fulfill the order.

❗️
Important:
To activate the text messages or mobile reward delivery feature on your platform, you must sign the Mobile Delivery Addendum through the Tango portal and confirm your organization's agreement to comply with government protection regulations. The text delivery feature is disabled by default.

When you resend a previously placed reward order using the API, you can change how the reward is delivered. For example, you can switch from EMAIL to PHONE. To learn more about resending rewards, see Resend a specific order.

📘
Note:

deliveryMethod is now used instead of the sendEmail parameter to provide a more flexible approach. If an original order was delivered via EMAIL, you can choose to resend using PHONE.

Mobile reward delivery only works with some unique Tango identifiers (UTIDs). Each UTID includes attributes such as EMAIL, PHONE, etc., indicating supported delivery methods. A UTID is eligible for text delivery only if its attribute includes PHONE.

We support the following delivery methods in Tango:

Delivery method	Description
None	Tango does not deliver the reward in this mode. You are responsible for delivering the reward to the recipient. This behavior is equivalent to setting `sendEmail=false`.
Email	Tango delivers the reward to the recipient via email when `deliveryMethod` is set to Email. In this case, the `recipient.email`field is required. Note:* The legacy `sendEmail=true` flag has previously controlled this behavior. However, `sendEmail` is now deprecated and replaced with `deliveryMethod` field. `sendEmail` only appears in the payload.
Phone	Tango delivers the reward to the recipient via text when the `deliveryMethod` is set to PHONE. The `recipientMobileNumber` is required if `deliveryMethod=PHONE`. The following validation rules apply to mobile numbers for PHONE 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 US phone numbers are supported: (Country code is +1 and 10 digits for the phone number.) -Standard compliance: Follows ITU E.164, allowing a maximum of 15 digits including the + sign..
Address	Tango delivers the physical rewards via the post office. You must include the recipient address. When ordering a physical gift card, validate the physical address of your reward recipients before sending it to Tango. Tango does not accept any responsibility for incorrect addresses.
Embedded	Embed Tango's landing page into your application. Tango will not deliver the rewards.
Bulk shipment🚧 (Coming soon)	Send a batch of physical rewards to Tango for delivery. You must provide a validated list of recipient addresses. Tango will handle the shipping via carriers, but is not responsible for incorrect or incomplete address information.

🚧
Coming soon:
Including an address for digital orders may result in a validation error. However, this will soon change for you to be able to include a physical address with your digital order.

Order status

The order status indicates the current state of a reward order. The order status helps you track whether a reward has been successfully processed, pending, or encountered an issue. An order status affects all rewards in the order.

Here are the available statuses in the Tango API for orders:

Status	Description
Complete	The order has been processed, and the reward associated with it has been sent. See line item status.
Pending	The order needs a little longer to process. Pending orders should be processed and delivered within one (1) business day. Orders placed on Friday afternoon or over the weekend may be processed on the following Monday or the next business day. Once the order is delivered, its status changes to Complete. Note: * Your order may take longer to review for a variety of reasons. See why your order is being reviewed. Contact your Customer Success Manager (CSM) or [email protected] with questions or concerns. To open a support case with Tango, use the Chat agent at the bottom right of the screen.
Failed	The order can not be sent. Your account is refunded for the total value of the order. Place the order again to ensure your reward is sent. For more information on why your order is failed, see the Tango Reward Status page, or email your Customer Success Manager (CSM) or [email protected] . Please ensure that you include the Reference Order ID of your failed order.

Status

Description

Complete

The order has been processed, and the reward associated with it has been sent. See line item status.

Pending

The order needs a little longer to process. Pending orders should be processed and delivered within one (1) business day. Orders placed on Friday afternoon or over the weekend may be processed on the following Monday or the next business day. Once the order is delivered, its status changes to Complete.

*Note: ** Your order may take longer to review for a variety of reasons. See why your order is being reviewed. Contact your Customer Success Manager (CSM) or [email protected] with questions or concerns. To open a support case with Tango, use the Chat agent at the bottom right of the screen.

Failed

The order can not be sent. Your account is refunded for the total value of the order. Place the order again to ensure your reward is sent.

For more information on why your order is failed, see the Tango Reward Status page, or email your Customer Success Manager (CSM) or [email protected] . Please ensure that you include the Reference Order ID of your failed order.