Get a gift card
Returns one gift card with its offers, in the item shape that search returns.
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.
PartnerApiKeyX-Partner-Key<token>Partner API Key (X-Partner-Key)
id*stringThe card's id (card_…) from search or the catalog.
currency?stringPrice currency, three letters in either case; the API key's currency when omitted. An unsupported code gives 400 / 10001 at currency, reason NOT_SUPPORTED.
OK
- 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*stringname*stringcountryCode?string|nullcategory*string"shopping""foodAndDining""entertainment""gaming""travel""paymentCards""softwareAndDigital""other"logoUrl?string|nulldescription?string|nulloffers*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.
curl -X GET 'https://api.sandbox.openroam.com/v1/giftcards/cards/card_tzkc6b2xcqznidhkouwh2rz7wi?currency=USD'{ "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.