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
| Route | Use it to |
|---|---|
GET /v1/giftcards/search | List 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/catalog | Walk every card in id order with a cursor, for example to build your own copy of the catalog. |
GET /v1/giftcards/categories | Read 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:
countryCodeis the issuing country, or null for a card without one (a global card). AcountryCodefilter does not list a card without one.details.isRedeemableGloballysays whether the card can be redeemed outside its issuing country. TheisRedeemableGlobally=truefilter 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 itsstepis the smallest allowed increment. priceis indicative and in the requested currency (currency, or your API key's currency). For a range it is the price of theminvalue and of themaxvalue. 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:
| Parameter | Search | Catalog | Meaning |
|---|---|---|---|
countryCode | yes | yes | ISO 3166-1 alpha-2. Omit it for every country. |
category | yes | yes | One of the category values above. |
q | yes | no | Brand name or card id, case-insensitive, at most 100 characters. |
isRedeemableGlobally | yes | yes | true keeps only cards that can be redeemed in any country. |
valueType | yes | yes | fixed or range. Keeps those offers within each card. |
currency | yes | yes | Price currency, three letters. Defaults to your API key's currency. |
page, limit | yes | limit only | Search: page defaults to 1, limit to 10 (at most 100). Catalog: limit 1 to 100, default 100. |
cursor | no | yes | The 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" }
}
}
]
}itemsholds 1 to 5 items, and at most 5 cards in total.quantitycan be above 1; each card becomes its own order item.currencyis the order currency. It defaults to your API key's currency.referenceIdis 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. AvalueormaxPricebesideinputsis rejected as an unknown member.
Product inputs
inputs member | When | Meaning |
|---|---|---|
value | Required 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. |
maxPrice | Optional | The highest unit price you accept, { amount, currency } in the order currency. |
recipientIdentifier | Only when the offer lists it in requiredInputs | The recipient's government or tax identifier, up to 64 characters. |
recipientEmail | Optional, on every offer | Sends the card to this address as a gift email, up to 254 characters. |
giftMessage | Optional, only with recipientEmail | Message 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.jsonPrice 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:
nameis the card at its value.valueis the face value, andcountryCodethe issuing country.inputsechoesrecipientIdentifier,recipientEmailandgiftMessage. The identifier is masked as***plus its last four characters, and the email asf***@example.com.giftMessageis returned as sent. The card value is invalue, andmaxPriceis never echoed.detailshasbrandName,isRedeemableGloballyandredemptionInstructions.
fulfillment.result is what was delivered:
deliveredValueis the face value of the issued card. It is null until a card is issued.details.codeslists the issued codes ascardNumber,pinCodeandinstructions. 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.deliveryis null for a card that is not a gift. For a gift it is{ status }, wherestatusispending,processing,retry,sentorfailed. The gift email is sent after fulfillment, so an item can befulfilledwhile its delivery is stillpending.
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}/updatechanges who a delivered gift card is sent to. It takes{ "inputs": { "recipientEmail": "...", "giftMessage": "..." } }, needs themanagepermission and anIdempotency-Key, and never charges or refunds anything. A member you leave out keeps its current value, and a card bought without a recipient needsrecipientEmail. A successful update sends the gift email again and startsdelivery.statusatpendingagain.actions.updateisavailableonly for a delivered, unrefunded card whose codes can be shown and while no gift email is being sent. Otherwise the update returns409 / 18005with the reasonIN_PROGRESSorNOT_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 answers422 / 18002(AMENDMENT_NOT_SUPPORTED). While the card is still pending, cancel answers409 / 18001. - Rejected cards are refunded. If fulfillment is rejected, the item is refunded in full automatically and the
order-item.refundedwebhook reports it. Cancelling with the reasonfulfillmentFailedreturns 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 value | Result |
|---|---|
success (or no header) | The order is fulfilled and each item gets a clearly synthetic code and PIN. |
fulfillment.rejected | Fulfillment is rejected after payment. There are no codes, and the item is refunded automatically. |
fulfillment.pending | Returns pending at once. The item becomes eligible for success after 15 minutes. |
fulfillment.late_success | Returns pending at once and becomes eligible for success after 2 minutes. |
fulfillment.late_rejected | Returns 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 / 10001with the reasonNOT_ALLOWED. An unknown or repeated value returns400 / 10001withINVALID_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 showspending.
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.
| Card | Offer | Inputs to send |
|---|---|---|
| Apple, US | Fixed 10 USD | None |
| Amazon, US | Range 5 to 100 USD, step 5 | inputs.value, for example 25 USD |
| Xbox, US | Fixed 25 USD | inputs.recipientIdentifier, for example TEST-RECIPIENT-1234 |
| Steam, AZ | Fixed 20 USD | None |
| Caspian Market, AZ | Fixed 10, 25 and 50 AZN | None (try currency USD to see a face value in AZN) |
| Baku Digital, AZ | Range 5 to 50 USD, step 5 | inputs.value and inputs.recipientIdentifier |
| PlayStation, GB | Fixed 10 GBP | None |
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 / code | Reason | Path | When |
|---|---|---|---|
400 / 10001 | REQUIRED | items[i].inputs.value | A range offer without a value. |
400 / 10001 | INVALID_VALUE | items[i].inputs.value.amount | A value outside the range, off its step, or different from a fixed offer's amount. |
400 / 10001 | CURRENCY_MISMATCH | items[i].inputs.value.currency | The value is not in the card's face currency. |
400 / 10001 | CURRENCY_MISMATCH | items[i].inputs.maxPrice.currency | maxPrice is not in the order currency. |
400 / 10001 | REQUIRED or INVALID_VALUE | items[i].inputs.recipientIdentifier | The offer needs a recipient identifier and it is missing, too long or has control characters. |
400 / 10001 | NOT_ALLOWED | items[i].inputs.giftMessage | A gift message without recipientEmail. |
400 / 10001 | INVALID_VALUE | items[i].inputs.<member> | An inputs member the offer does not define. |
400 / 11004 | EXPIRED_OR_INVALID | items[i] | An unknown, malformed or foreign publicId, including a card id or another product's offer. |
409 / 11003 | UNAVAILABLE | items[i] | The offer cannot be sold now. |
409 / 11002 | PRICE_CHANGED | items[i].inputs.maxPrice | The current unit price is above maxPrice. Nothing is charged. |
404 / 10004 | none | none | GET /v1/giftcards/cards/{id} with an unknown id, or a card with no orderable offer. |
403 / 10003 | SERVICE_NOT_ENABLED | service | Gift cards are not enabled for your account. |
422 / 18000 | none | none | Cancelling an issued card. |
409 / 18005 | IN_PROGRESS or NOT_AVAILABLE | id | A 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.