Get line items

Retrieving line items can be essential for your business. You may want to prepare financial reports requiring accurate data on sales and expenses, or you may need to analyze sales performance to identify trends and opportunities. Use GET {URI}/lineItems endpoint to retrieve the line items and filter the information about all line items ordered on the platform. Using this endpoint, you can see the reward status, reward history, and redemption history, freeze, unfreeze, cancel, reissue and resend a specific line item.

📘

Note:

Orders and line items include sensitive information such as Personally Identifiable Information (PII). PII must be used for internal logging and support only. To protect your users, do not reveal the orders and rewards sensitive information to any other user, except the reward recipient.

Use the following endpoint to retrieve line items ordered under this platform. This endpoint includes query parameters: deliveryMethod, recipientMobileNumber , and deliveryStatus. You can query rewards using delivery methods such as EMAIL, PHONE, ADDRESS, and EMBEDDED for better results.

GET indicates that you are requesting data from the server. Replace {URI} with the base URI of your API:

EndpointDescription
GET {URI}/lineItemsGet a list of line items placed on this platform.

Here are a list of query parameters that helps you filter, sort, and customize the data you retrieve from this endpoint:

Query params

Data type

Requirement

Description

referenceOrderID

string

required

A unique identifier for the order you want to query. It's a required path parameter for the GET /orders/{referenceOrderID} endpoint.

externalRefID

string

optional

An idempotent identifier that is strongly recommended to use when creating orders. If you retry a failed order with the same externalRefID, Tango will not create a duplicate order. It helps with order tracking, deduplication, and error recovery.

utid

string

A unique identifier used to specify the exact reward item (such as gift card brand and denomination) when placing an order. Each reward item in the Tango catalog has a unique utid. You retrieve available utids using the GET {URI}/catalogs or GET {URI}/choiceProducts/{choiceProductUtid}/catalog endpoints.

ptid

string

required for physical delivery

The unique identifier for the Printed Reward Link template provided under templates in Tango portal. PTID is only applicable when sending Printed Reward Links. Printed Reward Link is printed on paper and physically mailed to your US recipients. Learn how to Manage Printed Reward Link templates.

etid

string

The unique identifier for the digital template. Only applicable when deliveryMethod= EMAIL.

status

string

The line item status to be retrieved for each line item. See Line item status. The available values are: COMPLETE, PENDING, FAILED, and CANCELLED.

emailStatus

string

The email status to be retrieved for each line item. The email can only be sent if deliveryMethod=EMAIL . The available values for email status are: DELIVERED, NOT_DELIVERED, PENDING, SENT, DEFERRED, DROPPED, BOUNCE, and BLOCKED.

deliveryMethod

string

Specifies the delivery method for an order to determine how a reward is sent to a recipient:

  • NONE: Tango does not deliver. You are responsible to deliver the rewards to your recipient. This option is similar to sendEmail=false.

  • EMAIL: Tango delivers the reward to the recipient via email. You must include the recipient email. This option is similar to sendEmail=true.

  • PHONE: Tango delivers the reward to the recipient via text. You must include the recipient phone number.

  • ADDRESS: Tango delivers the physical rewards via a carriers such as the post office, FexEx, UPS, etc. You must include the recipient address.

  • EMBEDDED: You will embed Tango's lading page into your application. Tango will not deliver the rewards.

deliveryStatus

string

Includes the delivery status to be queried. The available values are: PENDING, PROCESSING, DISPATHCHED, DELIVERED, and FAILED.

orderStatus

string

The order status to be retrieved for each line item. See order status . The available values are: COMPLETE, PENDING, FAILED, CANCELLED, and PARTIAL.

orderSource

string

