Manage async orders

Async orders are designed for large-scale or multi-recipient reward distributions where processing occurs asynchronously. Each line item can have its own reward, amount, recipient, 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.

About bulk shipment(🚧 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 receives and distributes the physical cards to recipients. In this case, the shipment is sent to your organization's address rather than directly to the end recipients.

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. See BULKSHIPMENT eligibility and requriements in Delivery methods in Tango API for more details.

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.

Physical reward shipping types

When ordering physical rewards, choose the appropriate shipment type based on the delivery destination. BULKSHIPMENT is used for bulk deliveries to a shared location, while ADDRESS is used for direct-to-recipient shipments.

Rate limits and performance

To ensure reliable performance and prevent service disruptions when interacting with the Tango API, follow these best practices:

• Stay withing API rate limits: Design your integration to respect API rate limits and avoid sending excessive requests in a short period of time. This is especially important when processing large order volumes or submitting orders in rapid succession.
• Monitor async orders using dedicated resources: For async order processing, track order progress and completion through the asyncOrderStatus webhook event. When retrieving async order details, use the GET /asyncOrders endpoints rather than the GET /orders endpoints, which are intended for synchronous order workflows.

Common validation errors for async orders

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 required fields must be provided, including recipient and delivery information when applicable.
• Invalid delivery configuration: Orders may fail validation when the selected reward does not support the requested delivery method or when the requested delivery method is not enabled for the platform. See Delivery Methods in Tango API for delivery-method eligibility and recipient requirements.

Async order considerations

Keep the following considerations in mind when working with async orders to ensure accurate processing, status tracking, and reward delivery:

• Async orders are queued for processing and are not fulfilled immediately after submission. Processing times may vary depending on order volume and system activity.
• To monitor order progress and completion, subscribe to the appropriate webhook events for real-time status updates.
• Verify that recipient contact information matches the selected delivery method. For example, provide an email address for email delivery, a phone number for SMS delivery, and a valid mailing address for physical rewards.