Manage orders

With Tango, you can incentivize your employees and customers by sending digital or printed rewards. Using Tango API, you can generate reward credentials, send rewards to recipients by email, and resend reward emails. See the following endpoints for more information:

❗️
Disclaimer:

When ordering a physical gift card, make sure to validate the physical address of your reward recipients before sending it to Tango. Tango does not accept any responsibilities for the incorrect addresses.

Tango does not deliver the reward email when sendEmail= false. When placing orders, you are responsible to deliver rewards if sendEmail=false.

📘
Note:

If you submit a recipient firstName and emailAddress with a Promo Link order when sendEmail=false, Tango will send out the reminder emails and the reactivation emails when reactivated from the Tango portal.

Order requests receiving a 5XX error may occasionally process after a network connection is lost. We strongly recommend you use the External Reference ID idempotent parameter to ensures duplicate orders are not created when you retry a failed order. See our Best practices content regarding External Reference ID idempotent parameter.

credentials is deprecated and should no longer be used.

Instead, use the credentialList array under the reward block. credentailList contains type, label, and value, and stable parameters that allow our clients to display rewards within an application or by email.

Get a list of orders placed under this platform

Use the following endpoint to get a list of orders placed under this platform:

Endpoint	Purpose
`GET {URI}/orders`	Get a list of Orders placed under this platform.

📘
Note:
GET {URI}/orders currently only returns 10K results. Use query parameters to better filter your search results.

Here is a list of query parameters for when you use GET {URI}/orders to get a list of orders placed under this platform.

Query parameter	Data type	Description
accountIdentifier	string	Specify the account to be queried. The string must have 5-100 characters.
customerIdentifier	string	Specify the customer to be queried. The string must have 5-100 characters.
externalRefID	string	Specify the external reference ID to be queried. The string may have up to 100 alphanumeric characters.
startDate	string	Specify 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	Specify 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
elementsPerBlock	int32	Specify the number of elements in a block.
page	int32	Specify the page number to return.
minAmount	double	Specify the minimum face value of the reward to be queried. 👍 Best practice: When you are searching for an amount, we recommend you to enter a minimum and a maximum amount for the search.
maxAmount	double	Specify the maximum face value of the reward to be queried. 👍 Best practice: When you are searching for an amount, we recommend you to enter a minimum and a maximum amount for the search.
currencyCode	string	Specify the currency code of the reward to be queried. The string must be three characters.
utid	string	Specify the unique identifier of the reward to be queried.
ptid	string	🚧 Coming soon Specify the unique identifier of the physical delivery template to be queried. ptid is required for orders where the UTID is Reward Type = Reward Link, Fulfillment Type = Physical.
rewardName	string	Specify the reward name of the reward to be queried.
senderFirstName	string	Specify the sender's first name to be queried. This information is for tracking purposes only and doesn’t change the email address the reward is sent from when `sendEmail: true`. The `senderFirstName` may have up to 100 characters. You cannot use < or > or / in the name.
senderLastName	string	Specify the sender's last name to be queried. This information is for tracking purposes only and doesn’t change the email address the reward is sent from when `sendEmail: true`. The `senderlastName` may have up to 100 characters. You cannot use < or > or / in the name..
senderEmail	string	Specify the sender email address to be queried. This information is for tracking purposes only and doesn’t change the email address the reward is sent from when `sendEmail: true`.
recipientEmail	string	Specify the recipient’s email address to be queried.
recipientFirstName	string	Specify the recipient’s first name to be queried. The `recipientFirstName` may have up to 100 characters. You cannot use < or > or / in the name.
recipientLastName	string	Specify the recipient’s last name to be queried. The `recipientLastName` may have up to 100 characters. You cannot use < or > or / in the name.
sendEmail	boolean	Specify if sendEmail is true or false to be queried. ❗️ Disclaimer: When placing orders, you are responsible to deliver rewards if `sendEmail=false`. Tango does not deliver the reward email when `sendEmail= false`.
status	string	Specify the status to be queried.
lineItemStatus	string	Specify the status to be queried.
campaign	string	Specify the campaign to be queried. The string may have up to 100 characters.
notes	string	Specify the notes to be queried. The string may have up to 150 characters.
lineItemNotes	string	Specify the notes to be queried.
purchaseOrderNumber	string	specify the purchaseOrderNumber to be queried.

The following example shows the example response including pagination when you use GET {URI}/orders:

{
  "page": {
    "number": 0,
    "elementsPerBlock": 0,
    "resultCount": 0,
    "totalCount": 0
  },
  "orders": [
    {
      "referenceOrderID": "string",
      "externalRefID": "string",
      "customerIdentifier": "string",
      "accountIdentifier": "string",
      "accountNumber": "string",
      "amountCharged": {
        "value": 0,
        "currencyCode": "string",
        "exchangeRate": 0,
        "fee": 0,
        "total": 0
      },
      "denomination": {
        "value": 0,
        "currencyCode": "string",
        "exchangeRate": 0,
        "fee": 0,
        "total": 0
      },
      "utid": "string",
      "ptid": "string",
      "rewardName": "string",
      "sender": {
        "firstName": "string",
        "lastName": "string",
        "email": "string"
      },
      "recipient": {
        "email": "string",
        "firstName": "string",
        "lastName": "string",
        "address": {
          "streetLine1": "string",
          "streetLine2": "string",
          "city": "string",
          "stateOrProvince": "string",
          "postalCode": "string",
          "country": "string"
        }
      },
      "emailSubject": "string",
      "message": "string",
      "sendEmail": true,
      "etid": "string",
      "status": "string",
      "campaign": "string",
      "createdAt": "2023-10-12T16:28:34.439Z",
      "notes": "string",
      "orderClientSource": "string",
      "purchaseOrderNumber": "string"
    }
  ]
}

The response message for this endpoint is:

200 OK
400 Bad request
401 Unauthorized
403 Forbidden

Create an order under a specific account

Use the following endpoint to create an order under a specific account.

Endpoint	Purpose
`POST {URI}/orders`	Create an Order under a specific Account.

The POST {URI}/orders endpoint has a 1 TPS rate limit. If you receive an error when placing an order, wait for 1 second and try again with the same externalRefID.

Here is a list of body parameters for when you use thePOST {URI}/orders to create an order under a specific account. The recipient address object is required for physical rewards. For digital orders, it must be excluded or set to null.

📘
Note:
Providing an address for digital orders will result in validation failure.

Body parameter	Data type	Description
externalRefID	string	(Optional) An idempotent field that can be used for client-side Order cross reference and prevent accidental order duplication. Will be returned in order response, order details, and order history. This string has a maximum of 100 alphanumeric characters.
customerIdentifier	string	(Required) Specify the customer associated with the Order. Must be the `customerIdentifier` the `accountIdentifier` is associated with. The string must have 5-100 characters.
accountIdentifier	string	(Required) Specify the account this order will be deducted from. The string must have 5-100 characters.
utid	string	(Required) The unique identifier for the reward you are sending as provided in the `GET /catalog`s endpoint. The UTID must be in your platform catalog (and not just in a Tango Choice product catalog) to place the order.
amount	double	(Required) Specify the face value of the reward. Always required, including for fixed-value items. The amount is stored as a double-precision floating point number.
sender	object	(Optional) Use to set the sender’s name and email address if different than the default platform setting. This information is for tracking purposes only and doesn’t change the email address the reward is sent from when `sendEmail: true`. The sender's first name and last name may have up to 100 characters each.
-firstName	string	always optional (100 characters max). This information is for tracking purposes only and doesn’t change the email address the reward is sent from when `sendEmail: true`. The `senderFirstName` may have up to 100 characters. You cannot use < or > or / in the name.
-lastName	string	always optional (100 characters max). This information is for tracking purposes only and doesn’t change the email address the reward is sent from when `sendEmail: true`. The `senderLastName` may have up to 100 characters. You cannot use < or > or / in the name.
-email	string	always optional. This information is for tracking purposes only and doesn’t change the email address the reward is sent from when `sendEmail: true`.
recipient	object	(Required) If `sendEmail` is true. Use to set and store the recipient name and email address. When `sendEmail` is false, setting these parameters will allow the platform to store this information for reporting, auditing, and reconciliation.
-firstName	string	Required if `sendEmail` is true, or ordering a physical reward. The `recipientFirstName` may have up to 100 characters for digital rewards. You cannot use < or > or / in the name. If a physical reward, it may have up to 25 characters and can use Digits 0-9, alpha (a-z, A-Z), space period, comma, or hyphen.
-LastName	string	Required if ordering a physical gift card, for digital rewards it is optional. The `recipientLastName` may have up to 25 characters for physical, or 100 characters for digital. You cannot use < or > or / in the name. If a physical reward, it may include Digits 0-9, alpha (a-z, A-Z), space period, comma, or hyphen.
`-email`	string	Required if `sendEmail` is true. (100 characters max).
`-address`	object	Required for physical rewards. For digital orders, this field must be excluded or set to 'null'. Providing an address for digital orders will result in validation failure. ❗️Disclaimer: When ordering a physical gift card, make sure to validate the physical address of your reward recipients before sending it to Tango. Tango does not accept any responsibility for the incorrect addresses. NOTE: Do not pass an address object when the reward is digital.
`-streetLine1`	string	Required for physical rewards, not applicable for digital rewards (35 characters max). May include Digits 0-9, alpha (a-z, A-Z), space, period, comma, hyphen, forward slash (/), and apostrophe
`-streetLine2`	string	(Optional) for physical rewards, not applicable for digital rewards (35 characters max). May include Digits 0-9, alpha (a-z, A-Z), space, period, comma, hyphen, forward slash (/), and apostrophe
`-city`	string	Required for physical rewards, not applicable for digital rewards (30 characters max). May include Digits 0-9, alpha (a-z, A-Z), space, period, hyphen, and apostrophe
`-stateOrProvince`	string	Required for physical rewards, not applicable for digital rewards (must be a valid 2-character uppercase abbreviation for a U.S. state, territory, or military base; a Canadian province; or contain an international region less than 36 characters).
`-postalCode`	string	Required for physical rewards, not applicable for digital rewards may include Digits 0-9 and alpha (a-z, A-Z). For US addresses this must include the five-digit US ZIP Code only.
`-country`	string	Required for physical rewards, not applicable for digital rewards (2 characters).
emailSubject	string	(Optional) If not specified, a default email subject will be used for the specified reward.
message	string	(Optional) gift message. The string may have up to 3000 characters.
sendEmail	boolean	(Required) Should Tango send the email to the recipient?
etid		(Optional) Etid is the unique identifier for the email template you would like to use. Only applicable if `sendEmail` is true.
campaign	string	(Optional) Campaign may be used to administratively categorize a specific Order. The string may have up to 100 characters.
ptid	string	🚧 Coming soon Only required when ordering a Printed Reward Link. The unique identifier for the Printed Reward Link Template provided in the Tango Portal on the Printed Template page.
purchaseOrderNumber	string	(Optional) The Purchase Order Number associated with this order. The string may have up to 100 characters.
notes	string	(Optional) Order notes. The string may have up to 150 characters.
expirationDate	date-time	(Optional) This is optional for Promo Links, the exact calendar date the Promo Link will expire. See the Promo Link acceptance criteria.