The order source to be retrieved for each line item. The available values are:

  • RA: The rewards are sent through Tango API. Tango API users see the two-letter identifiers when they use: -GET {URI}/lineItem under "OrderSource
    • GET {URI}/orders/{referenceOrderID} under "orderClientSource"
  • RG: The rewards are sent through Tango portal by email or mail delivery.
  • BE: The rewards are sent through Blast External (BE) or bulk upload for 15-50,000 recipients per order.
  • BI: Orders placed using bulk-internal upload.
  • CI: Rewards are sent manually by the Tango Orders team. Contact your Customer Success Manger (CSM) or [email protected] if you are interested in working with the Tango Orders team to send rewards.
  • QW: Rewards Links are sent via Qualtrics (QW) or Tango integration. Contact your Customer Success Manger (CSM) or [email protected] if you are interested in integrating Tango with Qualtrics.

recipientEmail

string

A recipient's email address. It returns line items across all orders.

recipientMobileNumber

string

Specifies the recipient mobile number to be queried. MobileNumber is required if deliveryMethod is PHONE. The following validation rules apply to mobile numbers for Mobile 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

The recipient’s first name. It returns line items across all orders. The string can have up to 100 characters.

recipientLastName

string

The recipient’s last name. It returns line items across all orders. The string can have up to 100 characters.

accountIdentifier

string

The account identifier used to place an order. It returns line items across all orders (5-100 characters).

campaign

string

Specifies the campaign to be queried. The maximum length is 1024 characters including the special characters such as @, #, %, etc.

purchaseOrderNumber

string

optional

A unique identifier assigned to a purchase order. It's a custom reference string that allows you to associate a Tango reward order with your own internal purchase order system used for tracking.

orderNotes

string

Specifies the orderNotes to be queried. orderNotes is a custom text field that allows you to attach internal notes or comments to an order when placing it via the API. it can be used for internal tracking such as purpose or details of the order.

recipientStreetLine1

string

Specifies the recipientStreetLine1 to be queried. It includes the first line of the recipient’s street address, typically including: street number, street name, and apartment or suite number (if applicable). This field is used when the deliveryMethod=PHYSICAL.

recipientStreetLine2

string

Specifies the recipientStreetLine2 to be queried. It represents the second line of the recipient’s street address, typically used for: apartment, suite, or unit numbers, building names, and additional address details that don’t fit in recipientStreetLine1. This field is used when the deliveryMethod=PHYSICAL.

recipientCity

string

Specifies the recipientCity to be queried. It's used to specify the city portion of the recipient’s address when placing an order for physical delivery.

recipientStateOrProvince

string

Specifies the recipientStateOrProvince to be queried. It's used to specify the state or province portion of the recipient’s address when placing an order for physical delivery.

recipientPostalCode

string

Specifies the recipientPostalCode to be queried. It's used to specify the postal or ZIP code of the recipient’s address when placing an order for physical delivery.

recipientCountry

string

Specifies the recipientCountry to be queried.

startDate

string

Specifies the starting date or date time to be queried according to RFC 3339 standard. For example: "2025-01-01" or "2025-01-01T00:00:00Z" that includes date-time with timezone. See https://www.ietf.org/rfc/rfc3339.txt

endDate

string

Specifies the ending date or date time to be queried according to RFC 3339 standard. For example: "2025-01-01" or "2025-01-01T00:00:00Z" that includes date-time with timezone. See https://www.ietf.org/rfc/rfc3339.txt

columnSortName

string

