Get a list of orders placed on this platform

Use GET {URI}/orders 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 placed orders.

Use case

Acme Health, a wellness‑benefits provider, uses Tango’s API to send rewards when employees complete activities such as annual checkups, fitness challenges, and preventive screenings. After creating reward orders with POST {URI}/orders, Acme Health uses GET {URI}/orders to track delivery status, monitor program performance, resolve participant issues, and audit fulfillment.

Endpoint

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

Endpoint	Purpose
`GET {URI}/orders`	Get a list of Orders placed under this platform.

📘
Note:
GET {URI}/orders returns a maximum of 10,000 results. Use query parameters and pagination to filter large datasets.

This endpoint supports query parameters for account, customer, date range, amount, currency, recipient, delivery method, order status, line item status, campaign, notes, and purchase order number. deliveryMethod, recipientMobileNumber, and deliveryStatus, allow 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:

Query params	Data type	Description
accountIdentifier	string	Specify the account to be queried. The string must have 5-100 characters.
customerIdentifier	string	Specify the customer to be queried. The string must have 5-100 characters.
externalRefID	string	Specify the external reference ID to be queried. The string may have up to 100 alphanumeric characters.
startDate	string	Specify the starting date or date time to be queried according to RFC 3339, i.e. "2016-01-01" or "2016-01-01T00:00:00Z". See https://www.ietf.org/rfc/rfc3339.txt
endDate	string	Specify the ending date or date time to be queried according to RFC 3339, i.e. "2016-01-01" or "2016-01-01T00:00:00Z". See https://www.ietf.org/rfc/rfc3339.txt
elementsPerBlock	int32	Specify the number of elements in a block that is the maximum number of items per page.
page	int32	Specify the page number to return.
minAmount	double	Specify the minimum face value of the reward to be queried. Best practice: When filtering by amount, provide both `minAmount` and `maxAmount`.
maxAmount	double	Specify the maximum face value of the reward to be queried. Best practice: When filtering by amount, provide both `minAmount` and `maxAmount`.
currencyCode	string	Specify the currency code of the reward to be queried. The string must be three characters.
utid	string	Specify the unique identifier of the reward to be queried. For example: UTID=U1234 has the attributes= (NONE, EMAIL, PHONE, and EMBEDDED).
ptid	string	Specify the unique identifier of the physical delivery template to be queried. PTID is required for orders where the UTID is Reward Type = Reward Link, Fulfillment Type = Physical.
rewardName	string	Specify the reward name of the reward to be queried.
senderFirstName	string	Specify the sender's first name to be queried. This information is for tracking purposes only and doesn’t change the email address the reward is sent from when `deliveryMethod=email`. The `senderFirstName` may have up to 100 characters. You cannot use < or > or / in the name.
senderLastName	string	Specify the sender's last name to be queried. This information is for tracking purposes only and doesn’t change the email address the reward is sent from when `deliveryMethod=email`. The `senderlastName` may have up to 100 characters. You cannot use < or > or / in the name..
senderEmail	string	Specify the sender email address to be queried. This information is for tracking purposes only and doesn’t change the email address the reward is sent from when `deliveryMethod=email`.
recipientEmail	string	Specify the recipient’s email address to be queried.
recipientMobileNumber	string	Specify the recipient mobile number to be queried. The `recipientMobileNumber` is required if `deliveryMethod=PHONE`. The following validation rules apply to mobile numbers for SMS delivery: Country Code: Must be included. Format: +CCCPPPPPPPPPPPP (where C is the country code, 1-3 digits, and P is the phone number, up to 12 digits). Initial Release: Only accepts US phone numbers (Country code = +1) and 10 digits for the phone number. -Standard: Follows ITU E.164, allowing (+) and up to 15 digits for the combined country code and phone number.
recipientFirstName	string	Specify the recipient’s first name to be queried. The `recipientFirstName` may have up to 100 characters. You cannot use < or > or / in the name.
recipientLastName	string	Specify the recipient’s last name to be queried. The `recipientLastName` may have up to 100 characters. You cannot use < or > or / in the name.
deliveryMethod	string	A query of orders based on their method of delivery. We have introduced various ways of reward delivery to your recipients through `deliveryMethod`. See Delivery methods for more information.
orderStatus	string	Specify the status to be queried. See order status. -COMPLETE -PENDING -FAILED -CANCELLED -PARTIAL
lineItemStatus	string	Specify the status to be queried. See line item status . -COMPLETE -PENDING -FAILED -CANCELLED
campaign	string	Specify the campaign to be queried. The maximum length is 1024 characters including the special characters such as @, #, %, etc.
notes	string	Specify the notes to be queried. The string may have up to 150 characters.
lineItemNotes	string	Specify the notes to be queried.
purchaseOrderNumber	string	Specify the purchase order number to query.

Responses

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.

Examples

The following example shows the payload including pagination when you use GET {URI}/orders. A successful response includes pagination metadata and an orders array. The response may include status, orderStatus, and lineItemStatus. Use orderStatus or lineItemStatus to determine fulfillment state.

{
  "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": "2026-05-08T19:15:31.526Z",
      "notes": "string",
      "orderClientSource": "string",
      "purchaseOrderNumber": "string",
      "orderExternalRefIdDupe": true,
      "asyncOrderEntity": {
        "externalRefID": "string",
        "status": "string",
        "totalLineItems": 0,
        "createdAt": "2026-05-08T19:15:31.526Z",
        "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:

Response	Description
200	The request was successful.
400	The server could not understand the request due to invalid syntax.
401	Authentication is required and has either not been provided or failed.
403	The server understood the request but refuses to authorize it.