Manage line items
Each line item represents a single gift card, reward, disbursement, or promotional link. A line item contains details about the issued reward—such as the reward brand, unique ID, and value—and may also include recipient information like first name, last name, and email address.
Line items are managed individually, which is especially helpful when a single reward encounters a delivery issue (e.g., an undeliverable email or an incorrect recipient name). An order can contain one or more line items.
Note:Orders and line items include sensitive information such as Personally Identifiable Information (PII). PII must be used for internal logging and support only. To protect your users, do not reveal the orders and rewards sensitive information to any other user except the reward recipient.
Delivery methods
deliveryMethod is a parameter set at the line item level for each individual reward within an order. It allows different items in the same order to use different delivery methods. deliveryMethod is replacing the legacy sendEmail for more flexibility and clarity. sendEmail only appears in the payload.
If the delivery method 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. With Resend you can switch delivery method from one type to another, for example, from email to phone, etc.
The following delivery methods are available in Tango API:
Delivery method | Description |
|---|---|
NONE | Tango does not deliver the rewards. You are responsible to deliver them to your recipient. This option is similar to |
Tango delivers the reward to the recipient via email. You must include the recipient email. This option is similar to | |
PHONE | Tango delivers the reward to the recipient via text message. You must include the recipient phone number. The following validation rules apply:
|
ADDRESS | Tango delivers the physical rewards via a carriers such as the post office, FedEx, UPS, etc. You must include the recipient address. |
EMBEDDED | You must embed Tango's lading page into your application for the rewards to be delivered via embedded page. |
EMBEDDED_COMPONENT | This is designed specifically for BHN MyPrepaidCenter cards. They support integration directly within a customer’s application through an embeddable widget, a capability that is unique to this product line. |
BULKSHIPMENT | (🚧 Coming soon) Tango provides Bulk Shipment feature for sending physical gift cards in large quantities. |
BULKDIGITAL | (🚧 Coming soon) Tango allows sending bulk digital rewards (via email or mobile) to up to 50,000 recipients per order using Tango’s bulk upload templates. |
(🚧 Coming soon) Tango delivers the reward to recipients via WhatsApp application. The following validation rules apply:
| |
QRCODE | (Tango portal only) Tango delivers rewards with QR code. QR code must be enabled for your platform first, but it can only be sent via Tango portal. You can use GET to get a list of rewards via Tango API. See Send rewards with QR code to learn how to send eligible rewards with QR code. |
Important activation requirements:
- Mobile (text) delivery requires signing the Mobile Delivery Addendum in the Tango portal and confirming compliance with applicable regulations. The text delivery feature is disabled by default. You must have Entire organization access and Platform settings permission. See Enable mobile reward delivery.
- QR Code deliverymust be enabled at the platform level. To access platform settings and enable QR code delivery, you must have Entire organization access and Platform settings permission. See Enable QR code reward delivery.
Note:
- Not all UTIDs support all delivery methods. A UTID must include the PHONE attribute to be eligible for text delivery.
- 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.
- The legacy
sendEmail=trueflag has previously controlled this behavior. However,sendEmailis now deprecated and replaced withdeliveryMethodfield.sendEmailonly appears in the payload. If an original reward was delivered via EMAIL, you can choose to resend using PHONE or QR code. To learn more about resending rewards, see how to Resend a line item.
Delivery status
Delivery status tracks the physical and digital transport of the reward to the recipient. Think of it as shipment tracking which tracks how the reward reaches the recipient. Delivery status is separate from order fulfillment. A line item can be COMPLETE (reward generated) but delivery status FAILED (couldn't reach recipient), in which case you'd need to resend using the corrected delivery details.
When delivery fails, you don't lose the reward or your funds. The reward still exists. You resend it using corrected recipient details (new email, phone, or address). Use the Resend line items endpoint to redeliver with updated information.
The following delivery statuses are available in Tango API:
| Delivery status | Description |
|---|---|
| PENDING | The reward in not shipped yet. It's ready but hasn't been sent, or it's waiting to start delivery. For example a package is sitting in the warehouse. |
| PROCESSING | The reward is currently shipping. It's being actively sent right now. For example: an email is being sent, text message is going out, or the package is on the delivery truck. |
| DISPATHCED | The reward is shipped, but not confirmed. For example: the reward is sent to the recipient's email server/phone carrier, it's on its way but not confirmed delivered yet, or it's "out for delivery" tracking status. |
| DELIVERED | The reward is confirmed received. It's successfully arrived at recipient's inbox/phone and the recipient has access to the reward now. It's like you get a "package delivered" confirmation. |
| FAILED | The reward couldn't deliver. The email has bounced back or the phone number is invalid. Something went wrong with delivery such as "undeliverable address" return. |
Line item status
Line item status tracks whether a reward was successfully created and provisioned. Once the reward is generated, the line item's job is done—the reward then has its own separate lifecycle. See Reward status. Use the line item status query parameter to filter orders by the status of their individual line items. Note that this parameter is different from the order status parameter. Line item status refers to the status of individual items within an order, while order status refers to the overall status of the entire order. See more about Order status.
The following line item statuses in an order are available in Tango API:
Line Item status | Description |
|---|---|
COMPLETE | The reward for this line item has been successfully created and is ready for delivery and redemption. For Printed Reward Links, the reward has been printed and mailed and is expected to arrive within 7–10 business days. For digital rewards, the reward has been delivered successfully. For Printed Reward Links, the line item has been mailed and is expected to arrive within 7–10 business days. |
PENDING | The rewards will be processed and delivered within one (1) business day/ on the following business day. Once delivered, the order status changes to Complete. |
FAILED | The line item has failed to be sent due to a potential error. See Orders and Reports FAQ .You are refunded for the reward’s value. We recommend placing a new order to ensure your reward is still sent. For more information on brand outages and deprecation see our Tango Rewards Status page, or email [email protected]. Make sure to include the Reference Order ID of your failed order. |
DELETED | The line item has been removed from the system and may not appear in standard queries or reports. It cannot be reactivated or modified or restored once deleted. The reason may be legal compliance requirements, account management cleanup, etc. |
CANCELED | The line item has been canceled and cannot be resent to the recipient. The funds have also been refunded for this line item. Place a new order if needed. |
RETURNED | The line item has been sent back or reversed after initial fulfillment. This status applies when a reward that was previously delivered is returned to Tango. It occurs when a reward that was successfully delivered gets sent back or reversed due to delivery issues, recipient actions, or fraud detection. |
Reward status
Reward status tells you whether the delivered reward is functional, redeemable, frozen, deleted, or migrated. You use reward status to answer: Can the recipient redeem it now, has it already been redeemed, or do I need to freeze/cancel it?
The following reward statuses are available in Tango API:
| Reward status | Description |
|---|---|
| ACTIVE | The reward is issued, valid, and available for the recipient to use. This is the normal usable state of a reward. (Aligned with Tango’s description that reward status shows if a reward is available for use.) |
| INACTIVE | The reward exists but is not currently usable. This may occur before activation, after administrative actions, or when awaiting another system event. |
| DELETED | The reward record has been removed from active use. Usually appears when the reward object is no longer valid or stored in active systems. |
| SUSPENDED | The reward has been temporarily disabled, typically due to risk review, account issues, fraud concerns, or manual admin action. |
| CANCELLED | The reward was intentionally voided before or after delivery, making it unusable. Similar concept to “cancelled” statuses in orders and line items. |
| PROCESSING | The reward is not yet fully created; Tango is still generating or provisioning the reward. Similar to “pending” during line item processing. |
| FAILED | The reward could not be successfully generated—an internal failure similar to a failed line item (e.g., payment issue, inventory issue, technical error). Tango uses “failed” in line item statuses for undeliverable transactions. |
| FROZEN | The reward has been manually or automatically locked and cannot be redeemed. Freezing is a fraud‑prevention or issue‑resolution state. Reward status indicates when a reward is not available for use. |
| CANCELED | Same meaning as cancelled (American spelling vs. British spelling). Indicates the reward is void and unusable. Both may appear depending on system source. |
Email status
Email status tracks whether the reward email reached the recipient's inbox. It shows whether the email was sent (SENT), received (DELIVERED), why it failed to arrive (BOUNCED, BLOCKED, DROPPED, DEFERRED), was never attempted (NOT DELIVERED — when sendEmail=false).
The following email statuses are available in Tango API:
Email status | Description |
|---|---|
DELIVERED | The email is delivered. The email can only be sent if |
NOT DELIVERED | The email is not delivered. An email cannot be sent if |
PENDING | Our email server has attempted to deliver the reward email. If an order is showing Processed as its most recent status, wait a few minutes and check again for a Delivered or Not Delivered status. |
SENT | The reward email is sent successfully to the recipient's email address. The email may have arrived in the recipient’s mailbox, but we haven't received confirmation from the recipient's email server that the email is received. |
DEFERRED | The reward email cannot be delivered immediately, and it hasn’t been completely rejected. We will continue to try for 72 hours to deliver a deferred message. |
DROPPED | We were unable to deliver to this recipient. Resend reward email to an alternative email address. See Resend a specific order for rules and exceptions. |
BOUNCE | The recipient's email server cannot deliver the email to the email address entered. Use Resend to send it to a new email address for the same recipient. See Resend a specific order for rules and exceptions. |
BLOCKED | The email is blocked by an Internet Service Provider (ISP) or messaging organization. We recommend trying the following troubleshooting techniques before resending the reward email:
|
Updated 13 days ago