Best practices

Suggest Edits

Idempotent External Reference ID

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

  • 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 process after a network connection is lost. We strongly recommend you make use of the External Reference ID idempotent parameter to ensures duplicate orders are not created when you retry a failed order.

📘

Note:

Tango does not support idempotency after 90 days from the original order.

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 TypeDescriptionCredential TypeIntegration example
textPlain TextcardNumber, PIN, securityCode, claimCode, etc.Wrap in a <span> tag
urlURL to a reward landing pageredemptionUrl, securityUrlWrap in an <a> tag
barcodeURL for a barcode imagebarcodeAdd an <img> tag
dateISO datetimeexpirationDateDisplay 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}/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

  • JSON is currently the only supported content type for inputs or outputs. It is not required that the requests contain an Accept header, but if they do, it must contain application/json or /.
  • All dates must be represented in a format that is compatible with ISO 8601, for example: 2013-02-21T20:37:07-07:00.
  • You can add fields in the Tango API response objects at any time. What you use to unmarshal the JSON responses into native data types must handle unknown fields without failing.

Updated 21 days ago