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.
Idempotent external reference ID
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
externalRefIDis not provided, theX-REQUEST-IDincluded 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 External Reference ID 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
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.
| Reward type | Description | Credential type | Integration example |
|---|---|---|---|
| text | Plain Text | cardNumber, PIN, securityCode, claimCode, etc. | Wrap in a <span> tag |
| url | URL to a reward landing page | redemptionUrl, securityUrl | Wrap in an <a> tag |
| barcode | URL for a barcode image | barcode | Add an <img> tag |
| date | ISO datetime | expirationDate | Display in localized date format based on locale of reward according to RFC 3339, i.e. "2016-01-01T00:00:00Z". |
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}/credentialtypescall. - We have also updated
GET {URI}/catalogsto 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}/credentialtypescall 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 in this user guide.
Updated 10 days ago