Create async orders

This Tango API endpoint enables you to create asynchronous orders for distributing rewards under a specific account. It's designed for multiple line items, where you need to send rewards to recipients with various delivery methods. The asynchronous orders are also efficient for large-scale reward campaigns.

Endpoint

Use the asynchronous orders endpoint to create a batch of rewards:

Use case

Acme Corp runs quarterly employee recognition and customer loyalty programs. Each cycle, they distribute hundreds of digital and physical rewards to recipients across different regions and departments. They use async order placement with this endpoint to submit rewards with multiple line items in a single request. They can track delivery status via the GET /asyncOrders endpoints without exposing reward credentials while customizing delivery methods per recipient (email, SMS, physical mail). They can receive webhook notifications when the order has completed.

Parameters

The following body parameters are used with this endpoint:

*See the description for more information.

External reference ID

To prevent duplicate order submissions, the POST {URI}/asyncOrders endpoint now validates incoming externalRefID values against existing orders.

• If the externalRefID was previously used with POST {URI}/orders, the request fails with a descriptive error.
• If the externalRefID was previously used with POST {URI}/asyncOrders, the endpoint returns the status of the existing order instead of creating a new one.

📘

Behavior change:

This endpoint now enforces delivery‑specific validation for quantity, recipient, and shipping fields. Existing integrations that used quantity > 1 with unsupported delivery methods will receive validation errors and must be updated to use BULKDIGITAL or BULKSHIPMENT for bulk quantities.

Bulk quantity, shipping, and recipient rules

The following table summarizes how bulk quantity, shipping, and recipient requirements vary by delivery method:

📘

Notes:

• For BULKDIGITAL and BULKSHIPMENT, do not include a recipient object. For BULKSHIPMENT, provide delivery information in shipping instead.
• Quantity defaults to 1 when missing. It must be 1 or greater for bulk digital and bulk shipment. If quantity is greater than 1, deliveryMethod must be BULKSHIPMENT or BULKDIGITAL.
• Any delivery method not listed as supporting bulk quantity will fail if quantity is greater than 1.
• Including a shipping object when it is not allowed will fail validation.
• Missing or extra recipient objects will fail validation based on the delivery method.
• Invalid requests return 422 Unprocessable Entity with a descriptive error message.

Examples

The following example illustrates the payload for using this endpoint and its parameters.

{
  "externalRefID": "string",
  "status": "string",
  "totalLineItems": 0,
  "createdAt": "2025-10-23T21:52:43.041Z",
  "failedLineItems": [
    {
      "lineItemId": "string",
      "externalRefLineItemID": "string",
      "utid": "string",
      "errors": [
        {
          "field": "string",
          "errorCodeValue": 0,
          "errorCodeName": "string",
          "message": "string"
        }
      ]
    }
  ],
  "duplicateLineItemRefIds": {
    "additionalProp": 0
  }
}

Here is the successful response example:

{
  "externalRefID": "ORDER-2025-001",
  "order": {
    "externalRefID": "ORDER-2025-001",
    "status": "pending",
    "totalLineItems": "2",
    "created_at": "2025-05-07T10:00:00Z"
  }
}

Response codes

The possible response codes for this endpoint are as follows. For details, see i18nkey codes and their error messages: