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 , and deliveryStatus. Once released, you can deliver rewards to your recipients using delivery methods such as SMS, CARRIER, 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.
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	-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 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",
      "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-02-18T19:03:00.648Z",
      "expirationDate": "2025-02-18T19:03:00.648Z",
      "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",
      "lineItemActionReason": "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:

200 OK
400 Bad request
401 Unauthorized
403 Forbidden
500 Internal Server Error

📘Note:

🚧Coming soon:

📘
Note:

🚧
Coming soon: