View catalog

A Catalog is a collection of rewards. Tango offers rewards in a variety of domestic and international popular gift cards such as those of physical stores and online retailers, prepaid cards, digital delivery of grocery and restaurant food, donations to charitable foundations, and our own Tango Choice Product. All rewards must be attached to a catalog to place an order and send to recipients.

Each Platform has its own catalog and is established when the platform is set up. The Catalog can be changed at any time by contacting Tango's Customer Success Manager (CSM) at [email protected]. For a complete list of Tango rewards catalog, see the full Tango catalog.

Each reward has a Unique Tango Identifier (UTID) that is used when placing an order. With Tango API, you can view items in the platform catalog, check their availability, and view the reward brand details and UTIDs before placing an order.

If you create your own in-app catalog, 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.

❗️

Warning!

We recommend to call GET {URI}/catalogs endpoint semi-daily (at most) to check the current list of content and their status. This catalog endpoint should not be used per individual order or with frequent polling system.

Get all items in the platform catalog

Use GET {URI}/catalogs endpoint to get all items in the platform's Catalog:

EndpointPurpose
GET {URI}/catalogsGet all items in the platform's catalog. It provides the credential types information for each item in the catalog.
See about Get credential types .

Catalog filters

Perform GET {URI}/catalogs to get details for specific items or groupings using the following endpoint filters:

Endpoint filterDescription
GET {URI}/catalogs?utid={{utid}}Return the details for a specific item (UTID).
GET {URI}/catalogs?brandKey={{brandKey}}Return all the items and details for a specific brand.
GET {URI}/catalogs?currencyCode=\*{{currencyCode}}Return items of a specific currency.
GET {URI}/catalogs?country=((2-digit country code))Return items from a specific country; the value can be found in the countries collection.

Here are the query parameters for this endpoint. For example, with "fulfillmentType": "PHYSICAL", you can see the list of your physical UTIDs to submit a recipient address:

Query ParameterData typeDescription
verboseboolean (false/true)When true, returns additional brand fields: status, disclaimer, description, shortDescription, terms, brandRequirements collection, and imageUrls collection.
brandKeystringReturns the brand and item details for a specific brand ID.
brandNamestringReturns the brand and item details for a specific brand name.
utidstringReturns the brand and item details for a specific UTID. The UTID is the unique identifier for a specific reward.
rewardNamestringReturns the brand and item details of the specified reward name.
statusstringReturns all brands and item details with the specified status. Possible statuses are: “test", “active", “inactive", "deleted".
currencyCodestringReturn all brands and item details associated with a specific currency.
countrystringReturns all brands and item details from a specific country. Country codes are two-digits.
fulfillmentType
-DIGITAL
-PHYSICAL
array of stringsReturns all brands and item details for a specific fulfillment type.
categoryIdsarray of stringsReturns all brands and item details for specific brand categories.

The response code for this endpoint is:

  • 200 OK
  • 400 Bad Request
  • 401 Unauthorized
  • 403 Forbidden

Retrieve catalog items when verbose is true

Use the GET {URI}/catalogs endpoint to view the items in your platform’s catalog and see what you can order. When the verbose is true, it returns the additional brand fields, such as status, disclaimer, description, shortDescription, terms, brandRequirements collection, and imageUrls collection.

The following payload is with verbose=true:

{
  "catalogName": "string",
  "brands": [
    {
      "brandKey": "string",
      "brandName": "string",
      "disclaimer": "string",
      "description": "string",
      "shortDescription": "string",
      "terms": "string",
      "createdDate": "2023-10-12T21:23:43.900Z",
      "lastUpdateDate": "2023-10-12T21:23:43.900Z",
      "brandRequirements": {
        "displayInstructions": "string",
        "termsAndConditionsInstructions": "string",
        "disclaimerInstructions": "string",
        "alwaysShowDisclaimer": true
      },
      "imageUrls": {
        "additionalProp": "string"
      },
      "status": "string",
      "items": [
        {
          "utid": "string",
          "rewardName": "string",
          "currencyCode": "string",
          "status": "string",
          "valueType": "string",
          "rewardType": "string",
          "isWholeAmountValueRequired": true,
          "exchangeRateRule": "string",
          "minValue": 0,
          "maxValue": 0,
          "faceValue": 0,
          "fee": {
            "type": "string",
            "value": 0
          },
          "createdDate": "2023-10-12T21:23:43.900Z",
          "lastUpdateDate": "2023-10-12T21:23:43.900Z",
          "countries": [
            "string"
          ],
          "credentialTypes": [
            "string"
          ],
          "redemptionInstructions": "string",
          "itemAvailability": {
            "itemAvailabilityStatus": "OPERATIONAL",
            "note": "string",
            "resolutionDate": "2023-10-12T21:23:43.900Z",
            "statusPageUrl": "string",
            "lastModifiedDate": "2023-10-12T21:23:43.900Z"
          },
          "fulfillmentType": "DIGITAL"
        }
      ],
      "categories": [
        {
          "identifier": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "description": "string"
        }
      ]
    }
  ]
}

