Documentation

Manage orders

Suggest Edits

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:

EndpointPurpose
GET {URI}/ordersGet 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 parameterData typeDescription
accountIdentifierstringSpecify the account to be queried.
The string must have 5-100 characters.
customerIdentifierstringSpecify the customer to be queried.
The string must have 5-100 characters.
externalRefIDstringSpecify the external reference ID to be queried.
The string may have up to 100 alphanumeric characters.
startDatestringSpecify 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
endDatestringSpecify 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
elementsPerBlockint32Specify the number of elements in a block.
pageint32Specify the page number to return.
minAmountdoubleSpecify 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.
maxAmountdoubleSpecify 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.
currencyCodestringSpecify the currency code of the reward to be queried.
The string must be three characters.
utidstringSpecify the unique identifier of the reward to be queried.
ptidstring 🚧 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.
rewardNamestringSpecify the reward name of the reward to be queried.
senderFirstNamestringSpecify 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.
senderLastNamestringSpecify 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..
senderEmailstringSpecify 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.
recipientEmailstringSpecify the recipient’s email address to be queried.
recipientFirstNamestringSpecify the recipient’s first name to be queried.
The recipientFirstName may have up to 100 characters. You cannot use < or > or / in the name.
recipientLastNamestringSpecify the recipient’s last name to be queried.
The recipientLastName may have up to 100 characters. You cannot use < or > or / in the name.
sendEmailbooleanSpecify 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.
statusstringSpecify the status to be queried.
lineItemStatusstringSpecify the status to be queried.
campaignstringSpecify the campaign to be queried.
The string may have up to 100 characters.
notesstringSpecify the notes to be queried.
The string may have up to 150 characters.
lineItemNotesstringSpecify the notes to be queried.
purchaseOrderNumberstringspecify 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.

EndpointPurpose
POST {URI}/ordersCreate an Order under a specific Account.

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 parameterData typeDescription
externalRefIDstring(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.
customerIdentifierstring(Required) Specify the customer associated with the Order. Must be the customerIdentifier the accountIdentifier is associated with.
The string must have 5-100 characters.
accountIdentifierstring(Required) Specify the account this order will be deducted from.
The string must have 5-100 characters.
utidstring(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.
amountdouble(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.
senderobject(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.
-firstNamestringalways 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.
-lastNamestringalways 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.
-emailstringalways optional. This information is for tracking purposes only and doesn’t change the email address the reward is sent from when sendEmail: true.
recipientobject(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.
-firstNamestringRequired 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.
-LastNamestringRequired 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.
-emailstringRequired if sendEmail is true. (100 characters max).
-addressobjectRequired 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.
-streetLine1stringRequired 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
-streetLine2string(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
-citystringRequired 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
-stateOrProvincestringRequired 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).
-postalCodestringRequired 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.
-countrystringRequired for physical rewards, not applicable for digital rewards (2 characters).
emailSubjectstring(Optional) If not specified, a default email subject will be used for the specified reward.
messagestring(Optional) gift message.
The string may have up to 3000 characters.
sendEmailboolean(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.
campaignstring(Optional) Campaign may be used to administratively categorize a specific Order.
The string may have up to 100 characters.
ptidstring🚧 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.
purchaseOrderNumberstring(Optional) The Purchase Order Number associated with this order. The string may have up to 100 characters.
notesstring(Optional) Order notes.
The string may have up to 150 characters.
expirationDatedate-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
  • 503 Service Unavailable

Get details for a specific order

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

EndpointPurpose
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 parameterData typeDescription
referenceOrderIDstringReference 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.

EndpointPurpose
POST {URI}/orders/{referenceOrderID}/resendsResend a specific Order.

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

Path parameterData typeDescription
referenceOrderIDstring(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 parameterData typeDescription
newEmailstringA new email to resend this Order to. (body parameter)
newEtidstringA 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.

Updated 28 days ago

What’s Next

Rewards as a Service™ and the RaaS® API are provided by Tango Card, Inc. © 2024 Tango Card, Inc.