Manage async orders

Async 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, amount, 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 the delivery status and who has received the delivery.

Delivery methods in async orders

Each line item in an async order has its own deliveryMethod and deliveryStatus. When you retrieve an async order or its line items, the response shows the delivery method and delivery status assigned to each existing line item.

Use BULKSHIPMENT when multiple physical rewards are shipped to one address. For delivery-method definitions, eligibility requirements, and validation rules, see Delivery methods in Tango API.

BULKSHIPMENT (🚧 Coming soon)

BULKSHIPMENT is a delivery method available only with Async Orders and is used for bulk physical reward fulfillment. It allows you to order one or more physical gift cards of the same reward and have them shipped to a single destination, such as a corporate office, branch location, event venue, or fulfillment center.

Use BULKSHIPMENT when your organization will receive and distribute the physical cards to recipients. In this scenario, the shipment is sent to your organization's address rather than directly to the end recipients.

When deliveryMethod is set to BULKSHIPMENT:

• Include a bulkShipping object containing the shipping contact and destination address.
• Include a supported shippingMethod.
• Do not provide a recipient object.
• The shipment is delivered to a single shared destination.
• The line item quantity may be one or greater.

For example, a company may order 5,000 physical gift cards and have them shipped to its headquarters for distribution to employees during a recognition program. Instead of creating thousands of individual shipments, the company creates a single Async Order with deliveryMethod set to BULKSHIPMENT. The bulkShipping object specifies where the shipment should be delivered and who will receive it.

Shipping Methods

A shippingMethod is required for physical reward deliveries that use either ADDRESS or BULKSHIPMENT. Some supported shipping methods are: upsground, upsgroundsignature, etc.

If a supported shipping method is only supported when the line item quantity is 1, orders using the shipping method with a quantity greater than 1 will fail validation.

Bulk shipment vs address

• Use BULKSHIPMENT when physical cards are shipped to a company or shared location for later distribution by your organization.

• Use ADDRESS when Tango ships a physical reward directly to an individual recipient's address. In this case, each line item includes recipient information and the reward is delivered to that specific recipient.

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