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
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
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.
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. "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. 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.

{
  "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": "2024-01-27T02:03:29.393Z",
      "expirationDate": "2024-01-27T02:03:29.393Z",
      "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"
    }
  ]
}

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 line item details. The recipient address object is included in all returning payloads. 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": "2024-01-27T01:15:58.065Z",
  "expirationDate": "2024-01-27T01:15:58.065Z",
  "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",
  "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": "2024-01-27T01:15:58.065Z",
      "expirationDate": "2024-01-27T01:15:58.065Z",
      "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"
    }
  ]
}

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"
}