Manage orders
With Tango API, you can manage rewards orders, get a list of orders that have been placed, get details for specific orders, or resend an undelivered order.
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.
Notes:
- When placing orders, you are responsible to deliver rewards if
sendEmail=false
. Tango does not deliver the reward email whensendEmail= false
.- If you submit a
recipient firstName
andemailAddress
with a Promo Link order whensendEmail=false
, Tango will send out the reminder emails and the reactivation emails when reactivated from the Tango Portal.- For the best data mapping experience, inspect the
credentialList
array under the reward block.- Credentials is a legacy parameter with no data mapping key/value pairs.
CredentialList
contains type, label, and value, and stable parameters that allow our clients to display rewards within an application or by email.- 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.
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. |
Here is a list of query parameters for when you use GET {URI}/orders
to get a list of orders placed under this platform.
Note:
When you are searching for an amount, we recommend you to enter a minimum and a maximum amount for search.
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. |
maxAmount | Double | Specify the maximum face value of the reward to be queried. |
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. |
rewardName | string | Specify the reward name of the reward to be queried. |
senderFirstName | string | Specify the sender's first name to be queried. The string may have up to 100 characters. |
senderLastName | string | Specify the sender's last name to be queried. The string may have up to 100 characters. |
senderEmail | string | Specify the sender email address to be queried. |
recipientEmail | string | Specify the recipient’s email address to be queried. |
recipientFirstName | string | Specify the recipient’s first name to be queried. The string may have up to 100 characters. |
recipientLastName | string | Specify the recipient’s last name to be queried. The string may have up to 100 characters. |
sendEmail | boolean | Specify if sendEmail is true or false to be queried. |
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 response message for this endpoint is:
- 200 OK
- 400 Bad request
- 401 Unauthorized
- 403 Forbidden
The following example shows the response including pagination when you use GET {URI}/orders
:
{
"page": {
"number": 0,
"elementsPerBlock": 25,
"resultCount": 25,
"totalCount": 10000
},
"orders": [
{
"referenceOrderID": "RA230510-100558-92",
"customerIdentifier": "string", (5-100 chars)
"accountIdentifier": "string", (5-100 chars)
"accountNumber": "A26904565",
"amountCharged": {
"value": 1,
"currencyCode": "string", (3 chars)
"total": 1
},
"utid": "U163059",
"rewardName": "Amazon.com Gift Card",
"sender": {
"firstName": "string", (100 chars)
"lastName": "string", (100 chars)
"email": "string", (100 chars)
},
"recipient": {
"email": "string", (100 chars),
"firstName": "string", (100 chars),
"lastName": "string", (100 chars),
"address": null
},
"emailSubject": "干得好",
"message": "string", (10240 chars)
"sendEmail": true,
"etid": "E000000",
"status": "COMPLETE",
"campaign": "string", (100 chars)
"createdAt": "2023-05-10T16:33:18.707Z"
}
}
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. |
Here are a list of body parameters for when you use POST {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. See more about External Reference ID. 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 /catalogs 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. The sender's firstName and lastName may have up to 100 characters each. |
-firstName | string | always optional (100 characters max) |
-lastName | string | always optional (100 characters max) |
string | always optional | |
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 (100 character max). |
-LastName | string | always optional (100 character max) |
string | required if sendEmail is true. | |
-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 responsibilities for the incorrect addresses. |
-streetLine1 | string | Required for physical rewards, not applicable for digital rewards (200 characters max). |
-streetLine2 | string | (Optional) for physical rewards, not applicable for digital rewards (100 characters max). |
-city | string | Required for physical rewards, not applicable for digital rewards (60 characters max). |
-stateOrProvince | string | Required for physical rewards, not applicable for digital rewards (60 characters max). |
-postalCode | string | Required for physical rewards, not applicable for digital rewards (12 characters). |
-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 1024 characters. |
sendEmail | boolean | (Required) Should Tango send the email to the recipient? |
etid | (Optional) 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. |
purchaseOrderNumber | string | (Optional) The Purchase Order Number associated with this order. |
notes | string | (Optional) Order notes. The string may have up to 150 characters. |
The response message for this endpoint is:
- 201 Created
- 400 Bad Request
- 401 Unauthorized
- 402 Insufficient Funds
- 403 Forbidden
- 503 Service Unavailable
The following example shows the response using POST {URI}/orders
. Perform the call to order one of the UTIDs that was returned in your GET {URI}/orders
call.
{
"page": {
"number": 0,
"elementsPerBlock": 0,
"resultCount": 0,
"totalCount": 0
},
"orders": [
{
"referenceOrderID": "string",
"externalRefID": "string",
"customerIdentifier": "string", (5-100 chars)
"accountIdentifier": "string", (5-100 chars)
"accountNumber": "string",
"amountCharged": {
"value": 0,
"currencyCode": "string", (3 chars)
"exchangeRate": 0,
"fee": 0,
"total": 0
},
"denomination": {
"value": 0,
"currencyCode": "string",
"exchangeRate": 0,
"fee": 0,
"total": 0
},
"utid": "string",
"rewardName": "string",
"sender": {
"firstName": "string", (5-100 chars)
"lastName": "string", (5-100 chars)
"email": "string"
},
"recipient": {
"email": "string",
"firstName": "string", (5-100 chars)
"lastName": "string", (5-100 chars)
"address": {
"streetLine1": "string", (200 chars)
"streetLine2": "string", (100 chars)
"city": "string", (60 chars)
"stateOrProvince": "string", (60 chars)
"postalCode": "string", (12 chars)
"country": "string" (2 chars)
}
},
"emailSubject": "string",
"message": "string", (1024 chars)
"sendEmail": true,
"etid": "string",
"status": "string",
"campaign": "string",
"createdAt": "2023-09-18T17:18:05.159Z",
"notes": "string",
"orderClientSource": "string",
"purchaseOrderNumber": "string"
}
]
}
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 response message for this endpoint is:
- 200 OK
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
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.
{
"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,
"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",
"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"
}
}
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 aGET {URI}/orders/{referenceOrderId}
call.
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 POST {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) |
Here is the Body parameter 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) |
The response message for this endpoint is:
- 201 Created
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
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
.
{
"newEmail": "[email protected]"
}
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.
Updated 4 days ago