Manage line items
One or more Line Items are included in each order. Each line item represents a single gift card, reward, disbursement, or promotional link. A line item shows the items's unique reference number, customer's first name, last name, email address, dollar amount, etc. Each line item can be managed separately when a request fails due to an undeliverable email or a misspelled recipient's name, for example.
Use our Line Item endpoints to page through or filter a list of line items, including their non-sensitive details and reward status. You can also view details for a specific Line Item, including sensitive details, reward history, redemption history, or resend a specific line item.
Get a list of line items placed under this platform
Use the following endpoint to retrieve line items ordered under this platform:
Endpoint | Description |
---|---|
GET {URI}/lineItems | Get a list of Line Items placed under 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:
Parameter | Data Type | Description |
---|---|---|
referenceOrderID | string | A unique identifier for an order |
externalRefID | string | specifies the external reference order ID |
status | string | The line item status to be retrieved for each line item. The available values are: -COMPLETE -PENDING -FAILED -CANCELLED |
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 |
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. |
startDate | string | Specifies the starting date or date time to be queried according to RFC 3339, i.e. "2016-01-01" or "2016-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. "2016-01-01" or "2016-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 response message for this endpoint is:
- 200 OK
- 400 Bad request
- 401 Unauthorized
- 403 Forbidden
The following example shows the response for when you use GET {URI}/lineItems
to retrieve a list of line items:
{
"keysetPage": {
"nextPageKeys": [
"string"
],
"previousPageKeys": [
"string"
],
"resultCount": 0,
"totalCount": 0
},
"lineItems": [
{
"referenceLineItemID": "string",
"referenceOrderID": "string",
"orderSource": "string",
"status": "string",
"orderStatus": "string",
"emailStatus": "string",
"lineNumber": 0,
"rewardName": "string",
"amountIssued": {
"value": 0,
"currencyCode": "string",
"exchangeRate": 0,
"fee": 0,
"total": 0
},
"dateIssued": "2023-09-18T17:18:05.159Z",
"expirationDate": "2023-09-18T17:18:05.159Z",
"accountNumber": "string",
"accountIdentifier": "string",
"etid": "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"
}
]
}
Get details for a specific line item
Use the following endpoint to retrieve the details such as reward credentials of a specific line item and the redemption history. For the real-time balance of the reward, you can subtract the redemption history from the total amount issued:
Endpoint | Description |
---|---|
GET {URI}/lineItems/{referenceLineItemID} | Get details for a specific line item. |
Here is a query parameter for when you use GET {URI}/lineItems/{referenceLineItemID}
to get the identification of the line item you request to get the details. The system autogenerates the identification, and you can find it by using the line item endpoint.
Parameter | Data Type | Description |
---|---|---|
referenceLineItemID | string | Reference line item ID is returned in the Line Items response. |
The response message for this endpoint is:
- 200 OK
- 400 Bad request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
The following example shows the response using GET {URI}/lineItems/{referenceLineItemID}
for when you get the details for a specific line items:
{
"referenceLineItemID": "string",
"referenceOrderID": "string",
"orderSource": "string",
"status": "string",
"orderStatus": "string",
"emailStatus": "string",
"lineNumber": 0,
"rewardName": "string",
"amountIssued": {
"value": 0,
"currencyCode": "string",
"exchangeRate": 0,
"fee": 0,
"total": 0
},
"dateIssued": "2023-09-18T17:18:05.159Z",
"expirationDate": "2023-09-18T17:18:05.159Z",
"accountNumber": "string",
"accountIdentifier": "string",
"etid": "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",
"reward": {
"credentials": {
"additionalProp": "string"
},
"credentialList": [
{
"label": "string",
"value": "string",
"type": "string",
"credentialType": "string"
}
],
"redemptionInstructions": "string"
},
"redemptionHistory": [
{
"referenceLineItemID": "string",
"referenceOrderID": "string",
"orderSource": "string",
"status": "string",
"orderStatus": "string",
"emailStatus": "string",
"lineNumber": 0,
"rewardName": "string",
"amountIssued": {
"value": 0,
"currencyCode": "string",
"exchangeRate": 0,
"fee": 0,
"total": 0
},
"dateIssued": "2023-09-18T17:18:05.159Z",
"expirationDate": "2023-09-18T17:18:05.159Z",
"accountNumber": "string",
"accountIdentifier": "string",
"etid": "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"
}
]
}
Resend a specific line item
Use the following endpoint to resend a specific Line Item to the same email address:
Endpoint | Description |
---|---|
POST {URI}/lineItems/{referenceLineItemId}/resends | Resend a specific Line Item. |
Here is a path parameter for when you use POST {URI}/lineItems/{referenceLineItemId}/resends
to resend a specific line item to the same email address. The identification of the line item you requested will be resent. The system autogenerates it, and you can find it by using the line item endpoint.
Parameter | Data Type | Description |
---|---|---|
referenceLineItemId | string | (Required) Reference line item id is returned in the line item response payload. |
The response message for this endpoint is:
- 201 Created
- 400 Bad request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
The following example shows the request for when you resend a specific line item to the same email address:
{
"id": 957806,
"legacyId":" string",
"createdAt": "2023-09-18T17:18:05.159Z",
"email": "string"
}
The following example shows the response for when you resend a specific line item to the same email address:
{
"ID": 0,
"Legacy ID (only when resending v1 orders)": "string",
"Created Date": "2022-11-14T17:02:45.166Z",
"Email address that the resend was sent to": "string"
}
Updated 4 days ago