Skip to Content
OpenRoam Docs
Gift cards

Get a gift card

Returns one gift card with its offers, in the item shape that search returns.

GET
/v1/giftcards/cards/{id}

Returns one gift card with its offers, in the item shape that search returns.

An unknown or unparseable ID, or a card without an orderable offer, gives 404 / 10004.

Authorization

PartnerApiKey
headerX-Partner-Key<token>

Partner API Key (X-Partner-Key)

Path Parameters

id*string

The card's id (card_…) from search or the catalog.

Query Parameters

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.

Response Body

OK

  1. response

One card (brand and issuing country, plus the face currency when a brand sells several) as search, the one-card route and the catalog return it. id is the card ID card_…, an opaque ID that is never orderable; an order names one of its offers by public ID. countryCode is the issuing country's ISO 3166-1 alpha-2 code, or null for a card without a country, such as a global card. Prices are indicative; quote recalculates them.

id*string
name*string
countryCode?string|null
category*string
Value in"shopping""foodAndDining""entertainment""gaming""travel""paymentCards""softwareAndDigital""other"
logoUrl?string|null
description?string|null
offers*array<>
details*

Gift card facts outside the item keys every partner service shares. isRedeemableGlobally is true when the card can be redeemed outside its issuing country; redemptionInstructions is the detailed redemption text, or null.

Example Request
curl -X GET 'https://api.sandbox.openroam.com/v1/giftcards/cards/card_tzkc6b2xcqznidhkouwh2rz7wi?currency=USD'
Example Response
{  "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"  }}

Order gift cards POST

Places a gift card order and returns the accepted order. Takes the same body as quote and needs the `manage` order permission (403 / 10003 without it). An `Idempotency-Key` header with a new UUID is required for every purchase: a retry with the same key and body returns the order already accepted, 409 / 12002 with `Retry-After` while it is still being accepted, and a changed body gives 409 / 12001. Order with the `publicId` a quote returned. Every price is recalculated: a current price above `inputs.maxPrice` gives 409 / 11002 at `items[i].inputs.maxPrice` before anything is charged. Each card of an item's `quantity` becomes its own order item; read the codes from the order routes or the `order.fulfillment.updated` webhook. A wallet charge that fails creates no order and gives 402 / 16000, with `details[0]` naming `wallet` and `INSUFFICIENT_BALANCE` or `WALLET_BLOCKED`; send the same request with the same key after a top-up.

Gift card catalog GET

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.