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:
Endpoint | Description |
---|---|
GET {URI}/lineItems | Get 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 |
externalRefID | string | optional | An idempotent identifier that is strongly recommended to use when creating orders. If you retry a failed order with the same |
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 | |
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 | |
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 | string | Specifies the delivery method for an order to determine how a reward is sent to a recipient:
| |
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:
| |
recipientEmail | string | A recipient's email address. It returns line items across all orders. | |
recipientMobileNumber | string | Specifies the recipient mobile number to be queried.
| |
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 | |
recipientStreetLine1 | string | Specifies the | |
recipientStreetLine2 | string | Specifies the | |
recipientCity | string | Specifies the | |
recipientStateOrProvince | string | Specifies the | |
recipientPostalCode | string | Specifies the | |
recipientCountry | string | Specifies the | |
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
| |
columnSortAscending | boolean | -Truesorts by ascending order for the column specified in
| |
elementsPerBlock | int32 | Specifies the number of elements returned by page. | |
pagePrevious | boolean |
| |
pageKeys | array of strings | This filter uses keyset paging. To move to the next page, use the |
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:
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. |
500 | Something went wrong on the server, but the server cannot be more specific about what the exact problem is. |
Updated 4 days ago