Skip to Content
OpenRoam Docs

Gift cards

Search the gift card catalog, quote a card at a fixed or custom value, order it, and read the issued codes.

What you can sell

Gift cards are digital cards from retail, gaming, travel, entertainment and other brands. A card is one brand in one issuing country, and it lists one or more offers:

  • A fixed offer sells one face value, for example 50 USD.
  • A range offer sells any value between a minimum and a maximum, on a step, for example 1 to 500 USD. You choose the value when you quote and order.

An order delivers the card number and PIN (or whichever parts the card has) in the order item. You can also ask OpenRoam to email the card to a recipient as a gift.

This page covers what is specific to gift cards. Authentication, environments, idempotency, errors, webhooks and the order envelope are shared by every product: Quickstart, Authentication, Environments, Idempotency, Errors, Webhooks and Orders.

The flow

Browse the catalog

RouteUse it to
GET /v1/giftcards/searchList cards with their offers, one page at a time.
GET /v1/giftcards/cards/{id}Read one card by its card_... id. It returns the same item that search returns.
GET /v1/giftcards/catalogWalk every card in id order with a cursor, for example to build your own copy of the catalog.
GET /v1/giftcards/categoriesRead the category list (shopping, foodAndDining, entertainment, gaming, travel, paymentCards, softwareAndDigital, other) with display names.

Quote

POST /v1/giftcards/quote prices the items of an order body. It has no side effects: nothing is reserved and nothing expires.

Order

POST /v1/giftcards/order takes the same body as the quote. It needs an Idempotency-Key header and an API key with the manage permission. It returns the shared order envelope.

Read the result

Follow the order with GET /v1/orders/{id} or the order.fulfillment.updated webhook.

An id from the catalog names a card. You never order a card id: you quote and order one of its offers by publicId.

Search and read cards

