Skip to Content
OpenRoam Docs
Gift cards

Gift card catalog

Returns every gift card with its offers, page by page, for partner inventory.

GET
/v1/giftcards/catalog

Returns every gift card with its offers, page by page, for partner inventory.

Returns { items, nextCursor }, ordered by card ID, with the search filters except q. Continue with nextCursor as cursor, the same filters and the same currency until it is null; a page can hold fewer cards than limit, even none, while nextCursor is not null. A cursor reused with other filters or another currency gives 400 / 10001. The walk is not a frozen snapshot: a card that appears or disappears during it may be missing. Quote confirms the final price and availability.

Authorization

PartnerApiKey
headerX-Partner-Key<token>

Partner API Key (X-Partner-Key)

Query Parameters

countryCode?string

Optional ISO 3166-1 alpha-2 issuing country, in either case; every country when omitted. A card without a country is not listed when it is set, and a blank value or GLOBAL is rejected.

category?string

Keep the cards of this category; categories lists the values.

Value in"shopping""foodAndDining""entertainment""gaming""travel""paymentCards""softwareAndDigital""other"
valueType?string

Keep only fixed or only range offers; a card left without an offer is dropped.

Value in"fixed""range"
isRedeemableGlobally?boolean

true keeps only cards that can be redeemed in any country.

currency?string

Price currency, three letters in either case; the API key's currency when omitted. An unsupported code gives 400 / 10001 at currency, reason NOT_SUPPORTED.

cursor?string

The nextCursor of the previous page; omit it for the first page. Reuse it only with the same filters and currency.

limit?integer

Page size, 1 to 100; default 100.

Formatint32

Response Body

OK

  1. response

A page of the partner catalog walk, ordered by card ID. Continue with nextCursor, the same filters and the same currency until it is null; a page may hold fewer items than the limit, even none.

items*array<>
nextCursor?string|null
Example Request
curl -X GET 'https://api.sandbox.openroam.com/v1/giftcards/catalog?countryCode=US&category=shopping&valueType=range&isRedeemableGlobally=false&currency=USD&limit=10'
Example Response
{  "items": [    {      "id": "string",      "name": "string",      "countryCode": "string",      "category": "shopping",      "logoUrl": "string",      "description": "string",      "offers": [        {          "publicId": "string",          "name": "string",          "description": "string",          "value": {            "amount": 0,            "currency": "string",            "type": "fixed"          },          "price": {            "amount": 0,            "currency": "string"          },          "requiredInputs": [            {              "name": "string",              "type": "text",              "required": true,              "description": "string",              "fields": [                {}              ]            }          ]        }      ],      "details": {        "isRedeemableGlobally": true,        "redemptionInstructions": "string"      }    }  ],  "nextCursor": "string"}