Order gift cards
Places a gift card order and returns the accepted order.
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.
PartnerApiKeyX-Partner-Key<token>Partner API Key (X-Partner-Key)
Idempotency-Key*stringUUID idempotency key for safe retries of this operation.
uuid- body
The body B2B gift card quote and order both take.
currency?|Order currency, three letters in either case; the API key's currency when omitted. An unsupported code gives
400 / 10001 at currency, reason NOT_SUPPORTED, before any item is checked.
referenceId?|Optional partner order reference, unique per partner, at most 128 characters without leading or trailing spaces. A quote validates it and ignores it.
items*array<>1 to 5 items, with at most 5 cards in total.
OK
- response
The current state of an order.
id*stringOrder id.
uuidorigin*Where the order was created.
status*stringCurrent order status: paymentPending, processing, completed,
partiallyFulfilled, fulfillmentFailed, partiallyRefunded, refunded or cancelled.
"paymentPending""processing""completed""partiallyFulfilled""fulfillmentFailed""partiallyRefunded""refunded""cancelled"total*What was charged for the order, in the order's currency, before refunds: the item prices plus completed amendment charges, less completed amendment credits.
refunded*What completed item refunds returned, in the order's currency; zero when nothing was
returned. You paid total minus refunded, the sum of the items' effectivePaidAmount.
payment?|The latest payment attempt; null when none was made.
items*array<>The order items, one per unit bought.
timeline*array<>Every status the order has had, oldest first, each once per stretch.
createdAt*stringWhen the order was created (UTC).
date-timeupdatedAt*stringWhen anything in the order last changed (UTC): its status, an item's fulfillment, a refund or an amendment.
date-timefulfillmentVersion*integerIncreases with every fulfillment change; matches the
order.fulfillment.updated webhook.
int64referenceId?|Your own order reference, when one was sent.
customer?|The traveller who paid on your hosted site, masked; null unless the origin is site, and
once the traveller's details are deleted at the end of their retention period.
curl -X POST 'https://api.sandbox.openroam.com/v1/giftcards/order' \ -H 'Idempotency-Key: 0b8f7f3e-6b7a-4a52-9a5e-3d2f1a9c7e10' \ -H 'Content-Type: application/json' \ -d '{ "currency": "USD", "referenceId": "partner-order-42", "items": [ { "publicId": "giftcard_p5udmgvqke2bcrwlk35drsqfqm", "quantity": 1, "inputs": { "maxPrice": { "amount": 50, "currency": "USD" } } }, { "publicId": "giftcard_tm4m2tnb4u3dlthj3pvo6zqkha", "quantity": 1, "inputs": { "recipientEmail": "friend@example.com", "giftMessage": "Happy birthday!", "value": { "amount": 25, "currency": "USD" }, "maxPrice": { "amount": 30, "currency": "USD" } } } ]}'{ "id": "01a1413c-2641-7c3e-8b5a-6d9f0e1a2b34", "referenceId": "partner-order-42", "origin": { "channel": "api" }, "status": "processing", "total": { "amount": 75.23, "currency": "USD" }, "refunded": { "amount": 0, "currency": "USD" }, "payment": { "status": "completed", "method": "balance", "amount": { "amount": 75.23, "currency": "USD" }, "wallet": { "label": "Main wallet", "debited": { "amount": 75.23, "currency": "USD" } }, "failure": null }, "items": [ { "id": "01a1413c-265f-7a02-b7c4-1e3f5a7c9d20", "orderId": "01a1413c-2641-7c3e-8b5a-6d9f0e1a2b34", "productType": "giftCard", "price": { "amount": 48.98, "currency": "USD" }, "purchasedProduct": { "name": "Amazon 50 USD", "countryCode": "US", "logoUrl": "https://cdn.openroam.test/amazon.png", "value": { "amount": 50, "currency": "USD" }, "inputs": { "recipientIdentifier": null, "recipientEmail": null, "giftMessage": null }, "details": { "brandName": "Amazon", "isRedeemableGlobally": false, "redemptionInstructions": "Go to amazon.com/redeem and enter the code." } }, "fulfillment": { "status": "pending", "result": null, "failure": null }, "actions": { "amendment": { "availability": "notAvailable", "reason": null }, "cancellation": { "availability": "notAvailable", "reason": null }, "update": { "availability": "notAvailable", "reason": null } }, "createdAt": "2026-10-16T05:27:59.521962Z", "effectivePaidAmount": { "amount": 48.98, "currency": "USD" } }, { "id": "01a1413c-265f-77b1-9041-25aee298d4d0", "orderId": "01a1413c-2641-7c3e-8b5a-6d9f0e1a2b34", "productType": "giftCard", "price": { "amount": 26.25, "currency": "USD" }, "purchasedProduct": { "name": "Amazon 25 USD", "countryCode": "US", "logoUrl": "https://cdn.openroam.test/amazon.png", "value": { "amount": 25, "currency": "USD" }, "inputs": { "recipientIdentifier": null, "recipientEmail": "f***@example.com", "giftMessage": "Happy birthday!" }, "details": { "brandName": "Amazon", "isRedeemableGlobally": false, "redemptionInstructions": "Go to amazon.com/redeem and enter the code." } }, "fulfillment": { "status": "pending", "result": null, "failure": null }, "actions": { "amendment": { "availability": "notAvailable", "reason": null }, "cancellation": { "availability": "notAvailable", "reason": null }, "update": { "availability": "notAvailable", "reason": null } }, "createdAt": "2026-10-16T05:27:59.521962Z", "effectivePaidAmount": { "amount": 26.25, "currency": "USD" } } ], "timeline": [ { "status": "paymentPending", "occurredAt": "2026-10-16T05:27:59.521962Z" }, { "status": "processing", "occurredAt": "2026-10-16T05:27:59.521962Z" } ], "createdAt": "2026-10-16T05:27:59.521962Z", "updatedAt": "2026-10-16T05:27:59.521962Z", "fulfillmentVersion": 1}Search billers GET
Searches the billers of a country and returns them with their offers, one page at a time. Returns `{ items, pagination }`. `countryCode` is required; `category`, `serviceType` and `q` select billers. Utility has no value or price filter. Pages count billers that still have an offer, and prices are indicative, in `currency`. Quote and order take an offer's `publicId`, never the biller's `id`. An invalid or unknown parameter gives 400 / 10001; an unsupported `currency` gives 404 / 10004.
Get a gift card GET
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.