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:

EndpointDescription
GET {URI}/lineItemsGet 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 , and deliveryStatus. 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
The available values are:

  • COMPLETE
  • PENDING
  • FAILED
  • CANCELLED

emailStatus

string

The email status to be retrieved for each line item. The email can only be sent if sendEmail= true. See Email statuses . 🚧 Coming soon: sendEmail will be deprecated soon. It will only appear in the payload once the deliveryMethod is released.
The available values are:

  • DELIVERED
  • NOT_DELIVERED
  • PENDING
  • SENT
  • DEFERRED
  • DROPPED
  • BOUNCE
  • BLOCKED

deliveryMethod
(🚧 Coming soon)

string

Specify the delivery method for an order to determine how a reward is sent to a recipient. deliveryMethod will replace sendEmail once released:
-NONE: Tango does not deliver. You are responsible to deliver the rewards to your recipient. This option is similar to sendEmail=false.
-EMAIL: Tango delivers the reward to the recipient via email. You must include the recipient email. This option is similar to sendEmail=true.
-SMS: Tango delivers the reward to the recipient via text. You must include the recipient phone number.
-CARRIER: Tango delivers the physical rewards via a carriers such as the post office, FexEx, UPS, etc. You must include the recipient address.
-EMBEDDED: You will embed Tango's lading page into your application. Tango will not deliver the rewards.

orderStatus

string

The order status to be retrieved for each line item. See order status .
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: The rewards are sent through Tango API. Tango API users see the two-letter identifiers when they use:
    -GET {URI}/lineItem under "OrderSource
    • GET {URI}/orders/{referenceOrderID} under "orderClientSource"
  • RG: The rewards are sent through Tango portal by email or mail delivery.
  • BE: The rewards are sent through Blast External (BE) or bulk upload for 15-50,000 recipients per order.
  • BI: Orders placed using bulk-internal upload.
  • CI: Rewards are sent manually by the Tango Orders team. Contact your Customer Success Manger (CSM) or [email protected] if you are interested in working with the Tango Orders team to send rewards.
  • QW: Rewards Links are sent via Qualtrics (QW) or Tango integration. Contact your Customer Success Manger (CSM) or [email protected] if you are interested in integrating Tango with Qualtrics.

recipientEmail

string

A recipient's email address. It returns Line Items across all orders.

recipientMobileNumber
(🚧 Coming soon)

string

Specify the recipient mobile number to be queried. MobileNumber is required if deliveryMethod is SMS. The following validation rules apply to mobile numbers for SMS delivery:

  • Country Code: Must be included.
  • Format: +CCCPPPPPPPPPPPP (where C is the country code, 1-3 digits, and P is the phone number, up to 12 digits).
  • Initial Release: Only accepts US phone numbers (Country code = +1) and 10 digits for the phone number.
    -Standard: Follows ITU E.164, allowing (+) and up to 15 digits for the combined country code and phone number.

deliveryStatus
(🚧 Coming soon)

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:

  • accountNumber: The account the order was placed from. See account numbers.
  • amountIssued: The order amount
  • dateIssued: (default), the date and time the order was placed.
  • emailStatus: The reward email status such as delivered, not delivered, pending, etc. See Email status.
  • deliveryMethod: (🚧 Coming soon) Use the deliveryMethod such as none, email, SMS, etc. to determine how a reward is sent to a recipient.
    -externalReferenceId: An optional idempotent field. Tango allows one unique order per External Reference ID. See Idempotent external Reference ID.
  • status:
  • orderSource: Such as RA (Tango API), RG (Tango portal), etc. See above.
  • orderStatus: Such as complete, pending, failed, etc. See above.
  • recipientFirstName: The recipient’s first name up to 100 characters.
  • recipientLastName: The recipient’s last name up to 100 characters.
  • rewardName:(If columnSortName is not specified, it sorts by dateIssued.)

columnSortAscending

boolean

-Truesorts by ascending order for the column specified in columnSortName.

  • Falsesorts 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 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:

ResponseDescription
200The request was successful.
400The server could not understand the request due to invalid syntax.
401Authentication is required and has either not been provided or failed.
403The server understood the request but refuses to authorize it.
500Something went wrong on the server, but the server cannot be more specific about what the exact problem is.

© 2025 Tango API are provided by Tango, a division of BHN, Inc.