The following example shows the response using thePOST {URI}/orders. Perform the call to order one of the UTIDs that was returned in your GET {URI}/catalogs call.

📘
Note:
credentials has been deprecated. Use credentialList instead.

{
  "referenceOrderID": "string",
  "externalRefID": "string",
  "customerIdentifier": "string",
  "accountIdentifier": "string",
  "amountCharged": {
    "value": 0,
    "currencyCode": "string",
    "exchangeRate": 0,
    "fee": 0,
    "total": 0
  },
  "denomination": {
    "value": 0,
    "currencyCode": "string",
    "exchangeRate": 0,
    "fee": 0,
    "total": 0
  },
  "utid": "string",
  "ptid": "string",
  "rewardName": "string",
  "reward": {
    "credentials": {
      "additionalProp": "string"
    },
    "credentialList": [
      {
        "label": "string",
        "value": "string",
        "type": "string",
        "credentialType": "string"
      }
    ],
    "redemptionInstructions": "string"
  },
  "sender": {
    "firstName": "string",
    "lastName": "string",
    "email": "string"
  },
  "recipient": {
    "email": "string",
    "firstName": "string",
    "lastName": "string",
    "address": {
      "streetLine1": "string",
      "streetLine2": "string",
      "city": "string",
      "stateOrProvince": "string",
      "postalCode": "string",
      "country": "string"
    }
  },
  "emailSubject": "string",
  "message": "string",
  "sendEmail": true,
  "status": "string",
  "campaign": "string",
  "purchaseOrderNumber": "string",
  "createdAt": "2023-10-12T16:28:34.439Z",
  "redemptionInstructions": "string"
}

Here is an example for when you use POST {URI}/orders to create an order with Promo link. You can set expiration date for Promo Link at the time of the order:

📘
Note:
credentials has been deprecated. Use credentialList instead.

