Manage async orders

🚧

Closed Release:

This feature is available for a limited number of customers with a specific use case.

These endpoints are used to manage asynchronous orders placed on the system. It’s designed for scenarios where a multi-line item order is placed. Each line item could have a different recipient, different amount, different reward, and delivery method., The GET endpoints will allow you to examine each line item without exposing reward credentials or get the full credentials. With async orders, you will also need to subscribe to the AsyncOrderStatus webhook event to receive a notification when the order has completed.

Using the POST async orders endpoint, you need to provide the External Reference ID to identify and query the order. The summary GET endpoint returns the total number of line items, recipient details, delivery method, and much more. No reward credentials are returned in the response, protecting sensitive data from being exposed to internal systems or employees.

Use case

You’ve placed a multi-line item asynchronous order for gift cards to be delivered via different methods. After receiving a webhook notification that the order is complete, you use this endpoint to confirm delivery status, audit who received what, and ensure no credentials are exposed to your software or staff.

👍

Best practices

• Idempotency— Always provide unique externalRefID values to prevent duplicate orders.
• Delivery Scheduling— Utilize deliveryDate to schedule the delivery of a reward to a future date. See Send rewards with scheduled delivery to learn about what types of rewards can be scheduled and how far in advance you can set the delivery.
• Subscribe to the AsyncOrderStatus webhook event to receive updates on when the order completes.

Rate limits and performance

To ensure smooth operation and optimal performance when interacting with the Tango API, follow these best practices:

• Respect API rate limits: Avoid exceeding rate limits, especially when submitting large or frequent orders.
• Monitor Order Status Separately: Track the progress and completion of async orders by subscribing to the asyncOrderStatus webhook event. Use the dedicated GET /asyncOrders endpoints instead of the GET /orders endpoints.

Error Handling

When placing asynchronous orders via the Tango API, be aware of the following common error scenarios:

• Invalid customerIdentifier or accountIdentifier: Ensure these values match existing records in your Tango account.
• Insufficient Account Balance: Orders will fail if the account balance is insufficient to cover the total cost.
• Invalid utid: The reward identifier must match an item available in your catalog.
• Missing Required Fields: All mandatory fields (e.g., recipient info, delivery method) must be provided.
• Invalid Delivery Method for Reward Type: Certain rewards may not be supported by specific delivery methods (e.g., physical delivery for digital-only items).

Additional notes

• The asynchronous nature of this endpoint means that orders are queued for processing, not fulfilled immediately.
• To track progress, subscribe to the webhook for real-time updates.
• Ensure that the recipient's contact details align with the selected delivery method (e.g., an email address for email delivery, a phone number for SMS, or a physical address for mailed rewards).