Tango provides webhook events so your system can react automatically when a reward changes after it has been created. Under the REWARD category, you can subscribe to the RewardStatus event to receive real-time updates about reward lifecycle changes, such as when a reward is frozen, unfrozen, cancelled, activated, or redeemed:

`RewardStatus` event

Subscribe to the RewardStatus event within the REWARD category to receive real-time updates when a reward moves through its lifecycle. These updates can include status changes such as FROZEN, UNFROZEN, CANCELLED, etc. Using this event you can:

Track reward fulfillment
Keep users informed about reward activity
Respond quickly to issues (like frozen/cancelled rewards)
Maintain accurate reward status in their systems

How to subscribe

To subscribe to RewardStatus events, create a webhook subscription for the REWARD category and the RewardStatus event. After you subscribe, your webhook endpoint will receive a notification each time the reward status changes.


POST {URI}/webhooks
{
  "category": "REWARD",
  "eventType": "RewardStatus",
  "targetUrl": "https://yourserver.com/tango-webhook",
  "description": "My Reward Status Listener"
}
``

Use case

Acme, a wellness incentive company, subscribes to Tango’s RewardStatus webhook event to monitor important changes in reward delivery and usage. By subscribing to this event, Acme receives real-time updates when:

A recipient activates a mailed prepaid MasterCard or Visa.
A plastic card is received and activated.
A Choice Product is frozen, unfrozen, cancelled, reissued, or redeemed (partially or fully).

This helps Acme track reward fulfillment, respond to issues quickly, and improve the recipient experience.

Statuses for `RewardStatus`

The RewardStatus webhook event reports changes that occur after a reward has been created. A reward receives these statuses only after its line item is COMPLETE, because before that point there is no reward to track.

Use these statuses to understand whether a reward can be redeemed, has been redeemed, or has been acted on, such as being frozen or cancelled. These status updates are delivered in real time through webhook events. They are not stored as event history for later retrieval, so if you miss the webhook event, you cannot retrieve that event from the API later.

The reward statuses that are stored in the database, however, can be queried via GET {URI}/lineItems endpoint. For more details, see Reward status.

The following RewardStatus webhook event statuses are available in Tango API:

Status	Description
`FROZEN`	The Choice Product is frozen and cannot be redeemed by the recipient. Unfreeze the reward to allow redemption.
`UNFROZEN`	The Choice Product is unfrozen and ready to be redeemed by the recipient.
`CANCELLED`	The Choice Product has been cancelled and cannot be redeemed by the recipient. The funds have been refunded for this reward. Send new rewards if needed.
`ACTIVATED`	This status is used for physical open-loop cards where the recipient activates the card. Approval is required to receive this status.
`PARTIAL_REDEMPTION`	The recipient partially redeems a Choice Product. The balance is not zero (<> $0), meaning the product still has some value left after the partial redemption.
`FULL-REDEMPTION`	The recipient fully redeems a Choice Product. The balance is zero (=$0) and the product does not have any value left after the full redemption.
`RETURNED`	The PayPal/Venmo reward was returned to the issuer because it could not be successfully delivered due to a transfer failure, delivery issue, or recipient rejection.

Tracking `deliveryStatus`

The RewardStatus webhook event does more than report reward lifecycle changes. It also includes a deliveryStatus field so you can track whether the reward has reached the recipient. When a RewardStatus event is sent, the payload can include delivery-related values such as:

deliveryStatus	Description
PENDING	The reward has been created but not yet delivered.
PROCESSING	Delivery is in progress.
DELIVERED	The reward was successfully delivered to the recipient.

See Delivery status for more information.

Example payload

Here is an example payload of RewardStatus event that also shows deliveryStatus:

{
"category": "REWARD",
"eventType": "RewardStatus",
"eventOccurredAt": "2024-11-09T04:25:36.4844028Z",
"eventData": {
    "referenceLineItemId": "RG241108-3077508-11-1",
    "externalRefID": "XXXXXX",
    "type": rewardtype,
    "deliveryStatus": "DELIVERED" , "PENDING", "BOUNCED", etc.
    "status": "FROZEN", "UNFROZEN", "CANCELLED", "ACCESSED", "PARTIAL_REDEMPTION", "FULL_REDEMPTION", "RETURNED"
    "action": <"FREEZE", "UNFREEZE", "CANCEL", "REISSUE", "RESEND", "DELIVERY_UPDATE">
    "newReferenceLineItemID": "RG241108-3077518-12-1",
    "reasonCode": <enumeration>
    "reason": <text description> [100 chars]
}

RewardStatus event