{
  "referenceOrderID": "string",
  "externalRefID": "string", (100 chars)
  "customerIdentifier": "string", (5-100 chars)
  "accountIdentifier": "string", (5-100 chars)
  "accountNumber": "string", (5-100 chars)
  "amountCharged": {
    "value": 10.00,
    "currencyCode": "USD",
    "total": 10.0
  },
  "denomination": {
    "value": 10.0,
    "currencyCode": "USD"
  },
  "utid": "string",
  "rewardName": "Promo Link",
  "sender": {
    "firstName": "string",
    "lastName": "string",
    "email": "string"
  },
  "recipient": {
    "email": "string",
    "firstName": "string", (100 chars)
    "lastName": "string", (100 chars)
    "address": null
  },
  "sendEmail": false,
  "status": "COMPLETE",
  "createdAt": "2023-10-11T23:10:55.284Z",
  "reward": {
    "credentials": {
      "redemptionUrl": "https://gamma.rewardlink.io/r/1/Cl4e2dX_qz3zyUbSTb4dZgrbQta9qg-oBd6sPkywiIk",
      "expirationDate": "2024-12-31T06:59:59Z"
    },
    "credentialList": [
      {
        "label": "redemptionUrl",
        "value": "https://gamma.rewardlink.io/r/1/Cl4e2dX_qz3zyUbSTb4dZgrbQta9qg-oBd6sPkywiIk",
        "type": "url",
        "credentialType": "redemptionUrl"
      },
      {
        "label": "expirationDate",
        "value": "2024-12-31T06:59:59Z",
        "type": "date",
        "credentialType": "expirationDate"
      }
    ],
    "redemptionInstructions": "string"
  }
}

The response message for this endpoint is:

200 Duplicate externalRefID, payload returns the original payload. No money is subtracted from the account.
201 Created
400 Bad Request
401 Unauthorized
402 Insufficient Funds
403 Forbidden
409 Duplicate server order in flight
429 Exceeded the allowable TPS rate limit
503 Service Unavailable

Get details for a specific order

Use the following endpoint to retrieve details for a specific order.

Endpoint	Purpose
`GET {URI}/orders/{referenceOrderID}`	Get details for a specific Order.

Here is the path parameter when you use GET {URI}/orders/{referenceOrderID} to get details for a specific order.

Path parameter	Data type	Description
referenceOrderID	string	Reference Order ID is returned in the order response payload

The following example shows a response for the order placed in the past. Perform a GET {URI}/orders/{referenceOrderID} to view the details of an old order you have placed in the system.

📘
Note:
credentials has been deprecated. Use credentialList instead.

{
  "referenceOrderID": "string",
  "externalRefID": "string", (100 chars)
  "customerIdentifier": "string", (5-100 chars)
  "accountIdentifier": "string", (5-100 chars)
  "accountNumber": "string", (5-100 chars)
  "amountCharged": {
    "value": 0,
    "currencyCode": "string",
    "exchangeRate": 0,
    "fee": 0,
    "total": 0
  },
  "denomination": {
    "value": 0,
    "currencyCode": "string",
    "exchangeRate": 0,
   },
  "denomination": {
    "value": 0,
    "currencyCode": "string",
    "exchangeRate": 0,
    "fee": 0,
},
  "denomination": {
    "value": 0,
    "currencyCode": "string",
    "exchangeRate": 0,
    "fee": 0,
    "total": 0
  },
  "utid": "string",
  "rewardName": "string",
  "sender": {
    "firstName": "string", (100 chars)
    "lastName": "string", (100 chars)
    "email": "string"
  },
  "recipient": {
    "email": "string",
    "firstName": "string", (100 chars)
    "lastName": "string", (100 chars)
    "address": {
      "streetLine1": "string",
      "streetLine2": "string",
      "city": "string",
      "stateOrProvince": "string",
      "postalCode": "string",
      "country": "string"
    }
  },
  "emailSubject": "string",
  "message": "string", (1024 chars)
  "sendEmail": true,
  "etid": "string",
  "ptid": "string",
  "status": "string",
  "campaign": "string", (100 chars)
  "createdAt": "2023-09-18T19:36:27.589Z",
  "notes": "string", (150 chars)
  "orderClientSource": "string",
  "purchaseOrderNumber": "string",
  "reward": {
    "credentials": {
      "additionalProp": "string"
    },
    "credentialList": [
      {
        "label": "string",
        "value": "string",
        "type": "string",
        "credentialType": "string"
      }
    ],
    "redemptionInstructions": "string"
  }
}

The following example shows a Promo Link with an expiration date when you perform a GET {URI}/orders/{referenceOrderID} to view the details of a previously placed order. Note that expirationDate is now part of the reward credentialList:

📘
Note:
credentials has been deprecated. Use credentialList instead.

