Order category events

The following webhook events are currently under the Order category:

• Asynchronous order status
• Line item delivery status (for physical gift cards)
• Order action status 🚧( Coming soon)

Asynchronous order status

The Asynchronous order status is a webhook notification provided by Tango. This webhook notifies you when an asynchronous order has completed processing—whether it was successful, retrying, failed, or partially failed. This is useful when you need large batch orders to be automatically notified of the processing outcome. The async order status notification includes details such as: externalRefID, customerIdentifier, accountIdentifier, referenceOrderID, and status.

Use case

Acme Wellness has submitted a large batch order for digital wellness gift cards (e.g., as part of a corporate wellness program) and wants to be automatically notified when a bulk gift card order, submitted asynchronously via the Tango API, has finished processing—whether it was successful, failed, retrying, or partially failed.

Example payload

Here is the response payload example:

{
  "eventId": "string",
  "revision": integer,
  "category": "ORDER",
  "eventType": "AsyncOrderStatus",
  "eventOccurredAt": "2026-01-27T21:30:11.562578300Z",
  "eventData": {
    "externalRefID": "string",
    "status": "SUCCESSFUL",
    "totalLineItems": integer,
    "failedLineItems": integer,
    "successfulLineItems": integer,
    "referenceOrderId": "string",
    "accountIdentifier": "string",
    "customerIdentifier": "string"
  }
}

Line item delivery status for physical gift cards

The Line item delivery status for physical gift cards is a webhook event that notifies you about changes in the delivery status. By subscribing to the LineItemDeliveryStatus event you receive timely updates when the delivery status of a line item changes, such as from In Progress to Shipped, etc.

To receive these notifications, create a subscription using POST {URI}/webhooks, with an eventTypes = LineItemDeliveryStatus and categories = ORDER.

Use case

Acme, a wellness incentive company, uses this webhook to monitor the delivery progress of physical gift cards. By subscribing to this event, Acme receives real-time updates when a line item’s delivery status changes from In Progress to Shipped, for example. This event allows Acme to keep recipients informed and manage delivery expectations effectively.

List of line item delivery statuses

The following statuses may be returned with thelineItemDeliveryStatus:

Example payload

Here is a response payload of LineItemDeliveryStatusevent:

{
  "eventId": "2e3b91ba-4d6a-43b5-8e77-3b31e3f938b3",
  "revision": 4,
  "category": "ORDER",
  "eventType": "LineItemDeliveryStatus",
  "eventOccurredAt": "2024-06-17T17:10:00.759273600Z",
  "eventData": {
    "referenceLineItemId": "RA240828-128134-15-1",
    "status": "In Process"
  }
}

🚧( Coming soon) Order action status

The Order action status webhook event provides updates on actions taken on an order. This event helps you track each line item's status, ensuring efficient order management. To receive these notifications, create a subscription using POST {URI}/webhooks with eventTypes = OrderActionStatus and categories = ORDER.

Actions in this webhook event refer to the following order-level operations you can perform on all eligible rewards in the order:

• CANCEL: bulk-cancel all eligible line items in the order.
• FREEZE: bulk-freeze all eligible line items in the order.
• UNFREEZE: bulk-unfreeze all eligible line items in the order.

Learn more about the available order statuses in Tango API in Order status.

Use Case

Acme, a wellness incentive company, uses this webhook event to monitor actions such as freezing, unfreezing, or canceling order line items. This allows them to manage orders effectively and ensure compliance with business rules. For example, when an async cancel-order operation is processed, the webhook event will be emitted to reflect the updated action status of the request.

How to use the order actions status event?

1. Initiate Action: Call the async bulk endpoint, such as POST {URI}/asyncOrders/{referenceOrderID}/cancel to perform actions like canceling, freezing, or unfreezing order line items.
2. Receive Webhook Notification: Wait for the OrderActionStatus webhook to be triggered, which will notify you of the action's outcome.
3. Match Identifiers: Use the referenceOrderID (and optionally externalRefID) to match the webhook notification to your original request.
4. Review Action and Status: Check the action taken (e.g., CANCEL, FREEZE, UNFREEZE) and determine the outcome (e.g., COMPLETED, INCOMPLETE).
5. Analyze counts: Use the counts such as: totalOrderLineItems, eligibleOrderLineItems, and actionedOrderLineItems to show how many rewards were affected.

Here is a response payload of OrderActionStatus:

"category": "ORDER",
"eventType": "OrderActionStatus",
"eventData": {
  "referenceOrderID": "...",
  "externalRefID": "...",
  "totalOrderLineItems": 1000,
  "eligibleOrderLineItems": 700,
  "actionedOrderLineItems": 500,
  "status": "COMPLETED" | "INCOMPLETE",
  "action": "FREEZE" | "UNFREEZE" | "CANCEL",
  "reasonCode": "...",
  "reason": "..."
}