Skip to Content
OpenRoam Docs
Gift cards

Search gift cards

Searches gift cards and returns them with their offers, one page at a time.

GET
/v1/giftcards/search

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.

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"
q?string

Brand name or card ID, case-insensitive; at most 100 characters, without control characters.

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.

page?integer

Page number, from 1; default 1.

Formatint32
limit?integer

Page size, 1 to 100; default 10.

Formatint32

Response Body

OK

  1. response

A page of cards; pagination.totalCount counts cards that still have an offer after filtering.

items*array<>
pagination*

Paging of a list response.

Example Request
curl -X GET 'https://api.sandbox.openroam.com/v1/giftcards/search?countryCode=US&category=shopping&valueType=range&isRedeemableGlobally=false&currency=USD&page=1&limit=10'
Example Response
{  "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.