Get details for a specific order

Use this Tango API endpoint to retrieve the full details of a specific order. An order may include one or multiple rewards created at the same time. When you query an order, the response includes important information such as the reward value, currency, reward name, sender and recipient details, and delivery information. The response also provides key status fields—such as email status and line item status—along with the credentialList, credential types, and other line‑item attributes. See more information about email status and line item status To fetch an order, you must supply its referenceOrderID, which uniquely identifies the order and ensures you retrieve the correct set of rewards and associated details.

Use case

Acme Health uses this endpoint to look up the details of a reward previously issued to a member. When a member contacts support—for example, saying they didn’t receive their reward—Acme Health retrieves the order using its referenceOrderID to quickly access: reward value and currency, sender and recipient information, delivery method, email or line‑item status, and credential list (e.g., reward codes or URLs). This information allows the support team to confirm delivery, identify issues, and take the correct next steps such as resending the reward or updating the recipient information.

Endpoint

Use the following endpoint to retrieve details of a specific order:

Parameters

The referenceOrderID is a path parameter and serves as a unique identifier for an order created through the Tango API. It functions like a a tracking number for a reward order, allowing you to retrieve, manage, or audit a specific order at any time. Use theGET {URI}/orders/{referenceOrderID} endpoint to look up the details of a specific order

With referenceOrderID, you can verify that an order was processed correctly, track delivery or redemption status, and reissue or cancel a reward if needed (using the referenceLineItemID from the order).

Examples

The following example shows the payload for the order when you perform a GET {URI}/orders/{referenceOrderID} to view the details of an order placed in the system. You can get the delivery method, order status, reward details, recipient info, and much more in the response:

{
  "referenceOrderID": "string",
  "referenceLineItemID": "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
    }
  },
  "reward": {
    "credentials": {
      "additionalProp": "string"
    },
    "credentialList": [
      {
        "label": "string",
        "value": "string",
        "type": "string",
        "credentialType": "string"
      }
    ],
    "redemptionInstructions": "string"
  }
}

The following payload example shows the credentialList details for a specific order.

📘

Note:

• The credentials field is deprecated. Use credentialList instead.
• credentialList includes stable parameters—such as type, label, and value—that allow clients to properly display or deliver rewards within an application or via email.

 
  "reward": {
    "credentials": {
      "rewardSecurityCode": "331XHT75",
      "rewardSecurityUrl": "https://sandbox.rewardcodes.com/r2/1/Y4blCPqUsr7fsiLYAws6yvrcJSPer1AyR3AJ5yz_niiKekq-4RcrY19u6MCsRima"
    },
    "credentialList": [
      {
        "label": "rewardSecurityCode",
        "value": "331XHT75",
        "type": "text",
        "credentialType": "rewardSecurityCode"
      },
      {
        "label": "rewardSecurityUrl",
        "value": "https://sandbox.rewardcodes.com/r2/1/Y4blCPqUsr7fsiLYAws6yvrcJSPer1AyR3AJ5yz_niiKekq-4RcrY19u6MCsRima",
        "type": "url",
        "credentialType": "rewardSecurityUrl"
      }
    ],
    "redemptionInstructions": "<ol>\n<li><strong>Copy</strong> the security code.</li>\n<li><strong>Click</strong> on the Redemption URL and <strong>paste</strong> the code.</li>\n<li>Agree to the Cardholder agreement to unlock the card. </li>\n</ol>\n<p> </p>"
  }
}

The following payload example shows a Promo Link with an expiration date when you perform a GET {URI}/orders/{referenceOrderID} to view the details of a previously placed order. Note that expirationDate is now part of the reward credentialList:

📘

Note:

• Expiration date only applies to Promo Links.
• expirationDate is now part of the reward credentialList. Note that we have deprecated credentials and use credentialList instead.

{
  "referenceOrderID": "string",
  "externalRefID": "string",
  "customerIdentifier": "string",
  "accountIdentifier": "string",
  "accountNumber": "string",
  "amountCharged": {
    "value": 10.00,
    "currencyCode": "USD",
    "total": 10.0
  },
  "denomination": {
    "value": 10,
    "currencyCode": "USD"
  },
  "utid": "string",
  "rewardName": "Promo Link",
  "sender": {
    "firstName": "string",
    "lastName": "string",
    "email": "string"
  },
  "recipient": {
    "email": "string",
    "firstName": "string",
    "lastName": "string",
    "address": null
  },
  "sendEmail": false,
  "status": "COMPLETE",
  "createdAt": "2023-10-11T23:10:55.284Z",
  "reward": {
    "credentials": {
      "redemptionUrl": "string",
      "expirationDate": "2024-12-31T06:59:59Z"
    },
    "credentialList": [
      {
        "label": "redemptionUrl",
        "value": "string",
        "type": "url",
        "credentialType": "redemptionUrl"
      },
      {
        "label": "expirationDate",
        "value": "2024-12-31T06:59:59Z",
        "type": "date",
        "credentialType": "expirationDate"
      }
    ],
    "redemptionInstructions": "Promo Link Test Redemption Instructions"
  }
}

📘

Order history:

Orders placed via the Tango API are v1 available via the v2 GET {URI}/orders call and are combined with Orders placed via the Tango API v2. To retrieve full order details, including reward credentials, make a GET {URI}/orders/{referenceOrderId} call.

Response body

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

• referenceOrderID uniquely identifies the order. referenceLineItemID identifies the specific reward within the order and is required for actions like resend, cancel, freeze, or reissue.

• externalRefID is an idempotent field used to prevent accidental duplicate orders. orderExternalRefIdDupe = true indicates the same externalRefID was used previously.

• amountCharged shows the billed amount (may include fees or currency conversion). Denomination represents the reward value delivered to the recipient.

• sendEmail is deprecated. Use deliveryMethod to determine how the reward was delivered. credentials is deprecated. Use credentialList for reward redemption details.

• credentialList includes all fields needed to display or deliver the reward (label, value, credential type, redemption instructions).Some rewards may return multiple credentials (e.g., code + PIN).

• status, orderStatus, and lineItemStatus offer details on order validation, fulfillment, and delivery outcomes. Use lineItemStatus to determine whether a specific reward was delivered successfully.

• deliveryMethod indicates how the reward was delivered (EMAIL, PHONE, ADDRESS, EMBEDDED, etc.). Address fields appear only for physical delivery.

• failedLineItems lists any items that failed validation or processing, including error codes and messages.

• duplicateLineItemRefIds appears when multiple line items share the same externalRefLineItemID in the request.

• createdAt is returned in UTC for consistent time tracking across systems.

• asyncOrderEntity indicates that asynchronous processing may be involved for certain reward types.

Response codes

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