{
  "referenceOrderID": "string",
  "externalRefID": "string",
  "customerIdentifier": "string",
  "accountIdentifier": "string",
  "accountNumber": "string",
  "amountCharged": {
    "value": 10.00,
    "currencyCode": "USD",
    "total": 10.0
  },
  "denomination": {
    "value": 10,
    "currencyCode": "USD"
  },
  "utid": "string",
  "rewardName": "Promo Link",
  "sender": {
    "firstName": "string",
    "lastName": "string",
    "email": "string"
  },
  "recipient": {
    "email": "string",
    "firstName": "string",
    "lastName": "string",
    "address": null
  },
  "sendEmail": false,
  "status": "COMPLETE",
  "createdAt": "2023-10-11T23:10:55.284Z",
  "reward": {
    "credentials": {
      "redemptionUrl": "string",
      "expirationDate": "2024-12-31T06:59:59Z"
    },
    "credentialList": [
      {
        "label": "redemptionUrl",
        "value": "string",
        "type": "url",
        "credentialType": "redemptionUrl"
      },
      {
        "label": "expirationDate",
        "value": "2024-12-31T06:59:59Z",
        "type": "date",
        "credentialType": "expirationDate"
      }
    ],
    "redemptionInstructions": "Promo Link Test Redemption Instructions"
  }
}

📘
Order history:
Orders placed via the Tango API are v1 available via the v2 GET {URI}/orders call and are combined with Orders placed via the Tango API v2. To retrieve full order details, including reward credentials, make a GET {URI}/orders/{referenceOrderId} call.

The response message for this endpoint is:

200 OK
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found

Resend a specific order

Use the following endpoint to resend a specific order.

Endpoint	Purpose
`POST {URI}/orders/{referenceOrderID}/resends`	Resend a specific Order.

Here is the path parameter when you use thePOST {URI}/orders/{referenceOrderID}/resends to resend a specific order:

Path parameter	Data type	Description
referenceOrderID	string	(Required) Reference Order ID is returned in the Order response payload. (path parameter)

The following body parameters are used when you use POST {URI}/orders/{referenceOrderID}/resends to resend a specific order:

Body parameter	Data type	Description
newEmail	string	A new email to resend this Order to. (body parameter)
newEtid	string	A new etid for resending an order. Etid is the unique identifier for the email template you would like to use. The default Email Template ID is E000000.

The Resend method allows you to resend reward emails to the original recipient on demand. This may be useful if a recipient reports that they never received the reward email or cannot find it.

The following example shows a past order is resent using POST {URI}/orders/{referenceOrderID}/resends.

{
  "id": 0,
  "legacyId": "string",
  "createdAt": "2024-03-25T22:46:39.922Z",
  "email": "string"
}

The response message for this endpoint is:

201 Created
400 Bad Request
401 Unauthorized
403 Forbidden

To send the target order (resent), you must set the sendEmail property value to true (default) which means Tango has sent the original email. If the property value is set to false, it indicates that we have never sent the original email, therefore, we cannot resend it.

📘
Note:

Orders can be resent once every 30 seconds. The error message timestamp notifies you if a second attempt is made less than 30 seconds following the last send.

Resends of orders placed via the Tango API v1 are handled in the same fashion as resends of Orders placed via the Tango API v2. Only orders where Tango sent the original email can be resent by Tango . If you delivered reward credentials directly to your recipients, you need to retrieve them again via the GET {URI}/orders/{referenceOrderId} call.

You need the original order number to perform the resend. The Tango order History call allows searching past orders. The order number is included in the order result.

📘
Note:

Orders can be resent to a new email address, but to the same recipient. A reward links is tied to the same email address.

If an administrator needs to verify reward information for a given order, consider using the Get order Information call instead of the Resend a Reward Email call.

Resending an email does not guarantee delivery. If the recipient does not receive an email due to spam filter settings, corporate firewalls, etc. resending an email may not be enough. The underlying problem must be determined and resolved.

Manage orders

❗️
Disclaimer:

📘
Note:

Get a list of orders placed under this platform

📘
Note:

Create an order under a specific account

📘
Note:

📘
Note:

📘
Note:

Get details for a specific order

📘
Note:

📘
Note:

📘
Order history:

Resend a specific order

📘
Note:

📘
Note:

❗️Disclaimer:

📘Note:

Get a list of orders placed under this platform

📘Note:

Create an order under a specific account

📘Note:

📘Note:

📘Note:

Get details for a specific order

📘Note:

📘Note:

📘Order history:

Resend a specific order

📘Note:

📘Note:

❗️
Disclaimer:

📘
Note:

📘
Note:

📘
Note:

📘
Note:

📘
Note:

📘
Note:

📘
Note:

📘
Order history:

📘
Note:

📘
Note: