Search gift cards
Searches gift cards and returns them with their offers, one page at a time.
Searches gift cards and returns them with their offers, one page at a time.
Returns { items, pagination }. countryCode, category, q and
isRedeemableGlobally select cards; valueType selects offers within them, and a card left without
an offer is dropped. Pages count cards. Prices are indicative, in currency; a fixed offer is listed only
when it is cheaper than the card's range at the same value. An invalid or unknown parameter gives 400 / 10001;
an unsupported currency gives 400 / 10001 at currency.
PartnerApiKeyX-Partner-Key<token>Partner API Key (X-Partner-Key)
countryCode?stringOptional 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?stringKeep the cards of this category; categories lists the values.
"shopping""foodAndDining""entertainment""gaming""travel""paymentCards""softwareAndDigital""other"valueType?stringKeep only fixed or only range offers; a card left without an offer is dropped.
"fixed""range"q?stringBrand name or card ID, case-insensitive; at most 100 characters, without control characters.
isRedeemableGlobally?booleantrue keeps only cards that can be redeemed in any country.
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.
page?integerPage number, from 1; default 1.
int32limit?integerPage size, 1 to 100; default 10.
int32OK
- response
A page of cards; pagination.totalCount counts cards that still have an offer after filtering.
items*array<>pagination*Paging of a list response.
curl -X GET 'https://api.sandbox.openroam.com/v1/giftcards/search?countryCode=US&category=shopping&valueType=range&isRedeemableGlobally=false¤cy=USD&page=1&limit=10'{ "items": [ { "id": "card_tzkc6b2xcqznidhkouwh2rz7wi", "name": "Amazon", "countryCode": "US", "category": "shopping", "logoUrl": "https://cdn.openroam.test/amazon.png", "description": "Redeem at amazon.com", "offers": [ { "publicId": "giftcard_p5udmgvqke2bcrwlk35drsqfqm", "name": "Amazon 50 USD", "description": null, "value": { "type": "fixed", "amount": 50, "currency": "USD" }, "price": { "amount": 48.98, "currency": "USD" }, "requiredInputs": [ { "name": "recipientEmail", "type": "email", "required": false, "description": "Sends the card to this email address as a gift." }, { "name": "giftMessage", "type": "text", "required": false, "description": "Message included in the gift email." } ] }, { "publicId": "giftcard_tm4m2tnb4u3dlthj3pvo6zqkha", "name": "Amazon 1–500 USD", "description": null, "value": { "type": "range", "min": 1, "max": 500, "step": 0.01, "currency": "USD" }, "price": { "min": 2.01, "max": 506, "currency": "USD" }, "requiredInputs": [ { "name": "recipientEmail", "type": "email", "required": false, "description": "Sends the card to this email address as a gift." }, { "name": "giftMessage", "type": "text", "required": false, "description": "Message included in the gift email." } ] } ], "details": { "isRedeemableGlobally": false, "redemptionInstructions": "Go to amazon.com/redeem and enter the code." } } ], "pagination": { "currentCount": 1, "totalCount": 1, "skip": 0, "limit": 10, "hasMore": false, "page": 1, "totalPages": 1 }}Quote gift cards POST
Prices the order body with current prices, without placing an order. Takes the same body as order and checks it the same way: each item completely (its inputs, then its `publicId`, then its price) before the next, in request order. The first failure aborts the quote and is named at `items[i]`, as the order names it, for example 409 / 11002 at `items[i].inputs.maxPrice` when the current price is above it. A range offer may be quoted on an equivalent offer of the same card that sells the same value for less: the item then returns that offer's `publicId`, which the order should use.
Book hotels POST
Places and pays for hotel bookings of up to 5 searched or quoted rates. Requires an `Idempotency-Key` header (a new UUID per purchase) and an API key with order-manage permission. Repeating the same request with the same key returns the original order; while the first request is still running the response is 409 / 12002 with `Retry-After`, after which you send the same request again. The order is paid from your wallet balance and each booking completes asynchronously: track it with `GET /orders/{id}` or the `order.fulfillment.updated` webhook. The body is `{ currency, referenceId, items }` with 1 to 5 items, each `{ publicId, quantity, inputs }`. `publicId` is an offer's `publicId` from search, or the newer one from quote, and `quantity` must be 1. `inputs` holds the holder and one `roomGuests` entry per searched room (`roomIndex` 1 to N), whose guests must match the searched occupancy and child ages, the optional `specialRequests`, and the optional price guard `maxPrice` in the order currency. Unknown fields are rejected with 400. The whole body is validated first: a body error gives 400 / 10001, also when it is in a later item. Once the body is valid, each item is checked completely before the next, and an error names its item in `details[].path`. Before any money moves each rate is priced again in the order currency and capped: at `inputs.maxPrice` when sent, else at the price shown with the `publicId`. Above the cap the order returns 409 / 11002 at `items[i].inputs.maxPrice` or `items[i]` (quote again); at or below it the rate is charged as priced, so a `maxPrice` above the shown price accepts a rise up to it. A rate that cannot be booked now returns 409 / 11003, an offer priced in another currency than the order 400 / 11005, and an unknown, expired or another partner's `publicId` 400 / 11004, each at `items[i]`. Offer and hotel-system failures return their hotel codes (21003, 21007–21010) without a path. A wallet charge that fails 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. Nothing is created or charged when the order is refused.