Get a list of orders placed on this platform

This Tango API endpoint is used to retrieve a list of orders associated with your platform and account. It is primarily used to retrieve all orders or a filtered subset, audit and track orders, monitor delivery status, support customer service and troubleshooting workflows.

This endpoint is typically used after orders have already been created through the API (for example, via POST {URI}/orders. You can track, audit, and manage your reward program by reviewing your previously paced orders.

Use case

Acme Health, a wellness‑benefits provider, uses Tango’s API to automate the distribution and tracking of health‑related rewards. These rewards are sent to employees and program participants when they complete activities such as annual checkups, fitness challenges, preventive screenings, or wellness milestones. Once Acme Health creates reward orders via POST {URI}/orders, they rely on GET {URI}/orders to track reward delivery status, monitor program performance, resolve participant issues, detect fraud or abnormal activity, and ensure timely fulfillment.

Endpoint

Use the following endpoint to retrieve a list of all reward orders placed under your platform:

📘

Note:

GET {URI}/orders currently returns a maximum of 10,000 results. Use Tango API query parameters to filter and paginate large datasets more efficiently.

This endpoint supports query parameters: deliveryMethod, recipientMobileNumber , and deliveryStatus, allowing you to filter orders by delivery types like EMAIL, PHONE, ADDRESS, and EMBEDDED.

Parameters

Here is a list of query parameters offered with this endpoint to better filter your search results:

Response body

The response body for GET {URI}/orders contains all order records returned by your query, along with pagination details and all relevant attributes for each order. It tells you which orders were found, how many exist, and provides complete metadata for each order, including delivery details, status, campaign identifiers, timestamps, and sender/recipient information.

On a successful request (200 OK), the response body includes some important fields. Below are key notes and considerations to help you understand field behaviors and best practices:

• The page object describes pagination metadata. Your integration should use these values to handle pagination:
  • number—the current page number returned.
  • elementsPerBlock—the maximum number of items per page.
  • resultCount—the number of orders returned on this page.
  • totalCount—the total number of matching orders across all pages.
• sendEmail is deprecated and should not be used to determine delivery behavior. Use deliveryMethod instead (e.g., EMAIL, PHONE, ADDRESS, etc.).
• The response includes status, orderStatus, and lineItemStatus. These may differ depending on: delivery success or failure, partial order completion, and multi‑item orders.
• Always use orderStatus or lineItemStatus for determining fulfillment state, not the presence of credentials.
• externalRefID is returned as provided when the order was created. Use it to detect duplicate orders or track retries across systems.
• createdAt is returned in Coordinated Universal Time (UTC) for consistency across all systems.
• The deliveryMethod enum indicates how the reward was delivered. It may differ from what was originally requested if the system applied fallback handling.
• For digital delivery (EMAIL, PHONE, EMBEDDED), the address object will be absent or empty.
• For physical delivery (ADDRESS, BULKSHIPMENT), the address object is required and returned.
• Each returned order includes the following identifiers helpful for classification and reporting: utid (identifies the reward type (catalog item ID)) and ptid (identifies the reward product type).
• amountCharged represents the billing amount, including fees or exchange rate effects. denomination represents the reward’s face value to the recipient. These may differ based on currency, markup, or program configuration.
• Some orders include an asyncOrderEntity object, indicating that the reward may be processed asynchronously. If present, check this object for additional status details. This is common for certain reward types or delivery pipelines.
• orderExternalRefIdDupe indicates whether the provided externalRefID has been used before. This is useful for auditing and validating idempotency behavior.

Examples

The following example shows the payload including pagination when you use GET {URI}/orders. The delivery method, delivery status and other delivery details are included in the payload.

{
  "page": {
    "number": 0,
    "elementsPerBlock": 0,
    "resultCount": 0,
    "totalCount": 0
  },
  "orders": [
    {
      "referenceOrderID": "string",
      "externalRefID": "string",
      "customerIdentifier": "string",
      "accountIdentifier": "string",
      "accountNumber": "string",
      "amountCharged": {
        "value": 0,
        "currencyCode": "string",
        "exchangeRate": 0,
        "fee": 0,
        "total": 0
      },
      "denomination": {
        "value": 0,
        "currencyCode": "string",
        "exchangeRate": 0,
        "fee": 0,
        "total": 0
      },
      "utid": "string",
      "ptid": "string",
      "rewardName": "string",
      "sender": {
        "firstName": "string",
        "lastName": "string",
        "email": "string"
      },
      "recipient": {
        "firstName": "string",
        "lastName": "string",
        "email": "string",
        "mobileNumber": "string",
        "address": {
          "companyName": "string",
          "streetLine1": "string",
          "streetLine2": "string",
          "city": "string",
          "stateOrProvince": "string",
          "postalCode": "string",
          "country": "string"
        }
      },
      "emailSubject": "string",
      "message": "string",
      "deliveryMethod": "NONE",
      "etid": "string",
      "status": "string",
      "orderStatus": "string",
      "lineItemStatus": "string",
      "campaign": "string",
      "createdAt": "2025-11-03T23:25:29.857Z",
      "notes": "string",
      "orderClientSource": "string",
      "purchaseOrderNumber": "string",
      "orderExternalRefIdDupe": true,
      "asyncOrderEntity": {
        "externalRefID": "string",
        "status": "string",
        "totalLineItems": 0,
        "createdAt": "2025-11-03T23:25:29.857Z",
        "failedLineItems": [
          {
            "lineItemId": "string",
            "externalRefLineItemID": "string",
            "utid": "string",
            "errors": [
              {
                "field": "string",
                "errorCodeValue": 0,
                "errorCodeName": "string",
                "message": "string"
              }
            ]
          }
        ],
        "duplicateLineItemRefIds": {
          "additionalProp": 0
        }
      }
    }
  ]
}

Here's an example payload for when you receive an error:

{
  "timestamp": "2025-02-21T23:23:13.930Z",
  "requestId": "string",
  "path": "string",
  "httpCode": 0,
  "httpPhrase": "string",
  "i18nKey": "string",
  "message": "The error message will show here for error codes ",
  "errors": [
    {}
  ]
}

Response codes

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