Reward category events

The following webhook event is supported under Reward category:

Reward Status event

Tango supports sending webhook events when reward status changes. Subscribing to the reward status event ensures you receive timely notifications for changes such as rewards becoming frozen, unfrozen, cancelled, etc. To subscribe to reward status events, create a subscription using POST {URI}/webhooks ,then select RewardStatus for the event type and REWARD for the category.

Use case

Acme, a wellness incentive company, subscribes to Tango’s RewardStatus webhook event to monitor key 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 enables Acme to track reward fulfillment, respond to issues promptly, and enhance the overall recipient experience. Using RewardStatus Acme receives a notification indicating the status change.

List of webhook event statuses (for reward status)

These statuses are sent via the RewardStatus webhook event to notify you about changes to a reward after it has been created. They track the reward's lifecycle, whether it can be redeemed, has been redeemed, or has been acted upon (frozen, cancelled, etc.). Reward status only exists once the line item is COMPLETE—because before that, there's no reward to track. See Reward status table for more information. The Reward statuses are stored in the database. You can query them later via the GET {URI}/lineItems endpoint. Reward status event statuses, however, are reported only in the webhook event at the moment they happen. They are not stored. If you miss the webhook, you can't retrieve them from the API later.

The following webhook event statuses (for reward status) are available in Tango API:

Webhook event statuses	Description of webhook event statues (for reward status)
`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`	This is not stored but transient status value. 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`	This is not stored but transient status value. 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.

Tracking reward delivery status

With the RewardStatus webhook event, you can track reward delivery. The payload includes deliveryStatus along other fields so you can track whether the reward reached the recipient (PENDING, PROCESSING, DELIVERED, etc.). See Delivery status for line items.

Here is an example payload of RewardStatusevent:

{
"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"
    "action": <"FREEZE", "UNFREEZE", "CANCEL", "REISSUE", "RESEND", "DELIVERY_UPDATE">
    "newReferenceLineItemID": "RG241108-3077518-12-1",
    "reasonCode": <enumeration>
    "reason": <text description> [100 chars]
}