Is used when querying lists of data like line items to specify which column to sort the results by. The predefined values for this field are as follows. The column sort name defaults to dateIssued:

  • accountNumber: The unique identifier of the account from which a reward order was placed. See account numbers.
  • amountIssued: The amount or value of the reward that was issued.
  • dateIssued: Refers to the date and time when a reward order was placed. If columnSortName is not specified, it sorts by dateIssued.
  • emailStatus: Refers to the status of the email delivery for a reward order. It helps track whether the reward email was successfully sent, is pending, or failed. See Email status.
  • deliveryMethod: Refers to the method of reward delivery such as NONE, EMAIL, PHONE, and ADDRESS.
  • externalReferenceId: An optional idempotent field. Tango allows one unique order per external reference ID. You cannot create a duplicate order with the same externalReferenceId. See Idempotent external Reference ID.
  • status: Refers to the current state of a line item. It helps you track the progress or outcome of a reward transaction.
  • orderSource: Refers to the origin or method by which an order was placed such as RA (Tango API), RG (Tango portal), etc. See orderSource filed.
  • orderStatus: Refers to the current state of a reward order. It helps track the lifecycle of an order from creation to completion or failure such as complete, pending, failed, etc. See orderStatus field above.
  • recipientFirstName: Is used to specify the first name of the reward recipient when placing an order. The recipient’s first name up to 100 characters.
  • recipientLastName: Is used to specify the last name (surname) of the reward recipient when placing an order. The recipient’s last name up to 100 characters.
  • rewardName: Is used to describe or label the reward being issued in an order. It is typically a custom, user-defined string that helps identify the reward in reporting, tracking, or recipient communication.

columnSortAscending

boolean

-Truesorts by ascending order for the column specified in columnSortName.

  • Falsesorts by descending order for the column specified in columnSortName.
  • If columnSortName is not specified, it sorts by dateIssued.

elementsPerBlock

int32

Specifies the number of elements returned by page.

pagePrevious

boolean

  • True returns the previous page
  • False returns the next page

pageKeys

array of strings

This filter uses keyset paging. To move to the next page, use the nextPageKeys object from the keySetPage object. The nextKeyPage object is an array of two strings.


The following example shows how the line items are structured in the payload when you use GET {URI}/lineItems. The recipient information is included in all returning payloads as well as in any query parameters used to filter or search the recipient information. The reward status indicates whether a reward is frozen or active.

{
  "keysetPage": {
    "nextPageKeys": [
      "string"
    ],
    "previousPageKeys": [
      "string"
    ],
    "resultCount": 0,
    "totalCount": 0
  },
  "lineItems": [
    {
      "referenceLineItemID": "string",
      "referenceOrderID": "string",
      "orderSource": "string",
      "status": "string",
      "orderStatus": "string",
      "emailStatus": "string",
      "deliveryMethod": "string",
      "rewardStatus": "string",
      "canCancel": true,
      "canFreeze": true,
      "lineNumber": 0,
      "rewardName": "string",
      "amountIssued": {
        "value": 0,
        "currencyCode": "string",
        "exchangeRate": 0,
        "fee": 0,
        "total": 0
      },
      "amountCharged": {
        "value": 0,
        "currencyCode": "string",
        "exchangeRate": 0,
        "fee": 0,
        "total": 0
      },
      "dateIssued": "2025-07-01T21:42:07.744Z",
      "expirationDate": "2025-07-01T21:42:07.744Z",
      "accountNumber": "string",
      "accountIdentifier": "string",
      "etid": "string",
      "ptid": "string",
      "utid": "string",
      "customerIdentifier": "string",
      "recipient": {
        "email": "string",
        "mobileNumber": "string",
        "firstName": "string",
        "lastName": "string",
        "address": {
          "streetLine1": "string",
          "streetLine2": "string",
          "city": "string",
          "stateOrProvince": "string",
          "postalCode": "string",
          "country": "string"
        }
      },
      "sender": {
        "firstName": "string",
        "lastName": "string",
        "email": "string"
      },
      "purchaseOrderNumber": "string",
      "campaign": "string",
      "orderNotes": "string",
      "lineItemActionReason": "string",
      "reissuedFromReferenceLineItemId": "string",
      "reissuedToReferenceLineItemId": "string"
    }
  ]
}

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": [
    {}
  ]
}

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

ResponseDescription
200The request was successful.
400The server could not understand the request due to invalid syntax.
401Authentication is required and has either not been provided or failed.
403The server understood the request but refuses to authorize it.
500Something went wrong on the server, but the server cannot be more specific about what the exact problem is.

© 2025 Tango API are provided by Tango, a division of BHN, Inc.