Order category events

The following webhook events are currently supported under the ORDER category:

AsyncOrderStatus events

Use the AsyncOrderStatus webhook event to receive the final processing outcome for an asynchronous order. This event is useful when you submit large batch orders and want your webhook endpoint to be notified when processing finishes. The payload includes identifiers such as externalRefID, customerIdentifier, accountIdentifier, referenceOrderId, and status.

How to subscribe?

To subscribe, create a webhook subscription for the ORDER category and the AsyncOrderStatus event type.

POST {URI}/webhooks
{
  "eventTypes": ["AsyncOrderStatus"],
  "categories": ["ORDER"],
  "url": "https://your-webhook-endpoint.com"
}

Use case

Acme Wellness submits a large batch order for digital wellness gift cards as part of a corporate wellness program. By subscribing to AsyncOrderStatus, Acme can automatically receive the final result when the asynchronous order completes, including successful, failed, retrying, and partially failed outcomes.

Example payload

The AsyncOrderStatus webhook event payload uses externalRefID instead of externalReferenceId for consistency with the Orders POST and GET responses.

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"
  }
}

LineItemDeliveryStatus events (physical gift cards)

Use the LineItemDeliveryStatus webhook event to receive delivery updates for physical gift card line items.

Subscribe to this event when you want to track changes in physical delivery status, such as a line item moving from IN_PROGRESS to SHIPPED.

How to subscribe?

To subscribe, create a webhook subscription for the ORDER category and the LineItemDeliveryStatus event type.

POST {URI}/webhooks
{
  "eventTypes": ["LineItemDeliveryStatu"],
  "categories": ["ORDER"],
  "url": "https://your-webhook-endpoint.com"
}

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 updates when a line item’s delivery status changes and can keep recipients informed about shipping progress.

Statuses for lineItemDeliveryStatus

The following statuses may be returned with thelineItemDeliveryStatus:

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) OrderActionStatus event

The OrderActionStatus webhook event will provide updates on actions taken on an order. Use this event to track the outcome of order-level bulk actions performed on eligible rewards in the order.

Here are the supported actions:

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

How to subscribe?

To subscribe, create a webhook subscription for the ORDER category and the OrderActionStatus event type.

POST {URI}/webhooks
{
  "eventTypes": ["OrderActionStatus"],
  "categories": ["ORDER"],
  "url": "https://your-webhook-endpoint.com"
}

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 OrderActionStatus event

1. Call the asynchronous bulk endpoint, such as POST {URI}/asyncOrders/{referenceOrderID}/cancel, to cancel, freeze, or unfreeze eligible order line items.
2. Wait for the OrderActionStatus webhook event.
3. Match the webhook notification to your original request by using referenceOrderID and, optionally, externalRefID.
4. Review the action and status values to determine the outcome.
5. Use counts such as totalOrderLineItems, eligibleOrderLineItems, and actionedOrderLineItems to understand how many rewards were affected.

Example payload

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": "..."
}