Reward category events

The following webhook event is supported under Reward category:

Reward status

Tango supports sending webhook events when reward status changes. Subscribing to the RewardStatus 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, uses Tango’s RewardStatus webhook 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 reward statuses

The following statuses are returned with RewardStatus:

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

When creating a subscription for reward status, use thePOST {URI}/webhooks and enter the following values:

Body Params	Type	Description
url	string	Enter the URL of your webhook listener. It must be a valid URL. (Required)
categories	array of strings	Enter `Reward` for categories. (Optional if you're specifying eventTypes.)
eventTypes	array of strings	Enter `RewardStatus` for eventTypes. (Optional if you're specifying categories.)

🚧 Coming soon: The payload includes externalRefID. Adding externalRefID to the RewardStatus event payload makes it easy to match the event with your original request and improves tracking across your systems. Here is a response payload of RewardStatus:

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

The possible response codes for this endpoint are as follows. For details, see i18nkey codes and their error messages:

201 Created
400 Bad Request
401 Unauthorized