Best practices

Rate limit calls to the endpoints

To ensure a successful experience for all of our customers, we enforce a 1 TPS rate limit on our endpoints. We recommend building a process within your code to handle the rate limit. A failure to do so may cause your implementation to fail unexpectedly. When placing orders, if you receive an error, wait 1 second and retry the order with the idempotent externalRefID.

external reference ID Idempotent

External Ref ID or externalRefID is an optional idempotent field. We allow one unique order per External Reference ID. Subsequent requests using the same External Reference ID do not create a new order but return the original Order information even if the original order is for a different item.

See the notes below:

• IDs have a maximum of 100 alphanumeric characters.
• If an externalRefID is not provided, the X-REQUEST-ID included in the response header for the transaction is used as a reference when you contact Tango support on the status of an order.
• Idempotency is enforced at the account level. We do not check for ID uniqueness in other accounts even if they are under the same platform or customer.
• If you wish to use a non-idempotent field for notes, we recommend you use the optional Notes field.
• Order requests receiving a 5XX error may occasionally be processed after a network connection is lost. We strongly recommend you use the externalRefID idempotent parameter to ensure duplicate orders are not created when you retry a failed order.
• A successful new order will return a 201 code.
• If an order already existed with the submitted External Reference ID, the system will return a 200.
• If you're handling reward delivery by using sendEmail=false, we highly recommend including the refOrderID from the POST order response body to your recipients. The refOrderID is the unique identifier for all items ordered via Tango. Without the refOrderID, we cannot tie a specific reward to a recipient.

Handle reward types

Tango returns the following types of reward credentials. If your integration requires displaying reward data in app or creating custom reward emails, you may need to add logic to parse the returned reward data correctly.

Use credential type

Use credentialType key in credentialList in the order response for better parsing and display of reward data.

• A list of available credential types can be found with a GET {URI}/credentialtypes call.
• We have also updated GET {URI}/catalogs to provide the credential types information for each item in the catalog.

📘

Note:

We are continuously expanding our catalog and it is likely that new reward types will arise over time. For this reason we recommend a fallback/default to handle unspecified types as text.

The categorization of credentialType(s) is based on internal factors of the Tango system. Many of the definitions found in the GET {URI}/credentialtypes call have similar or identical definitions.

Avoid browser-based API calls

We do not allow browsers to POST calls. Attempts to do so, will result in an authorization error (403.001).
For best practices, we recommend you to use non-browser tools for all API calls.

Design for change in your catalog

API users that create their own in-app Catalog should keep in mind that reward parameters may change from time to time. Brands often update their images, description, terms, redemption instructions, and sometimes even their names and available denominations. Use the UTID and Brand Key as your primary identifier for programmatic decisions.

Avoid HTML input in POST operations

Tango provides HTML-formatted brand and reward information in our method responses with the aim of minimizing integration design time. For security concerns, we escape any HTML input in POST operations.

About responses

See our content about Tango Response classes and error messages in this user guide.