Get a list of line items

Use Tango API line item endpoints to page through or filter a list of line items, including reward status, reward history, and redemption history. You can freeze, unfreeze, cancel, reissue or 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:

Endpoint	Description
`GET {URI}/lineItems`	Get a list of line items placed on this platform.

Here are a list of query parameters for when you use GET {URI}/lineItems to get a list of line items placed under this Platform:

Query params	Data type	Description
referenceOrderID	string	A unique identifier for an order
externalRefID	string	specifies the external reference order ID
utid	string	The unique identifier for the reward as provided in the Get Catalog call
ptid	string	The unique identifier for the Print Reward Link Template provided in the Tango Portal on the Printed Template page. Only applicable when sending a Printed Reward Links.
etid	string	The unique identifier for the email template. Only applicable when sendEmail = true.
status	string	The line item status to be retrieved for each line item. The available values are: -COMPLETE -PENDING -FAILED -CANCELLED See Line item status.
emailStatus	string	The email status to be retrieved for each line item. The available values are: - DELIVERED - NOT_DELIVERED - PENDING - SENT - DEFERRED - DROPPED - BOUNCE - BLOCKED See Email statuses.
orderStatus	string	The order status to be retrieved for each line item. The available values are: - COMPLETE - PENDING - FAILED - CANCELLED - PARTIAL
orderSource	string	The order source to be retrieved for each line item. The available values are: - RA (orders placed using Tango API) - RG (orders placed using Tango portal) - BE (orders placed using bulk-external upload) - BI (orders placed using bulk-internal upload) - CI (orders placed using code pulls) - QW (orders placed using Qualtrics)
recipientEmail	string	A recipient's email address. It returns Line Items across all orders.
recipientFirstName	string	The recipient’s first name. It returns Line Items across all orders. The string must have up to 100 characters.
recipientLastName	string	The recipient’s last name. It returns Line Items across all orders. The string must 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	Specify the campaign to be queried.
purchaseOrderNumber	string	Specify the purchaseOrderNumber to be queried.
orderNotes	string	Specify the orderNotes to be queried.
recipientStreetLine1	string	Specify the recipientStreetLine1 to be queried.
recipientStreetLine2	string	Specify the recipientStreetLine2 to be queried.
recipientCity	string	Specifty the recipientCity to be queried.
recipientStateOrProvince	string	Specify the recipientStateOrProvince to be queried.
recipientPostalCode	string	Specify the recipientPostalCode to be queried.
recipientCountry	string	Specify the recipientCountry to be queried.
startDate	string	Specifies the starting date or date time to be queried according to RFC 3339, i.e. "2025-01-01" or "2025-01-01T00:00:00Z". See https://www.ietf.org/rfc/rfc3339.txt
endDate	string	Specifies the ending date or date time to be queried according to RFC 3339, i.e. "2025-01-01" or "2025-01-01T00:00:00Z". See https://www.ietf.org/rfc/rfc3339.txt
columnSortName	string	Specifies the column name to sort by: - accountNumber - amountIssued - dateIssued - emailStatus - externalReferenceID - status - orderSource - orderStatus - recipientFirstName - recipientLastName - rewardName (If columnSortName is not specified, it sorts by `dateIssued`.)
columnSortAscending	boolean	-True sorts by ascending order for the column specified in `columnSortName`. - False sorts 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 the payload for when you use GET {URI}/lineItems to retrieve a list of line items. The recipient address (object) is included in all returning payloads, as well as in any query parameters that can 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",
      "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-02-18T19:03:00.648Z",
      "expirationDate": "2025-02-18T19:03:00.648Z",
      "accountNumber": "string",
      "accountIdentifier": "string",
      "etid": "string",
      "ptid": "string",
      "utid": "string",
      "customerIdentifier": "string",
      "recipient": {
        "email": "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"
    }
  ]
}

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:

200 OK
400 Bad request
401 Unauthorized
403 Forbidden
500 Internal Server Error

📘Note:

📘
Note: