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. 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. |
Coming soon:This endpoint will soon be modified to include more query parameters such as
deliveryMethod
,recipientMobileNumber
, anddeliveryStatus
. Once released, you can deliver rewards to your recipients using delivery methods such as PHONE, ADDRESS, and EMBEDDED besides EMAIL.
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 | 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. See Line item status
|
emailStatus | string | The email status to be retrieved for each line item. The email can only be sent if
|
deliveryMethod | string | Specify the delivery method for an order to determine how a reward is sent to a recipient. deliveryMethod will replace sendEmail once released: |
orderStatus | string | The order status to be retrieved for each line item. See order status . |
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 | Specify the recipient mobile number to be queried. MobileNumber is required if
|
deliveryStatus | string | Will contain the email, SMS, and physical delivery status. |
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 | Specify the campaign to be queried. The maximum length is 1024 characters including the special characters such as @, #, %, etc. |
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:
|
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 8 days ago