Retrieve catalog items when verbose is false

Use GET {URI}/catalogs to retrieve catalog items.

The following payload is with verbose=false:

{
  "catalogName": "string",
  "brands": [
    {
      "brandKey": "string",
      "brandName": "string",
      "disclaimer": "string",
      "description": "string",
      "shortDescription": "string",
      "terms": "string",
      "createdDate": "2023-10-12T21:23:43.900Z",
      "lastUpdateDate": "2023-10-12T21:23:43.900Z",
      "brandRequirements": {
        "displayInstructions": "string",
        "termsAndConditionsInstructions": "string",
        "disclaimerInstructions": "string",
        "alwaysShowDisclaimer": true
      },
      "imageUrls": {
        "additionalProp": "string"
      },
      "status": "string",
      "items": [
        {
          "utid": "string",
          "rewardName": "string",
          "currencyCode": "string",
          "status": "string",
          "valueType": "string",
          "rewardType": "string",
          "isWholeAmountValueRequired": true,
          "exchangeRateRule": "string",
          "minValue": 0,
          "maxValue": 0,
          "faceValue": 0,
          "fee": {
            "type": "string",
            "value": 0
          },
          "createdDate": "2023-10-12T21:23:43.900Z",
          "lastUpdateDate": "2023-10-12T21:23:43.900Z",
          "countries": [
            "string"
          ],
          "credentialTypes": [
            "string"
          ],
          "redemptionInstructions": "string",
          "itemAvailability": {
            "itemAvailabilityStatus": "OPERATIONAL",
            "note": "string",
            "resolutionDate": "2023-10-12T21:23:43.900Z",
            "statusPageUrl": "string",
            "lastModifiedDate": "2023-10-12T21:23:43.900Z"
          },
          "fulfillmentType": "DIGITAL"
        }
      ],
      "categories": [
        {
          "identifier": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "description": "string"
        }
      ]
    }
  ]
}

Check item availability

📘

Note:

  • Item availability is on limited release. Contact your Tango representative or email Technical Support specialists at [email protected] for more questions.
  • 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.

When placing an order, an item may or may not be available. The ItemAvailability will provide details such as when we are experiencing an issue or when the item is no longer available.

📘

Note:

To avoid performance issues, only use ItemAvailability with a utid filter for a specific gift card, and verbose = true. Do not check the ItemAvailability for the entire catalog when utid= blank/null.

The following response shows ItemAvailability payload retrieved using GET {URI}/catalogs when verbose=true:

"itemAvailability": {
            "itemAvailabilityStatus": "Availability Status",
            "note": "string",
            "resolutionDate": "2022-12-22T00:06:30.401Z",
            "statusPageUrl": "string",
            "lastModifiedDate": "2022-12-22T00:06:30.401Z"
          }

📘

Note:

When the ItemAvailability is AVAILABLE, the note, resolutionDate, statusPageUrl, and lastModifiedDate is not returned in the payload (null).

Here are the statuses for an UTID (item) returned by ItemAvailabilityStatus:

Availability statusDescription
AVAILABLEThis item is available for ordering.
DEGRADEDThis item is currently experiencing higher than usual errors. We are working to restore this item for you. We will have an update for you shortly.
UNAVAILABLEThis item is currently unavailable. We are working to restore this item for you. We will have an update for you shortly.
DEPRECATEDThis item is permanently unavailable.

See the following response:

"itemAvailability": {
     "itemAvailabilityStatus": "AVAILABLE",
     "note": "resolution date added",
     "resolutionDate": "2021-07-22T07:00:00Z",
     "statusPageUrl": "https://www.tangocard.com",
     "lastModifiedDate": "2021-07-06T20:51:14.943Z"
}

Other response parameters may include:

Response parameterDescription
notesAny relevant notes regarding availability. The notes are entered manually by the user.
resolutionDateIf known, the anticipated date to return to the Available status. The resolutionDate is manually entered by the user.
statusPageUrlIf applicable, contains a link to the StatusPage posting, subscribe to updates available. statusPageUrl is a manual field that contains a link to a manually-created StatusPage entry.
lastModifiedDateShows the most recent update and is an automated timestamp.

🚧

Coming soon:

The global attribute of lang helps define the language of your catalog. For example, <span lang=“US-EN”>This is the English Text</span> shows the US English language and <span lang=“CA-FR”>This is the French Canadian text</span> shows the Canadian French.

GET {URI}/catalogs provides the credential types information for each item in the catalog. See our topic on how to Get Credential Types.