curl "https://api.sandbox.openroam.com/v1/giftcards/search?countryCode=US&limit=10" \
  -H "X-Partner-Key: $OPENROAM_API_KEY"
{
  "items": [
    {
      "id": "card_example1234567890abcdefghij",
      "name": "Example Store",
      "countryCode": "US",
      "category": "shopping",
      "logoUrl": "https://cdn.example.com/logo.png",
      "description": "Redeem at example.com",
      "offers": [
        {
          "publicId": "giftcard_example1fixed00000000000",
          "name": "Example Store 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_example1range0000000000",
          "name": "Example Store 1–500 USD",
          "description": null,
          "value": { "type": "range", "min": 1, "max": 500, "step": 0.01, "currency": "USD" },
          "price": { "min": 2.01, "max": 506.00, "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 example.com/redeem and enter the code." }
    }
  ],
  "pagination": { "currentCount": 1, "totalCount": 1, "skip": 0, "limit": 10, "hasMore": false, "page": 1, "totalPages": 1 }
}

What to know about the catalog:

  • countryCode is the issuing country, or null for a card without one (a global card). A countryCode filter does not list a card without one.
  • details.isRedeemableGlobally says whether the card can be redeemed outside its issuing country. The isRedeemableGlobally=true filter keeps only such cards.
  • A card with the same brand and country but another face currency is a separate card with its own id.
  • Offers list fixed values from low to high, then at most one range offer. A range always has a max, and its step is the smallest allowed increment.
  • price is indicative and in the requested currency (currency, or your API key's currency). For a range it is the price of the min value and of the max value. The quote is authoritative.
  • A fixed offer whose value the range also sells is hidden when the range sells that value for the same price or less. In that case you buy that value through the range.

Filters for search and catalog:

ParameterSearchCatalogMeaning
countryCodeyesyesISO 3166-1 alpha-2. Omit it for every country.
categoryyesyesOne of the category values above.
qyesnoBrand name or card id, case-insensitive, at most 100 characters.
isRedeemableGloballyyesyestrue keeps only cards that can be redeemed in any country.
valueTypeyesyesfixed or range. Keeps those offers within each card.
currencyyesyesPrice currency, three letters. Defaults to your API key's currency.
page, limityeslimit onlySearch: page defaults to 1, limit to 10 (at most 100). Catalog: limit 1 to 100, default 100.
cursornoyesThe nextCursor of the previous catalog page.

Search can return fewer cards than limit on a page. Catalog pages can even be empty while nextCursor is not null: keep following nextCursor, with the same filters and currency, until it is null. A cursor reused with other filters or another currency returns 400 / 10001.

Quote and order

Quote and order take the same body.

{
  "currency": "USD",
  "referenceId": "partner-order-42",
  "items": [
    {
      "publicId": "giftcard_example1fixed00000000000",
      "quantity": 1,
      "inputs": { "maxPrice": { "amount": 50, "currency": "USD" } }
    },
    {
      "publicId": "giftcard_example1range0000000000",
      "quantity": 1,
      "inputs": {
        "recipientEmail": "friend@example.com",
        "giftMessage": "Happy birthday!",
        "value": { "amount": 25, "currency": "USD" },
        "maxPrice": { "amount": 30, "currency": "USD" }
      }
    }
  ]
}
  • items holds 1 to 5 items, and at most 5 cards in total. quantity can be above 1; each card becomes its own order item.
  • currency is the order currency. It defaults to your API key's currency.
  • referenceId is your own order reference, unique per partner, at most 128 characters. A quote validates it and ignores it.
  • The card value and the price limit are members of inputs. A value or maxPrice beside inputs is rejected as an unknown member.

Product inputs

inputs memberWhenMeaning
valueRequired for a range offer; optional for a fixed offer{ amount, currency } in the card's face currency. For a range it must be within min and max and on the step. For a fixed offer it must equal the offer's amount.
maxPriceOptionalThe highest unit price you accept, { amount, currency } in the order currency.
recipientIdentifierOnly when the offer lists it in requiredInputsThe recipient's government or tax identifier, up to 64 characters.
recipientEmailOptional, on every offerSends the card to this address as a gift email, up to 254 characters.
giftMessageOptional, only with recipientEmailMessage in the gift email, up to 500 characters.

inputs can be left out for a fixed offer that does not list recipientIdentifier. A range offer needs at least inputs.value.

The quote response

{
  "currency": "USD",
  "items": [
    {
      "publicId": "giftcard_example1fixed00000000000",
      "quantity": 1,
      "name": "Example Store 50 USD",
      "value": { "amount": 50, "currency": "USD" },
      "price": { "amount": 48.98, "currency": "USD" }
    },
    {
      "publicId": "giftcard_example1range0000000000",
      "quantity": 1,
      "name": "Example Store 25 USD",
      "value": { "amount": 25, "currency": "USD" },
      "price": { "amount": 26.25, "currency": "USD" }
    }
  ],
  "total": { "amount": 75.23, "currency": "USD" }
}

For a range item, the quote prices the cheapest offer of the same card that sells exactly that value: the range you sent, another range of the card, or a fixed offer of exactly that value. The quote item returns the publicId of the winning offer, which can differ from the one you sent. Order with the id the quote returned.

Place the order

curl -X POST https://api.sandbox.openroam.com/v1/giftcards/order \
  -H "X-Partner-Key: $OPENROAM_API_KEY" \
  -H "Idempotency-Key: 5a1f0c3e-8d1a-4c1e-9a55-0f6b7a2d9e10" \
  -H "Content-Type: application/json" \
  -d @order.json

Price limit at order time

The order recalculates every price. A lower price is charged as calculated. A higher price is accepted only up to the item's inputs.maxPrice. Above it, the order fails with 409 / 11002 at items[i].inputs.maxPrice and nothing is charged. The card value is never reduced to fit maxPrice.

{
  "code": 11002,
  "name": "OFFER_PRICE_CHANGED",
  "message": "The price changed.",
  "requestId": "0123456789abcdef0123456789abcdef",
  "details": [ { "path": "items[0].inputs.maxPrice", "reason": "PRICE_CHANGED" } ]
}

Quote and order check the body in the same way. Structural problems (an unknown member, a missing publicId, a quantity below 1, more than 5 items) give 400 / 10001 before any item is priced. After that, items are checked one at a time in request order, and the first failing item ends the request. Its index is in the error path.

What the order item contains

Read an item with GET /v1/order-items/{id}, or as one entry of items in GET /v1/orders/{id}.

{
  "id": "01a1413c-265f-77b1-9041-25aee298d4d0",
  "orderId": "01a1413c-2642-7348-bf49-0f93879eacf1",
  "productType": "giftCard",
  "price": { "amount": 26.25, "currency": "USD" },
  "purchasedProduct": {
    "name": "Example Store 25 USD",
    "countryCode": "US",
    "logoUrl": "https://cdn.example.com/logo.png",
    "value": { "amount": 25, "currency": "USD" },
    "inputs": { "recipientIdentifier": null, "recipientEmail": "f***@example.com", "giftMessage": "Happy birthday!" },
    "details": {
      "brandName": "Example Store",
      "isRedeemableGlobally": false,
      "redemptionInstructions": "Go to example.com/redeem and enter the code."
    }
  },
  "fulfillment": {
    "status": "fulfilled",
    "result": {
      "deliveredValue": { "amount": 25, "currency": "USD" },
      "details": {
        "codes": [ { "cardNumber": "CARD-0001", "pinCode": "PIN-0001", "instructions": null } ],
        "delivery": { "status": "pending" }
      }
    },
    "failure": null
  },
  "actions": {
    "amendment": { "availability": "notAvailable", "reason": null },
    "cancellation": { "availability": "notAvailable", "reason": null },
    "update": { "availability": "available", "reason": null }
  },
  "createdAt": "2026-10-15T20:23:43.489051Z",
  "effectivePaidAmount": { "amount": 26.25, "currency": "USD" }
}

purchasedProduct is what was bought:

  • name is the card at its value. value is the face value, and countryCode the issuing country.
  • inputs echoes recipientIdentifier, recipientEmail and giftMessage. The identifier is masked as *** plus its last four characters, and the email as f***@example.com. giftMessage is returned as sent. The card value is in value, and maxPrice is never echoed.
  • details has brandName, isRedeemableGlobally and redemptionInstructions.

fulfillment.result is what was delivered:

  • deliveredValue is the face value of the issued card. It is null until a card is issued.
  • details.codes lists the issued codes as cardNumber, pinCode and instructions. Any of the three can be null, because cards differ. The list is empty when the item does not release its codes, for example after a refund.
  • details.delivery is null for a card that is not a gift. For a gift it is { status }, where status is pending, processing, retry, sent or failed. The gift email is sent after fulfillment, so an item can be fulfilled while its delivery is still pending.

fulfillment.status stays pending until a code has been retrieved, so a purchase that reports success without a code has not delivered anything. If the item stays pending longer than usual, fulfillment.progress carries the code CONFIRMING_OUTCOME.

After purchase

Gift cards use the shared order-item routes, described in Orders.

  • Change the gift recipient. POST /v1/order-items/{id}/update changes who a delivered gift card is sent to. It takes { "inputs": { "recipientEmail": "...", "giftMessage": "..." } }, needs the manage permission and an Idempotency-Key, and never charges or refunds anything. A member you leave out keeps its current value, and a card bought without a recipient needs recipientEmail. A successful update sends the gift email again and starts delivery.status at pending again. actions.update is available only for a delivered, unrefunded card whose codes can be shown and while no gift email is being sent. Otherwise the update returns 409 / 18005 with the reason IN_PROGRESS or NOT_AVAILABLE.
  • Cancel and amend. An issued card cannot be taken back or changed. Cancel and its preview answer 422 / 18000 (CANCELLATION_NOT_SUPPORTED), and amending answers 422 / 18002 (AMENDMENT_NOT_SUPPORTED). While the card is still pending, cancel answers 409 / 18001.
  • Rejected cards are refunded. If fulfillment is rejected, the item is refunded in full automatically and the order-item.refunded webhook reports it. Cancelling with the reason fulfillmentFailed returns that refund.

Testing in Sandbox

Sandbox supports gift cards. It uses the same routes and rules as production with a test catalog and test wallet funds; see Environments. Gift cards in Sandbox never produce redeemable codes, and no real gift email is sent.

On POST /v1/giftcards/order, set the OpenRoam-Sandbox-Scenario header to choose the fulfillment outcome:

Header valueResult
success (or no header)The order is fulfilled and each item gets a clearly synthetic code and PIN.
fulfillment.rejectedFulfillment is rejected after payment. There are no codes, and the item is refunded automatically.
fulfillment.pendingReturns pending at once. The item becomes eligible for success after 15 minutes.
fulfillment.late_successReturns pending at once and becomes eligible for success after 2 minutes.
fulfillment.late_rejectedReturns pending at once and confirms the rejection after 2 minutes.
  • The scenario applies to every item of the order and is part of idempotency. The same key, body and scenario replay the same order, and changing the scenario with the same key returns 409.
  • The header is accepted only on order creation in Sandbox. Anywhere else, including search and quote, it returns 400 / 10001 with the reason NOT_ALLOWED. An unknown or repeated value returns 400 / 10001 with INVALID_VALUE.
  • Pending results contain no codes. Read the order again or wait for the webhook: the outcome appears on the next reconciliation pass, so the durations are not a guaranteed delay.
  • Even with success, fulfillment takes a few seconds, so read the order again if the first read shows pending.

Sandbox codes look like SANDBOX-NOT-REDEEMABLE-..., with a PIN starting TEST-ONLY-. They are the same on replay, and separate order items get distinct codes. Gift email delivery starts pending and then reads sent, which here means a local test delivery.

Fixtures to try. Card ids are generated per environment, so find each card with search (countryCode and q) and use the publicId of its offers.

CardOfferInputs to send
Apple, USFixed 10 USDNone
Amazon, USRange 5 to 100 USD, step 5inputs.value, for example 25 USD
Xbox, USFixed 25 USDinputs.recipientIdentifier, for example TEST-RECIPIENT-1234
Steam, AZFixed 20 USDNone
Caspian Market, AZFixed 10, 25 and 50 AZNNone (try currency USD to see a face value in AZN)
Baku Digital, AZRange 5 to 50 USD, step 5inputs.value and inputs.recipientIdentifier
PlayStation, GBFixed 10 GBPNone

The face value keeps its own currency through quote, order and fulfillment: 25 AZN stays 25 AZN while the checkout price is in USD. Send an inputs.maxPrice below a quoted price to trigger 409 / 11002.

Errors to handle

Shared error handling is in Errors. Gift card specific cases:

Status / codeReasonPathWhen
400 / 10001REQUIREDitems[i].inputs.valueA range offer without a value.
400 / 10001INVALID_VALUEitems[i].inputs.value.amountA value outside the range, off its step, or different from a fixed offer's amount.
400 / 10001CURRENCY_MISMATCHitems[i].inputs.value.currencyThe value is not in the card's face currency.
400 / 10001CURRENCY_MISMATCHitems[i].inputs.maxPrice.currencymaxPrice is not in the order currency.
400 / 10001REQUIRED or INVALID_VALUEitems[i].inputs.recipientIdentifierThe offer needs a recipient identifier and it is missing, too long or has control characters.
400 / 10001NOT_ALLOWEDitems[i].inputs.giftMessageA gift message without recipientEmail.
400 / 10001INVALID_VALUEitems[i].inputs.<member>An inputs member the offer does not define.
400 / 11004EXPIRED_OR_INVALIDitems[i]An unknown, malformed or foreign publicId, including a card id or another product's offer.
409 / 11003UNAVAILABLEitems[i]The offer cannot be sold now.
409 / 11002PRICE_CHANGEDitems[i].inputs.maxPriceThe current unit price is above maxPrice. Nothing is charged.
404 / 10004nonenoneGET /v1/giftcards/cards/{id} with an unknown id, or a card with no orderable offer.
403 / 10003SERVICE_NOT_ENABLEDserviceGift cards are not enabled for your account.
422 / 18000nonenoneCancelling an issued card.
409 / 18005IN_PROGRESS or NOT_AVAILABLEidA recipient update while the gift email is being sent, or on a card that cannot be updated.

Browse routes reject any unknown query parameter with 400 / 10001 and the reason UNSUPPORTED_FIELD. A failing quote or order creates and charges nothing.

On this page