# Authentication (/docs/authentication)
Every Partner API request carries your API key in the `X-Partner-Key` header.
```bash
curl https://api.sandbox.openroam.com/v1/account/services \
-H "X-Partner-Key: $OPENROAM_API_KEY"
```
## Get a key [#get-a-key]
Create API keys in the OpenRoam partner dashboard of the environment you want to call. A key belongs to the environment that issued it: a Sandbox key works only on the Sandbox host, and a Production key only on the Production host. See [Environments](/docs/environments).
Treat a key like a password:
- Keep it on your server. Never put it in a mobile app, a browser page or a public repository.
- Read it from a secret store or an environment variable, as the examples on this site do with `$OPENROAM_API_KEY`.
- Rotate it from the dashboard if it may have leaked, and revoke keys you no longer use.
## Permissions [#permissions]
Each key has order permissions. They apply to the order and order item routes:
| Permission | Allows |
|---|---|
| `read` | Reading orders, order items, fulfillment status, amendments and cancellation previews |
| `manage` | Everything `read` allows, plus placing orders, cancelling, updating and amending items. A `manage` key always has `read` too |
Search, browse, catalog and quote routes work with any valid key. A request without the permission it needs is refused with `403 / 10003` (`FORBIDDEN`).
## Key currency [#key-currency]
Each key has a currency. Search, catalog and quote prices are in that currency when the request does not name one, and an order is charged in the order's `currency`. Send `currency` explicitly when you want another supported currency; [`GET /v1/currencies`](/docs/api-reference/currencies/get-all) lists them.
## Services enabled for your account [#services-enabled-for-your-account]
Each account has its own list of enabled products. [`GET /v1/account/services`](/docs/api-reference/account/get-services) returns it:
```json
{
"services": [
{ "productType": "airtime", "enabled": true, "requestable": false },
{ "productType": "hotel", "enabled": false, "requestable": true }
]
}
```
- `enabled` is `true` when the account may search, quote and order the product now.
- `requestable` is `true` when you can ask OpenRoam to enable it.
New accounts get eSIMs, gift cards, utility and airtime. OpenRoam enables hotels and flights on request. A request for a product that is not enabled is refused with `403 / 10003`, with one `details` entry per refused product and the reason `SERVICE_NOT_ENABLED`. A refused request charges, holds and creates nothing. What you sold before a product was switched off keeps working: reads, cancellations, refunds and the eSIM routes after purchase.
## Authentication errors [#authentication-errors]
| HTTP | Code | Meaning |
|---|---|---|
| 401 | `10002` `UNAUTHORIZED` | The key is missing, unknown or revoked, or belongs to another environment |
| 403 | `10003` `FORBIDDEN` | The key lacks the permission, or the product is not enabled for the account |
See [Errors](/docs/errors) for the error body.
# Changelog (/docs/changelog)
This page lists changes to the Partner API that affect integrations. Breaking changes are announced here before they ship.
## 2026-11 [#2026-11]
- The documentation moved to this site. The API reference is generated from the published OpenAPI specification.
# Environments (/docs/environments)
OpenRoam runs the Partner API in separate environments. Each has its own host, its own accounts and API keys, its own catalog and its own wallet balance.
| Environment | Base URL | Use it for |
|---|---|---|
| Sandbox | `https://api.sandbox.openroam.com` | Building and testing your integration with test funds |
| Production | `https://api.openroam.com` | Real orders, charged to your real wallet |
| Development | `https://api.develop.openroam.com` | OpenRoam's own pre-release testing. Use it only when OpenRoam asks you to |
The base URL has no path: every route starts with `/v1`.
```text
https://api.sandbox.openroam.com/v1/esims/search
https://api.openroam.com/v1/orders/{id}
```
An API key only works on the environment that issued it. Moving from Sandbox to Production means changing the base URL and the key, and nothing else.
## Sandbox [#sandbox]
Sandbox behaves like Production: authentication, validation, pricing, idempotency, orders, refunds and webhooks follow the same contract. The differences:
- **Test money.** Your Sandbox wallet holds test funds. Dashboard top-ups and card payments run in test mode; no real card is charged.
- **Fixture catalog.** Products come from a fixed Sandbox catalog, and fulfillment uses local fixtures instead of real deliveries.
- **Products.** Sandbox supports eSIMs, airtime, gift cards, utility and hotels. Flights are not available in Sandbox yet.
- **Chosen outcomes.** You can choose how an order's fulfillment ends with the `OpenRoam-Sandbox-Scenario` header.
### Choose a fulfillment outcome [#choose-a-fulfillment-outcome]
Send `OpenRoam-Sandbox-Scenario` on a product order route (`POST /v1/esims/order`, `/v1/airtime/order`, `/v1/giftcards/order`, `/v1/hotels/order`, `/v1/utility/order`) or on `POST /v1/orders`:
| Value | Outcome |
|---|---|
| `success` (or no header) | The item is delivered |
| `fulfillment.rejected` | The item is rejected after payment and refunded automatically |
| `fulfillment.pending` | The item stays pending and is delivered after about 15 minutes |
| `fulfillment.late_success` | The item stays pending and is delivered after about 2 minutes |
| `fulfillment.late_rejected` | The item stays pending and is rejected after about 2 minutes |
```bash
curl -X POST https://api.sandbox.openroam.com/v1/esims/order \
-H "X-Partner-Key: $OPENROAM_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "OpenRoam-Sandbox-Scenario: fulfillment.rejected" \
-H "Content-Type: application/json" \
-d '{ "currency": "USD", "items": [{ "publicId": "esim_...", "quantity": 1 }] }'
```
- The durations are approximate: completion is observed on the next routine check, so do not depend on the exact minute.
- An item that stays pending longer than usual shows `fulfillment.progress` with the code `CONFIRMING_OUTCOME`.
- The scenario is part of the idempotent request: the same key with another scenario is `409 / 12001`.
- An unknown, empty or repeated value is `400 / 10001` at `headers.OpenRoam-Sandbox-Scenario` (`INVALID_VALUE`). The header on any other route, or outside Sandbox, is `400 / 10001` (`NOT_ALLOWED`).
Each product guide lists the Sandbox fixtures you can search for.
## Going live [#going-live]
1. Get a Production account and create a Production API key.
2. Fund your Production wallet.
3. Register your webhook endpoint in the Production dashboard; it has its own signing secret.
4. Switch the base URL to `https://api.openroam.com` and use the Production key.
5. Remove the `OpenRoam-Sandbox-Scenario` header from your requests.
# Errors (/docs/errors)
Every error response has the same JSON body. The HTTP status and the application `code` are different values: a missing key is HTTP `401` with `code` `10002`.
```json
{
"code": 10001,
"name": "INVALID_REQUEST",
"message": "The request is invalid.",
"requestId": "0123456789abcdef0123456789abcdef",
"details": [
{ "path": "items[0].inputs.phoneNumber", "reason": "REQUIRED", "message": "..." }
]
}
```
| Field | Use it for |
|---|---|
| `code` | Choosing how to handle the error |
| `name` | The machine name of the code, such as `INVALID_REQUEST`. Never localized |
| `message` | A human-readable text. It may be localized: never parse it |
| `requestId` | Give it to support when you report a problem. It is not an order id |
| `details` | Optional. Each entry is `{ path, reason, message? }`: the field at fault and a machine-readable reason, such as `REQUIRED`, `INVALID_VALUE`, `UNSUPPORTED_FIELD`, `NOT_ALLOWED`, `NOT_SUPPORTED` or `CURRENCY_MISMATCH` |
Treat a `code` you do not know as a general error for its HTTP status, and log the `requestId`.
A `5xx` or a timeout does not prove that a purchase did not happen. Before buying again, repeat the request with the same `Idempotency-Key` or read the order. See [Idempotency](/docs/idempotency).
## Request errors [#request-errors]
| Code | Name | HTTP | What to do |
|---|---|---|---|
| 10000 | `INTERNAL_ERROR` | 500 | Save the `requestId`. For a purchase, check its state first |
| 10001 | `INVALID_REQUEST` | 400 | Fix the input. `details` names the field. An unknown query parameter or body member is refused too |
| 10002 | `UNAUTHORIZED` | 401 | Check the API key and the environment |
| 10003 | `FORBIDDEN` | 403 | Check the key's permissions and the products enabled for the account (`SERVICE_NOT_ENABLED`) |
| 10004 | `NOT_FOUND` | 404 | The id is unknown, or belongs to another account |
| 10005 | `CONFLICT` | 409 | Read the resource again before acting |
| 10006 | `RATE_LIMITED` | 429 | Wait for `Retry-After` when it is present |
| 10007 | `TEMPORARILY_UNAVAILABLE` | 503 | For a purchase, check its state before retrying |
| 10008 | `REQUEST_NOT_COMPLETED` | 502 | Save the `requestId`. It does not confirm that a purchase failed |
| 10009 | `RESPONSE_TIMEOUT` | 504 | Check the state of the operation |
| 10010 | `UNPROCESSABLE_REQUEST` | 422 | Check the data and the conditions of the operation |
| 10011 | `SERVICE_UNAVAILABLE` | 503 | Whether to retry depends on the operation and its state |
| 10012 | `METHOD_NOT_ALLOWED` | 405 | Check the method and the `Allow` header |
| 10013 | `PAYLOAD_TOO_LARGE` | 413 | Send a smaller body |
| 10014 | `UNSUPPORTED_MEDIA_TYPE` | 415 | Send `Content-Type: application/json` |
## Offers and prices [#offers-and-prices]
| Code | Name | HTTP | What to do |
|---|---|---|---|
| 11002 | `OFFER_PRICE_CHANGED` | 409 | The price rose above `inputs.maxPrice` or `maxTotal`, or above the searched price for hotels and flights. Quote again and confirm the new price |
| 11003 | `OFFER_UNAVAILABLE` | 409 | The offer is no longer sold. Search again |
| 11004 | `OFFER_EXPIRED_OR_INVALID` | 400 | The `publicId` expired or is not an offer. Search or quote again |
| 11005 | `OFFER_CURRENCY_MISMATCH` | 400 | Get an offer in the order currency |
| 11006 | `OFFER_TERMS_CHANGED` | 409 | The cancellation terms changed. Quote again and confirm the new terms |
## Idempotency [#idempotency]
| Code | Name | HTTP | What to do |
|---|---|---|---|
| 12000 | `IDEMPOTENCY_KEY_ALREADY_USED` | 409 | The operation already completed. Read its result; use a new key only for a new operation |
| 12001 | `IDEMPOTENCY_KEY_REQUEST_MISMATCH` | 409 | The key was used with another request. Restore the original body |
| 12002 | `IDEMPOTENCY_KEY_IN_PROGRESS` | 409 | Wait `Retry-After` seconds and repeat the same request |
## Payment and wallets [#payment-and-wallets]
| Code | Name | HTTP | What to do |
|---|---|---|---|
| 16000 | `PAYMENT_FAILED` | 402 | The wallet charge was refused and nothing was created. `details[0]` names `wallet` with `INSUFFICIENT_BALANCE` or `WALLET_BLOCKED` when known. Top up, then repeat with the same `Idempotency-Key` |
| 17000 | `WALLET_CURRENCY_ALREADY_EXISTS` | 400 | You already have a wallet in this currency |
| 17001 | `WALLET_LABEL_ALREADY_EXISTS` | 400 | Choose another wallet label |
## After purchase [#after-purchase]
| Code | Name | HTTP | What to do |
|---|---|---|---|
| 18000 | `CANCELLATION_NOT_SUPPORTED` | 422 | This kind of item can never be cancelled once delivered (airtime, utility, gift cards, eSIMs). Do not retry |
| 18001 | `CANCELLATION_NOT_AVAILABLE` | 409 | Not now: `details[0].reason` is `IN_PROGRESS`, `MANUAL_REVIEW` or `NOT_AVAILABLE` |
| 18002 | `AMENDMENT_NOT_SUPPORTED` | 422 | This kind of item cannot be changed |
| 18003 | `AMENDMENT_NOT_AVAILABLE` | 409 | Not now. `MANUAL_REVIEW` points to the manual amendment routes |
| 18004 | `UPDATE_NOT_SUPPORTED` | 422 | This kind of item cannot be updated. Do not retry |
| 18005 | `UPDATE_NOT_AVAILABLE` | 409 | Not now; same reasons as above |
| 18006 | `EMAIL_NOT_SUPPORTED` | 422 | The order has no traveller email. Do not retry |
| 18007 | `EMAIL_NOT_AVAILABLE` | 409 | The email cannot be sent as the order reads now; `details[0].reason` says why |
Read an item's `actions` before you call these routes: each action states its `availability` and `reason`. See [Orders](/docs/orders).
## Product codes [#product-codes]
Some products add their own codes, such as `20000` `AIRTIME_OPERATOR_CHANGED` (search again) and `22000` `ESIM_SMS_NOT_SUPPORTED` (do not retry). Hotels have a range of their own codes. Each [product guide](/docs/products/esims) lists the codes to handle.
## Failures inside a successful response [#failures-inside-a-successful-response]
An order read can answer `200` and still report a failure inside it. These are not HTTP errors:
| Code | Name | Where |
|---|---|---|
| 11001 | `FULFILLMENT_REJECTED` | `items[].fulfillment.failure`: the item was not delivered. It is refunded automatically |
| 16000 | `PAYMENT_FAILED` | `payment.failure`: the payment of a dashboard order failed |
A nested failure is `{ code, name, message }`, with no HTTP status and no `requestId`.
# Idempotency (/docs/idempotency)
Every route that buys, refunds or changes something takes an `Idempotency-Key` header. Sending the same request again with the same key never runs it twice: you get the result of the first call. This makes it safe to retry after a timeout or a dropped connection.
## Which routes need it [#which-routes-need-it]
- Placing an order: every product's `POST /v1//order` and the mixed `POST /v1/orders`.
- After purchase: cancel, update, amendment quote and confirm, manual amendment create and approve (`/v1/order-items/{id}/...`).
- eSIM provisioning, wallet transfers, and resending a traveller email.
Each route in the [API reference](/docs/api-reference) shows whether it takes the header.
## Using a key [#using-a-key]
- Generate a new UUID for each new intent, such as each purchase your customer makes.
- Store it with your own record before you send the request.
- On a timeout, a network error or a `5xx`, send **the same request with the same key and the same body**.
- Use a new key only for a new, intentional operation.
A missing or empty key is `400 / 10001` with `details[0].path` `headers.Idempotency-Key` and reason `REQUIRED`; a value that is not a UUID has the reason `INVALID_VALUE`. Nothing runs in either case.
The key is scoped to your account and to the operation. Rotating your API key, or a repeat sent by another key of the same account, does not create a new order. The same UUID on two different operations does not link them.
## Repeating an order [#repeating-an-order]
| Situation | Response |
|---|---|
| The order was accepted and the request matches | `200` with the same order `id`, as the order reads now |
| The first request is still running | `409 / 12002` `IDEMPOTENCY_KEY_IN_PROGRESS` with `Retry-After` (seconds). Repeat the same request after that delay |
| The body, route or another significant value changed | `409 / 12001` `IDEMPOTENCY_KEY_REQUEST_MISMATCH` |
| The first request's wallet charge was refused (`402 / 16000`) | No order was kept. After a top-up, the same key and body place the order |
| The outcome cannot be determined | `409 / 10005`, `500 / 10000` or `503 / 10011`, and nothing runs again. Check your orders before acting, and give the `requestId` to support |
A completed key never becomes free again: a new purchase needs a new key. A repeat does not retry payment or delivery; it returns the order as it is. A rejected item is refunded automatically, so delivering it again means a new order.
A timeout or a `5xx` does not prove that nothing was bought. Repeat with the same key, or read your orders, before buying again with a new key.
## What counts as the same request [#what-counts-as-the-same-request]
- The order of JSON object members does not matter. The order of array elements does.
- Numbers compare by value: `10`, `10.0` and `1e1` are the same; the string `"10"` is not.
- Strings compare exactly, with no trimming or case folding.
- An explicit `currency` is not the same as an omitted one.
- In Sandbox, the `OpenRoam-Sandbox-Scenario` header is part of the request.
- On the mixed `POST /v1/orders`, `maxTotal` is part of the request.
## Repeating other changes [#repeating-other-changes]
| Route | Repeat with the same key and body, once the first call completed |
|---|---|
| Cancel, update, amendment confirm, manual amendment approve, eSIM provisioning, wallet transfer, email resend | `200` with the result of the first call, as it reads now. Nothing runs again: a resend sends no second email |
| Manual amendment create | `409 / 12000` `IDEMPOTENCY_KEY_ALREADY_USED`. Read the request it made with `GET /v1/order-items/{id}/amendments` |
| Amendment quote | `409 / 12000` `IDEMPOTENCY_KEY_ALREADY_USED`. A quote is not kept, so a lost one cannot be read back: request a new quote with a new key |
On every keyed route, a request still running is `409 / 12002` with `Retry-After`, and a changed body is `409 / 12001`.
## Example responses [#example-responses]
```json title="409 Conflict, Retry-After: 2"
{
"code": 12002,
"name": "IDEMPOTENCY_KEY_IN_PROGRESS",
"message": "A request with this idempotency key is in progress. Retry later.",
"requestId": "b7064e5023c4486587d8162a5ed29f8b"
}
```
```json title="409 Conflict"
{
"code": 12001,
"name": "IDEMPOTENCY_KEY_REQUEST_MISMATCH",
"message": "This idempotency key was used for a different request.",
"requestId": "b7064e5023c4486587d8162a5ed29f8b"
}
```
Tell outcomes apart by HTTP status and `code`, never by `message`.
# Introduction (/docs)
The OpenRoam Partner API lets you sell travel and digital products to your own customers through one integration. Every product follows the same three steps, uses the same order, the same errors and the same webhooks, so once you have integrated one product the others work the same way.
| Product | What your customer gets |
|---|---|
| [eSIMs](/docs/products/esims) | A data plan for a country, a region or the world, installed on their phone |
| [Airtime](/docs/products/airtime) | Mobile credit sent straight to a phone number |
| [Utility](/docs/products/utility) | A paid bill, such as prepaid electricity |
| [Gift cards](/docs/products/gift-cards) | A digital gift card code, optionally emailed as a gift |
| [Hotels](/docs/products/hotels) | A confirmed hotel booking |
| [Flights](/docs/products/flights) | A ticketed flight booking |
## How it works [#how-it-works]
### Search [#search]
Find what to sell. A search returns **items** (an operator, a biller, a gift card brand, an eSIM destination, a hotel or a flight itinerary), and each item lists the **offers** you can buy. An offer's `publicId` is the only id you order with.
### Quote [#quote]
Send the offer with the customer's inputs to the product's `quote` route. The quote validates everything the order would, and returns the current price without buying anything.
### Order [#order]
Send the quoted body to the product's `order` route (or to `POST /v1/orders` to mix products in one order) with an `Idempotency-Key`, each item's `publicId` set to the one the quote returned: for hotels, flights and gift cards it can differ from the one you searched with. OpenRoam charges your wallet and delivers the product. You follow delivery with the order read or with the `order.fulfillment.updated` webhook.
## Conventions [#conventions]
- **Base URL and paths.** Every route starts with `/v1`, for example `https://api.sandbox.openroam.com/v1/esims/search`. See [Environments](/docs/environments).
- **Authentication.** Send your API key in the `X-Partner-Key` header. See [Authentication](/docs/authentication).
- **Money.** Amounts are `{ "amount": 10.5, "currency": "USD" }`. OpenRoam charges you a `price`; airtime, utility and gift cards also state the `value` your customer receives.
- **Times.** Every time is a UTC instant in ISO 8601 ending in `Z`, such as `2026-11-16T10:00:00Z`. A time bound to a place, such as a flight departure, also comes with the place's time zone and its local clock. A calendar date, such as a check-in date, is a plain date (`2026-11-16`).
- **Names.** JSON members and enum values are camelCase, in responses and in webhooks.
- **Ids.** Product and offer ids are opaque strings with a prefix, such as `esim_…` or `rate_…`. Orders and order items have UUIDs.
- **Errors.** Every error has the same body: `code`, `name`, `message`, `requestId` and optional `details`. See [Errors](/docs/errors).
## Where to next [#where-to-next]
- Make your first purchase in Sandbox with the [Quickstart](/docs/quickstart).
- Browse every operation in the [API reference](/docs/api-reference).
- Use an official client library from [SDKs](/docs/sdks), or connect an AI agent with the [MCP server](/docs/mcp).
This site is also available as Markdown: [`/llms.txt`](/llms.txt) lists every page, [`/llms-full.txt`](/llms-full.txt) holds all of them, and each page has a Markdown copy at its URL plus `.md`. The OpenAPI specification is at [`/openapi.json`](/openapi.json).
# MCP server (/docs/mcp)
The MCP server is in private beta and not on a public package registry yet. OpenRoam sends you the release file to install.
`@openroam/mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server. It connects AI assistants and agents (Claude, Cursor, VS Code and any other MCP client) to the Partner API. With one API key, an agent can search, price, buy and manage airtime, utility bill payments, gift cards, eSIMs, hotels and flights, and follow delivery to the end.
Every tool call is a normal Partner API request made with your key, so your permissions, enabled products, validation, idempotency and errors apply exactly as they do to your own integration.
A second group of read-only tools helps developers integrate the API: they search the documentation, explain an error, check a request before it is sent and build a signed test webhook event. Most of them work without a key.
## Why it is safe to let an agent buy [#why-it-is-safe-to-let-an-agent-buy]
| Guard | What it does |
|---|---|
| Quote, then confirm | Ordering takes only a sealed token from a quote, so the agent cannot change items, inputs or prices |
| Price lock | The order is sent with each quoted unit price as `maxPrice` and the quoted total as `maxTotal`. If a price rose, nothing is charged |
| One purchase per quote | The `Idempotency-Key` comes from the quote token, so a repeated call returns the same order and never buys twice |
| Bound to your account | A token works only with the key and environment that created it, and expires within 15 minutes |
| Spend cap | `OPENROAM_MAX_ORDER_TOTAL` refuses any order above your cap before a request is sent |
| Read-only mode | `OPENROAM_READ_ONLY=true` registers no tool that changes anything or moves money |
| Product allow-list | `OPENROAM_PRODUCTS` limits the agent to the products you choose |
| Secrets stay out of chats | Gift card codes, PINs, utility tokens and eSIM activation data are hidden unless you allow them |
| Sandbox by default | Production must be chosen explicitly, and every result says which environment it came from |
Moving money between wallets, wallet settings and webhook settings are not available to agents.
## Connect a client [#connect-a-client]
Use a Sandbox key first. For Claude Code:
```bash
claude mcp add openroam -e OPENROAM_API_KEY=your_sandbox_key -- npx -y @openroam/mcp
```
For Claude Desktop, Cursor and other clients, add the server to the client's MCP configuration:
```json
{
"mcpServers": {
"openroam": {
"command": "npx",
"args": ["-y", "@openroam/mcp"],
"env": { "OPENROAM_API_KEY": "your_sandbox_key" }
}
}
}
```
During the private beta, replace `npx -y @openroam/mcp` with the path of the release file you received.
# Orders (/docs/orders)
Every purchase is an order. An order holds one or more order items, one per product bought, and every product uses the same order envelope.
## Placing an order [#placing-an-order]
You can order through a product's own route, such as [`POST /v1/esims/order`](/docs/api-reference/esims/create-order), or mix products in one order with [`POST /v1/orders`](/docs/api-reference/orders/create-order). [`POST /v1/orders/quote`](/docs/api-reference/orders/quote-order) prices the same mixed body without buying.
```json title="POST /v1/orders"
{
"currency": "USD",
"referenceId": "my-order-42",
"maxTotal": { "amount": 10.7, "currency": "USD" },
"items": [
{
"productType": "airtime",
"publicId": "airtime_...",
"quantity": 1,
"inputs": { "phoneNumber": "+2348012345678", "value": { "amount": 1000, "currency": "NGN" } }
},
{ "productType": "esim", "publicId": "esim_...", "quantity": 1, "inputs": {} }
]
}
```
- An order has 1 to 5 items, with a total quantity of at most 5. Airtime, utility, eSIM top-ups, hotels and flights take quantity 1.
- `inputs` carries the offer's required inputs plus two standard fields where the product takes them: `value` (the amount to deliver, for range offers) and `maxPrice` (the highest unit price you accept).
- `maxTotal` (mixed orders only) is the highest order total you accept. A higher total is `409 / 11002` and nothing is charged.
- `referenceId` is your own reference, kept with the order.
- Every order needs an `Idempotency-Key`. See [Idempotency](/docs/idempotency).
OpenRoam charges the order total to your wallet when it accepts the order. A refused charge is `402 / 16000` and keeps no order.
## Reading orders [#reading-orders]
- [`GET /v1/orders/{id}`](/docs/api-reference/orders/get-by-id) returns one order as it is now.
- [`GET /v1/orders`](/docs/api-reference/orders/get-all) lists orders, with filters and `page` and `limit` paging.
- [`GET /v1/orders/{orderId}/fulfillment/status`](/docs/api-reference/orders/get-fulfillment-status) returns the delivery state of every item.
An order of another account answers `404 / 10004`, exactly like an unknown id.
## Order status [#order-status]
| `status` | Meaning |
|---|---|
| `paymentPending` | The order exists and its payment has not completed. Rare on the API: if a wallet charge was taken but not confirmed, repeating the order request with the same key completes it, and OpenRoam completes it automatically too. The wallet is never charged twice |
| `processing` | Paid, and at least one item has no outcome yet |
| `completed` | Every item was delivered |
| `partiallyFulfilled` | Some items were delivered and the others were rejected and refunded |
| `fulfillmentFailed` | No item was delivered. Rejected items are refunded |
| `partiallyRefunded` | At least one delivered item was cancelled and refunded, and at least one was not |
| `refunded` | Every delivered item was cancelled and refunded |
| `cancelled` | The order was never paid; nothing was charged |
`payment.status` is `pending`, `authorized`, `completed`, `failed`, `partiallyRefunded`, `refunded` or `cancelled`. `total` is what was charged, and `refunded` is what completed refunds returned.
## Order items [#order-items]
Each item carries:
- `purchasedProduct`: what was bought, with the inputs you sent. Customer identifiers are masked: phones as `+***`, emails as `a***@domain`, other identifiers as `***`.
- `fulfillment`: `status` (`pending`, `fulfilled` or `rejected`), `result` (only what was delivered, such as a gift card code or a hotel confirmation) and `failure`. While an outcome is being confirmed, a pending item can also carry `progress` with the code `CONFIRMING_OUTCOME`.
- `actions`: whether you can cancel, amend or update the item now.
- `refund`: the item's refund, once there is one.
A rejected item is refunded automatically and reported by the `order-item.refunded` webhook. There is no retry: to deliver it again, place a new order.
## After purchase [#after-purchase]
All products share the same item routes. The item id is `items[].id` from the order.
| Operation | Route | Permission | `Idempotency-Key` |
|---|---|---|---|
| Get an item | [`GET /v1/order-items/{id}`](/docs/api-reference/order-items/get-by-id) | `read` | no |
| Preview a cancellation | [`GET /v1/order-items/{id}/cancellation-preview`](/docs/api-reference/order-items/get-cancellation-preview) | `read` | no |
| Preview cancelling a whole order | [`GET /v1/orders/{id}/cancellation-preview`](/docs/api-reference/orders/get-cancellation-preview) | `read` | no |
| Cancel | [`POST /v1/order-items/{id}/cancel`](/docs/api-reference/order-items/cancel) | `manage` | yes |
| Update | [`POST /v1/order-items/{id}/update`](/docs/api-reference/order-items/update) | `manage` | yes |
| Quote an amendment | [`POST /v1/order-items/{id}/amendments/quote`](/docs/api-reference/order-items/quote-amendment) | `manage` | yes |
| Confirm an amendment | [`POST /v1/order-items/{id}/amendments/confirm`](/docs/api-reference/order-items/confirm-amendment) | `manage` | yes |
| List an item's amendments | [`GET /v1/order-items/{id}/amendments`](/docs/api-reference/order-items/get-amendments) | `read` | no |
| List all amendments | [`GET /v1/amendments`](/docs/api-reference/order-items/list-partner-amendments) | `read` | no |
| Hotel manual amendments | [`POST /v1/order-items/{id}/manual-amendments`](/docs/api-reference/hotel-manual-amendments/create-manual-amendment) and its approve, decline and cancel routes | `manage` | create and approve |
Check the item's `actions` first. Each of `actions.cancellation`, `actions.amendment` and `actions.update` has an `availability` and a `reason`. A call that is not available now is refused with a `409` from the `18001`-`18005` range; a kind of item that can never do it gives a `422`. See [Errors](/docs/errors#after-purchase).
What each product supports:
| Product | Cancel | Amend | Update |
|---|---|---|---|
| Airtime, utility, eSIMs | Not after delivery (`422 / 18000`). A rejected item is refunded automatically | no | no |
| Gift cards | Not after delivery (`422 / 18000`). A rejected item is refunded automatically | no | The gift recipient and message |
| Hotels | By the cancellation terms of the booking | By API for some hotels, otherwise with manual amendments | no |
| Flights | By the rules of the fare | By API | no |
The product guides explain the details: [Gift cards](/docs/products/gift-cards), [Hotels](/docs/products/hotels) and [Flights](/docs/products/flights).
## Resend a traveller email [#resend-a-traveller-email]
For an order placed on one of your hosted sites, [`POST /v1/orders/{id}/emails/resend`](/docs/api-reference/orders/resend-email) sends the receipt, or one item's delivery email, to the traveller again.
# Airtime (/docs/products/airtime)
## What you can sell [#what-you-can-sell]
Airtime is a mobile top-up for one phone number. An operator is one mobile operator in one country, and it lists offers:
- **Fixed offers** deliver a set amount, such as 40 AZN.
- **Range offers** deliver the amount you choose within a minimum, a maximum and a step, such as 10 to 200 AZN.
Each item tops up one number once, so `quantity` is always 1. Prices are in your order currency, while the delivered value is in the operator's currency.
## The flow [#the-flow]
There are two ways to find an offer. Both end in the same quote and order.
**Detected flow.** Give OpenRoam the recipient's number, and it finds the operator and its offers.
1. [`GET /v1/airtime/search?phoneNumber=`](/docs/api-reference/airtime/search) returns the detected operator with its offers.
**Manual flow.** Use this when search finds no operator, or when you want your customer to choose.
1. [`GET /v1/airtime/operators?countryCode=`](/docs/api-reference/airtime/get-operators) lists the operators of a country, without offers.
2. [`GET /v1/airtime/operators/{id}?phoneNumber=`](/docs/api-reference/airtime/get-operator) returns the chosen operator with its offers, in the shape search returns.
**Then, in both flows:**
3. [`POST /v1/airtime/quote`](/docs/api-reference/airtime/quote) prices an order body. It has no side effects.
4. [`POST /v1/airtime/order`](/docs/api-reference/airtime/create-order) places the order. It needs an `Idempotency-Key` header and an API key with the `manage` permission.
Other routes:
- [`GET /v1/airtime/number-lookup?phoneNumber=`](/docs/api-reference/airtime/lookup-number) describes a number: validity, country, calling code, formats and line type, plus the network name OpenRoam finds for it. Nothing is stored.
- [`GET /v1/airtime/catalog`](/docs/api-reference/airtime/catalog) is the operator directory, page by page with a cursor, as summaries without offers. Filter with `countryCode`, page with `limit` (1 to 100) and `cursor`.
Phone numbers are always in international format: a leading `+` or `00`, with optional spaces, hyphens and parentheses. National numbers and bare digits are rejected. The country comes from the number.
Unknown query parameters are rejected with `400 / 10001` (`UNSUPPORTED_FIELD`).
See [Orders](/docs/orders) for order and item status, and [Idempotency](/docs/idempotency) for retries.
## Search [#search]
```bash
curl "https://api.sandbox.openroam.com/v1/airtime/search?phoneNumber=%2B994501234567" \
-H "X-Partner-Key: $OPENROAM_API_KEY"
```
```json
{
"items": [
{
"id": "operator_tq7vbm2xk4hdn6wzr3pyjc5fae",
"name": "Example Mobile",
"countryCode": "AZ",
"category": null,
"logoUrl": "https://example.com/airtime/example-mobile.png",
"description": null,
"offers": [
{
"publicId": "airtime_raanuxyz6cxzie3w3my6c3r2wm",
"name": "Example Mobile 40 AZN",
"description": "Top-up for **Example Mobile** numbers.",
"value": { "type": "fixed", "amount": 40, "currency": "AZN" },
"price": { "amount": 25.00, "currency": "USD" },
"requiredInputs": [
{ "name": "phoneNumber", "type": "phone", "required": true, "description": "The recipient's mobile number in international format, starting with + or 00." }
],
"details": { "redemptionType": "directTopUp", "readMore": "Credit arrives within minutes." }
},
{
"publicId": "airtime_ms45o6lwxtqgrsculqdhop74zq",
"name": "Example Mobile 10 - 200 AZN",
"description": "Top-up for **Example Mobile** numbers.",
"value": { "type": "range", "min": 10, "max": 200, "step": 0.01, "currency": "AZN" },
"price": { "min": 6.25, "max": 125.00, "currency": "USD" },
"requiredInputs": [
{ "name": "phoneNumber", "type": "phone", "required": true, "description": "The recipient's mobile number in international format, starting with + or 00." }
],
"details": { "redemptionType": "directTopUp", "readMore": "Credit arrives within minutes." }
}
]
}
],
"pagination": { "currentCount": 1, "totalCount": 1, "skip": 0, "limit": 10, "hasMore": false, "page": 1, "totalPages": 1 },
"details": { "phoneLookup": { "status": "detected", "carrierName": "Example Mobile", "countryCode": "AZ" } }
}
```
Each search looks the number up once and returns at most one operator, so `page` must be 1. `limit` is 1 to 100 (default 10). `countryCode` and `cursor` are not search parameters.
`details.phoneLookup` tells you what the lookup found:
| `status` | Meaning | `items` |
|---|---|---|
| `detected` | The number's operator is in the catalog. | The operator with its offers. Empty when your offer filters leave none. |
| `notDetected` | No operator was found for the number. | Empty |
| `conflict` | The result contradicts the number's country, or matches several operators. | Empty |
| `notInCatalog` | The operator is not in the catalog, the line is not a mobile line, or no operator name came back. | Empty |
- `carrierName` is for display only. It is never an operator id.
- `countryCode` comes from the number itself and is present for every status.
- When `items` is empty, use the manual flow with `details.phoneLookup.countryCode`.
- A lookup that fails gives `503 / 10007` (`TEMPORARILY_UNAVAILABLE`). Retry later.
### Offer filters [#offer-filters]
`search` and `operators/{id}` take the same filters, which select offers inside the operator:
| Parameter | Meaning |
|---|---|
| `valueType` | `fixed` or `range`. |
| `valueCurrency` | Currency of `minValue` and `maxValue`. Required with either. |
| `minValue`, `maxValue` | Keep offers whose value overlaps this range. |
| `minPrice`, `maxPrice` | Keep offers whose indicative price overlaps this range, in the price currency. |
| `currency` | Price currency. The default is your API key's currency. |
The query parameter `maxPrice` filters indicative prices. It is not the `inputs.maxPrice` price limit of an order.
### Manual flow details [#manual-flow-details]
- `operators?countryCode=` takes only `countryCode` (ISO 3166-1 alpha-2, either letter case) and returns `{ items: [{ id, name, countryCode, category, logoUrl }] }` ordered by name, without paging.
- `operators/{id}` makes no lookup. A number of another country than the operator gives `400 / 10001` (`COUNTRY_MISMATCH`) at `phoneNumber`. An unknown id gives `404 / 10004`.
- Operator ids start with `operator_`. They name the operator only. You quote and order with an offer's `publicId`.
## Offers [#offers]
An operator lists its fixed offers by ascending value, then its range offers by ascending minimum.
- `value` is what the subscriber receives, in the operator's currency. A range has `min`, `max` and `step`.
- `price` is indicative and in the requested currency. For a range it is `{ min, max, currency }`, the price of the range's minimum and maximum. The quote is authoritative.
- A range's `step` is the smallest increment of the currency when the offer declares none (0.01 in most currencies, 1 in JPY, 0.001 in KWD). Quote and order accept the same `min`, `max` and `step` that search publishes. A step does not promise that every amount can be delivered. The quote checks the exact amount.
- `details.redemptionType` is `directTopUp` (an automatic recharge), `pin` (a PIN the customer activates) or null.
- `requiredInputs` lists `phoneNumber` first, then one `settings.` entry for each setting the operator requires.
## Quote and order [#quote-and-order]
Quote and order take the same body. The fixed offer below is bought as it is, and the range offer at 50 AZN:
```json
{
"currency": "USD",
"referenceId": "partner-order-42",
"items": [
{
"publicId": "airtime_raanuxyz6cxzie3w3my6c3r2wm",
"quantity": 1,
"inputs": {
"phoneNumber": "+994501234567",
"maxPrice": { "amount": 25, "currency": "USD" }
}
},
{
"publicId": "airtime_ms45o6lwxtqgrsculqdhop74zq",
"quantity": 1,
"inputs": {
"phoneNumber": "+994501234567",
"value": { "amount": 50, "currency": "AZN" },
"maxPrice": { "amount": 31.25, "currency": "USD" }
}
}
]
}
```
```bash
curl -X POST https://api.sandbox.openroam.com/v1/airtime/quote \
-H "X-Partner-Key: $OPENROAM_API_KEY" \
-H "Content-Type: application/json" \
-d @airtime-order.json
curl -X POST https://api.sandbox.openroam.com/v1/airtime/order \
-H "X-Partner-Key: $OPENROAM_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d @airtime-order.json
```
Quote response:
```json
{
"currency": "USD",
"items": [
{
"publicId": "airtime_raanuxyz6cxzie3w3my6c3r2wm",
"quantity": 1,
"name": "Example Mobile 40 AZN",
"value": { "amount": 40, "currency": "AZN" },
"price": { "amount": 25.00, "currency": "USD" },
"details": { "estimatedDeliveredValue": { "amount": 40, "currency": "AZN" } }
},
{
"publicId": "airtime_ms45o6lwxtqgrsculqdhop74zq",
"quantity": 1,
"name": "Example Mobile 50 AZN",
"value": { "amount": 50, "currency": "AZN" },
"price": { "amount": 31.25, "currency": "USD" },
"details": { "estimatedDeliveredValue": { "amount": 50, "currency": "AZN" } }
}
],
"total": { "amount": 56.25, "currency": "USD" }
}
```
- 1 to 5 items. `quantity` is optional and must be 1.
- `referenceId` is your own reference. Quote validates it and ignores it.
- A quote reserves nothing and does not expire. Order recalculates the operator and the price, so a quote does not bind it.
- `price` is per unit, and `total` is the sum of each price times its quantity.
- Items are checked one at a time in request order, and the first failing item ends the request. Quote and order report the same error for it.
- In a mixed [`POST /v1/orders`](/docs/api-reference/orders/create-order), each item adds `productType: "airtime"` and takes the same `inputs`.
### Inputs [#inputs]
| Member | Required | Meaning |
|---|---|---|
| `phoneNumber` | yes | The recipient's number in international format. It must belong to the offer's country. |
| `settings` | when the offer lists a required `settings.` | Operator settings as an object of text values, only with the names the offer lists. For example `{ "customerId": "C-1" }`. |
| `value` | for a range offer | The top-up, `{ amount, currency }`, in the offer's value currency, within `min` and `max` and on the `step`. |
| `maxPrice` | no | The highest unit price you accept, `{ amount, currency }`, in the order currency. |
| `minDeliveredValue` | no | Range offers only. The lowest value you accept the recipient to receive, `{ amount, currency }`, in the `value` currency and at most `value`. |
Rules for `value`, `maxPrice` and `minDeliveredValue`:
- On a fixed offer, `value` is optional. When sent, it must equal the offer's amount and currency, and the item is ordered exactly as one sent without it.
- A range offer without `value` fails with `REQUIRED` at `inputs.value`.
- An amount is above 0 and has at most the decimals of its currency (none in JPY or KRW, three in KWD, two in most). A currency is three letters in either case.
- A current unit price above `maxPrice` fails with `409 / 11002` (`PRICE_CHANGED`) at `items[i].inputs.maxPrice`. Nothing is ordered or charged. The value is never reduced to fit `maxPrice`.
- Without `minDeliveredValue`, a range top-up must deliver exactly `value`. With it, the top-up may deliver less, down to the minimum. A fixed offer rejects it with `NOT_ALLOWED`. A range offer that sends it without `value` gets `REQUIRED` at `inputs.value`.
- When no delivery option can deliver an amount between the minimum and `value`, the item fails with `400 / 10001` (`AMOUNT_UNAVAILABLE`) at `items[i].inputs.value.amount`. Choose another value or allow a minimum.
- Any other member of `inputs`, and any member beside `inputs`, fails with `INVALID_VALUE`.
`details.estimatedDeliveredValue` in the quote is what the recipient is expected to receive. With `minDeliveredValue` it can be below `value`, so show it as the expected receipt.
### The number is looked up again [#the-number-is-looked-up-again]
Quote and order look the number up again for every item, whichever flow found the offer.
- When the operator is confirmed for the number, the item is priced and sold as usual.
- When the number cannot belong to the offer's operator, the item fails with `409 / 20000` (`AIRTIME_OPERATOR_CHANGED`) before anything is charged. This happens when another catalog operator is detected, the number is in another country than the operator, or several catalog operators match and the offer's is not one of them. Search again.
- In every other case, such as `notDetected` or `notInCatalog`, the item is sold as a manual selection, through the offers of the manual flow.
OpenRoam cannot always confirm that a number belongs to the operator chosen in the manual flow, and a top-up delivered after a wrong manual choice is not refunded. Ask your customer to check the operator before a manual purchase.
## The order item [#the-order-item]
An airtime item carries `purchasedProduct`, what was bought, and `fulfillment.result`, what was delivered:
```json
{
"id": "01a1432e-7121-7829-a554-d8e2b22270c6",
"orderId": "01a1432e-7121-7b0e-a0a0-c35454d3b883",
"productType": "airtime",
"price": { "amount": 31.25, "currency": "USD" },
"purchasedProduct": {
"name": "Example Mobile 50 AZN",
"countryCode": "AZ",
"logoUrl": "https://example.com/airtime/example-mobile.png",
"value": { "amount": 50, "currency": "AZN" },
"inputs": { "phoneNumber": "+994***4567", "minDeliveredValue": null },
"details": {
"redemptionType": "directTopUp",
"estimatedDeliveredValue": { "amount": 50, "currency": "AZN" },
"readMore": "Credit arrives within minutes."
}
},
"fulfillment": {
"status": "fulfilled",
"result": {
"deliveredValue": { "amount": 50, "currency": "AZN" },
"details": { "redemption": { "type": "directTopUp", "pin": null, "instructions": 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": 31.25, "currency": "USD" }
}
```
- `purchasedProduct.name` is frozen at purchase. A range purchase is named at the purchased value.
- `purchasedProduct.value` is the top-up ordered.
- `purchasedProduct.inputs.phoneNumber` is masked as a plus sign, the country calling code, `***` and the last four digits, for example `+994***4567`. `minDeliveredValue` is echoed, and is null when none was sent. Operator `settings` are not echoed.
- `fulfillment.result.deliveredValue` is the amount reported as received by the recipient. It is null until known. A value reported later updates the result and sends another `order.fulfillment.updated` webhook with a higher `fulfillmentVersion`, while the status stays `fulfilled`.
- `fulfillment.result.details.redemption` is `{ type, pin, instructions }`, or null when the delivery is not declared. A `pin` top-up carries the issued PIN as a string and the customer `instructions`. Either is null when it was not received. Both are null for a `directTopUp`.
Read the order with [`GET /v1/orders/{id}`](/docs/api-reference/orders/get-by-id). The [`order.fulfillment.updated` webhook](/docs/api-reference/webhooks/order-fulfillment-updated) carries the same `result`. See [Webhooks](/docs/webhooks).
A delivered top-up cannot be cancelled, amended or updated. Cancel and its preview answer `422 / 18000`, amendments `422 / 18002` and update `422 / 18004`. While the top-up is pending, cancel answers `409 / 18001`. A rejected top-up is refunded in full automatically and reported by the `order-item.refunded` webhook. See [Orders](/docs/orders).
## Testing in Sandbox [#testing-in-sandbox]
Use [Sandbox](/docs/environments) with your Sandbox key. Authentication, validation, pricing, wallet payment and webhooks behave as in production, and the catalog and outcomes are synthetic.
### Scenarios [#scenarios]
`POST /v1/airtime/order` and the shared `POST /v1/orders` accept the `OpenRoam-Sandbox-Scenario` header:
| Value | Result |
|---|---|
| Omitted or `success` | A fulfilled item with the delivered value. |
| `fulfillment.rejected` | A rejected item with the normal fulfillment failure (`11001`) and no delivered result. It is refunded automatically. |
| `fulfillment.pending` | The item stays `pending` without blocking, and becomes eligible for success after about 15 minutes. |
| `fulfillment.late_success` | Pending, then success after about 2 minutes. |
| `fulfillment.late_rejected` | Pending, then rejection after about 2 minutes. |
```bash
curl -X POST https://api.sandbox.openroam.com/v1/airtime/order \
-H "X-Partner-Key: $OPENROAM_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "OpenRoam-Sandbox-Scenario: fulfillment.rejected" \
-H "Content-Type: application/json" \
-d @airtime-order.json
```
- The scenario is saved with the order and takes part in idempotency. The same key and body replay the order. The same key with a different scenario returns `409 / 12001`. Use a new key to try another scenario. While the first request is still being accepted, the same key returns `409 / 12002`: retry after the `Retry-After` seconds.
- Search, quote and reads take no scenario header. Sending it there, or outside Sandbox, returns `400 / 10001` (`NOT_ALLOWED`). An unknown, empty or repeated value returns `400 / 10001` (`INVALID_VALUE`).
- Scenarios do not bypass validation, permissions or wallet checks.
- Timing is approximate and not a guarantee. A pending item may show `fulfillment.progress` with code `CONFIRMING_OUTCOME`. By default Sandbox fulfillment takes a few seconds, so read the order again before assuming a final state.
### Sandbox catalog [#sandbox-catalog]
The Sandbox catalog covers 30 countries: AZ, US, CA, TR, AE, ES, MY, MX, PH, ID, IT, PT, PL, GE, AM, PK, BD, VN, TH, EG, SA, ZA, BR, AR, CL, CO, NG, KE, SG and KR. Each country has one to three operators. Each operator has five to seven fixed denominations and one range, in the country's currency. Do not hardcode offer ids: search and the operator routes return them.
| Input | Sandbox behavior |
|---|---|
| A valid international number, such as `+994501234567` | Resolves a test operator and its offers for the number's country. |
| A valid number of an unsupported country | Search returns no items with `notInCatalog`, not an error. |
| Manual flow | You can select any listed operator of the number's country and quote or buy its offers. |
| Checkout currency | USD by default. Other configured currencies use a stored test exchange rate. |
Sample denominations, in the currency each country delivers:
| Country | Fixed values | Range | Step |
|---|---|---|---|
| AZ (AZN) | 10, 15, 20, 25, 30, 40, 50 | 5 to 50 | 1 |
| US (USD) | 10, 15, 20, 25, 30, 40, 50 | 5 to 100 | 1 |
| TR (TRY) | 65, 70, 250, 300, 400, 500, 750 | 65 to 1,000 | 5 |
| ES (EUR) | 5, 6, 10, 15, 20, 25, 30 | 5 to 50 | 1 |
Try these cases with `+994501234567`:
- Quote the fixed 10 AZN offer, and the range at 5 AZN and 50 AZN. The same range rejects 4, 5.50 and 51 AZN with `INVALID_VALUE` at `inputs.value.amount`.
- Send `currency: "EUR"` to see the checkout price in EUR while the delivered value stays in AZN.
- Search with `valueType=fixed&valueCurrency=AZN&minValue=12&maxValue=12` to find a fixed 12 AZN offer that lists a required `settings.recipientReference`. Quote it with `"settings": { "recipientReference": "test-ref-01" }`. Without the setting you get `400 / 10001` (`REQUIRED`).
- Search an operator's details with `valueType=range&valueCurrency=AZN&minValue=55` to find a range from 55 to 75 AZN where only 55 AZN is delivered exactly, and any higher value delivers 1 AZN less. Request 60 AZN with `"minDeliveredValue": { "amount": 59, "currency": "AZN" }` to be quoted and delivered 59 AZN. Without the minimum, or with a minimum of 60, you get `400 / 10001` (`AMOUNT_UNAVAILABLE`).
- Use `+966501234567` to test a country with a single operator.
## Errors [#errors]
Paths below are relative to the item. On quote, order and the shared order they are prefixed with `items[i].`.
| Status / code | Reason | When | Path |
|---|---|---|---|
| `400 / 10001` | `INVALID_VALUE` | `quantity` is not 1, or the number is not international. | `quantity`, `inputs.phoneNumber` |
| `400 / 10001` | `COUNTRY_MISMATCH` | The number belongs to another country than the offer. | `inputs.phoneNumber` |
| `400 / 10001` | `REQUIRED` | A required operator setting is missing, or a range offer has no `value`. | `inputs.settings.`, `inputs.value` |
| `400 / 10001` | `UNSUPPORTED_FIELD` | A setting the offer does not list. | `inputs.settings.` |
| `400 / 10001` | `INVALID_VALUE` | `value` outside the range, off its step, or not the fixed offer's amount, or an amount that is not above 0 or has too many decimals. | `inputs.value.amount` |
| `400 / 10001` | `AMOUNT_UNAVAILABLE` | No delivery option can deliver the amount. | `inputs.value.amount` |
| `400 / 10001` | `CURRENCY_MISMATCH` | `value`, `minDeliveredValue` or `maxPrice` in the wrong currency. | `inputs.value.currency`, `inputs.minDeliveredValue.currency`, `inputs.maxPrice.currency` |
| `400 / 10001` | `NOT_ALLOWED` | `minDeliveredValue` on a fixed offer. | `inputs.minDeliveredValue` |
| `400 / 11004` | `EXPIRED_OR_INVALID` | Unknown, malformed or foreign `publicId`, an operator id, or an offer of another product. | `items[i]` |
| `409 / 11003` | `UNAVAILABLE` | The offer cannot be sold now. | `items[i]` |
| `409 / 11002` | `PRICE_CHANGED` | The current unit price is above `inputs.maxPrice`. | `inputs.maxPrice` |
| `409 / 20000` | `AIRTIME_OPERATOR_CHANGED` | The lookup shows the offer's operator cannot be the number's. | none |
| `503 / 10007` | `TEMPORARILY_UNAVAILABLE` | The number lookup or the service is temporarily unavailable. Nothing is charged. | none |
| `404 / 10004` | | `operators/{id}` with an unknown id, or an operator without an orderable offer. | none |
| `403 / 10003` | `SERVICE_NOT_ENABLED` | Airtime is not enabled for your account, or the key lacks the `manage` permission for an order. | `service` |
`409 / 20000` and `503 / 10007` carry no `details`, so they do not name the item. After one of them in a request with several items, quote the items one at a time to find it.
Check which services are enabled with [`GET /v1/account/services`](/docs/api-reference/account/get-services). Idempotency errors are shared across products; see [Idempotency](/docs/idempotency). For the common error format, see [Errors](/docs/errors).
## Next steps [#next-steps]
- [Quickstart](/docs/quickstart) for your first order.
- [Authentication](/docs/authentication) and [Environments](/docs/environments) for keys and hosts.
- [Orders](/docs/orders) for order and item status.
- [Webhooks](/docs/webhooks) for signing and retries.
# eSIMs (/docs/products/esims)
## What you can sell [#what-you-can-sell]
OpenRoam sells data eSIM plans by destination. A destination is one country (`local`), a region such as Europe (`regional`) or the whole world (`global`). Each destination lists offers: plans with a data allowance, a validity in days and a price.
You can sell:
- **A new eSIM.** Installed at once (the default) or as a deferred entitlement that you provision later.
- **A top-up.** An extra plan added to an eSIM you already bought, addressed by its ICCID.
An eSIM has no monetary value, so there is no `inputs.value` on this product. The price guard is `inputs.maxPrice`.
## The flow [#the-flow]
### Search [#search]
[`GET /v1/esims/search`](/docs/api-reference/esims/search) returns destinations with their offers, one page at a time. Filter by `countryCode`, `category`, `region`, `validityDays`, `isUnlimited` and `currency`. A country filter matches the destination's coverage, so `countryCode=FR` returns France and every regional or global destination that covers France.
Other ways to browse:
- [`GET /v1/esims/destinations`](/docs/api-reference/esims/get-destinations) lists every destination with an orderable offer, as summaries without offers.
- [`GET /v1/esims/destinations/{id}`](/docs/api-reference/esims/get-destination) returns one destination in the shape search returns.
- [`GET /v1/esims/catalog`](/docs/api-reference/esims/get-catalog) walks every destination page by page with a cursor. Continue with `nextCursor`, the same filters and the same currency until `nextCursor` is null.
- [`GET /v1/esims/compatible-devices`](/docs/api-reference/esims/get-compatible-devices) lists devices that support eSIM.
Unknown query parameters are rejected with `400 / 10001` (`UNSUPPORTED_FIELD`).
### Quote [#quote]
[`POST /v1/esims/quote`](/docs/api-reference/esims/quote) prices an order body. It has no side effects: nothing is charged or reserved, and a quote does not expire or bind the order. To hold a quoted price, send it as `inputs.maxPrice` in the order.
### Order [#order]
[`POST /v1/esims/order`](/docs/api-reference/esims/create-order) takes the same body as the quote. It needs an `Idempotency-Key` header and an API key with the `manage` permission. The response is the shared order envelope, read later with [`GET /v1/orders/{id}`](/docs/api-reference/orders/get-by-id). See [Idempotency](/docs/idempotency) and [Orders](/docs/orders).
You can also buy eSIMs together with other products through [`POST /v1/orders`](/docs/api-reference/orders/create-order), where each item adds `productType: "esim"`.
## Destinations and offers [#destinations-and-offers]
A destination looks like this (shortened):
```json
{
"id": "destn_k3m7q2t5w4y6b2d4f6h3j5n7pq",
"name": "Europe",
"countryCode": null,
"category": "regional",
"logoUrl": "https://example.com/esims/europe.png",
"description": null,
"offers": [
{
"publicId": "esim_k7m2q4t6v3x5z2b4d6f3h5jn2p",
"name": "Europe 3 GB 7 days",
"description": null,
"price": { "amount": 25.00, "currency": "USD" },
"requiredInputs": [
{
"name": "isInstant",
"type": "boolean",
"required": false,
"description": "Defaults to true, which creates the eSIM when the order is fulfilled. False delivers an entitlement, and the eSIM is created later through provisioning."
}
],
"details": {
"validityDays": 7,
"data": { "amount": 3072, "unit": "MB", "isUnlimited": false, "label": "3 GB" },
"voice": null,
"sms": null,
"apn": { "apn": "internet", "apnUsername": null, "apnPassword": null },
"properties": { "withTopUp": true, "withHotspot": true, "activation": "first-use", "charge": "one-time" },
"restrictions": { "throttle": false, "throttleSpeed": null, "expireInDays": 30 },
"notes": [ "Data only. Calls and SMS are not included." ],
"plan": null
}
}
],
"details": {
"destinationCode": "EU",
"region": "Europe",
"coverage": [
{ "countryCode": "FR", "name": "France", "networks": [ "4G", "5G" ], "carriers": [ "Example Mobile" ] }
]
}
}
```
Things to know:
- `id` is the destination id. `publicId` on an offer is the id you quote and order with. Treat both as opaque. A destination id is never orderable; sent as a `publicId` it gives `400 / 11004`.
- `countryCode` is an ISO 3166-1 alpha-2 code for a local destination and null for a regional or global one. `details.destinationCode` is the destination's own code, such as `FR`, `EU` or `NAM`.
- `price` is indicative. The quote is authoritative.
- `details.data.amount` is in MB. It is null when `isUnlimited` is true or the amount is not known.
- `details.properties.withTopUp` tells you whether the plan can be topped up.
- After a purchase, `GET /v1/esims/destinations/{id}` with the order item's `purchasedProduct.details.destination.id` returns the coverage of the destination the eSIM was bought for.
## Required inputs [#required-inputs]
Each offer lists the `inputs` it takes in `requiredInputs`:
| `name` | `type` | Required | Listed on |
|---|---|---|---|
| `eid` | `text` | yes | Offers that require the device EID. |
| `imei2` | `text` | yes | Offers that require the device's second IMEI. |
| `travelStartDate` | `date` | yes | Offers that require the first day of travel (`YYYY-MM-DD`). A deferred purchase may send it at provisioning instead. |
| `isInstant` | `boolean` | no | Every purchase offer. `true` (the default) creates the eSIM when the order is fulfilled. `false` delivers an entitlement. |
| `iccid` | `text` | yes | Top-up offers only. See [Top-ups](#top-ups). |
A new eSIM without an input its offer lists as required fails with `400 / 10001`, reason `REQUIRED`, at `items[i].inputs.`, before anything is charged. `eid` and `imei2` are needed for a deferred purchase too, because provisioning reuses the values the order recorded. `travelStartDate` is needed on an instant purchase only.
`inputs` also takes the standard `maxPrice` field (below). `requiredInputs` never lists it. `inputs` may be omitted for an offer that needs none.
## Quote and order [#quote-and-order]
Quote and order take the same body:
```json
{
"currency": "USD",
"referenceId": "partner-order-42",
"items": [
{
"publicId": "esim_k7m2q4t6v3x5z2b4d6f3h5jn2p",
"quantity": 1,
"inputs": {
"isInstant": true,
"maxPrice": { "amount": 25, "currency": "USD" }
}
}
]
}
```
```bash
curl -X POST https://api.sandbox.openroam.com/v1/esims/quote \
-H "X-Partner-Key: $OPENROAM_API_KEY" \
-H "Content-Type: application/json" \
-d @esim-order.json
curl -X POST https://api.sandbox.openroam.com/v1/esims/order \
-H "X-Partner-Key: $OPENROAM_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d @esim-order.json
```
The quote response:
```json
{
"currency": "USD",
"items": [
{
"publicId": "esim_k7m2q4t6v3x5z2b4d6f3h5jn2p",
"quantity": 1,
"name": "Europe 3 GB 7 days",
"price": { "amount": 25.00, "currency": "USD" }
}
],
"total": { "amount": 25.00, "currency": "USD" }
}
```
Rules:
- 1 to 5 items, and at most 5 eSIMs in total. A new eSIM accepts a `quantity` above 1, and each eSIM becomes its own order item. A top-up takes `quantity` 1.
- `referenceId` is your own reference. Quote validates it and ignores it.
- `inputs.value` does not exist for eSIM. Sending it, or sending `value` or `maxPrice` beside `inputs`, fails with `400 / 10001` and reason `INVALID_VALUE`.
- `inputs.maxPrice` is `{ amount, currency }`, the highest unit price you accept, in the order currency. A current price above it fails with `409 / 11002` (`PRICE_CHANGED`) at `items[i].inputs.maxPrice`, and nothing is charged. A different currency gives `400 / 10001` (`CURRENCY_MISMATCH`). The amount must be above 0 and use no more decimals than its currency.
- Items are checked one at a time in request order. The first failing item ends the request, and quote and order report the same error for it.
## Top-ups [#top-ups]
A top-up adds a plan to an eSIM you already bought.
1. Call `GET /v1/esims/search?iccid=`. It returns the eSIM's own destination with the offers that can top it up. Each offer lists only `iccid` in `requiredInputs`. The result is empty when no plan can top the eSIM up. With `iccid`, every filter other than `currency` is rejected (`NOT_ALLOWED`).
2. Quote and order that offer with `inputs.iccid`. Read the ICCID from the purchase's `fulfillment.result.details.iccid`.
```json
{
"currency": "USD",
"items": [
{ "publicId": "esim_k7m2q4t6v3x5z2b4d6f3h5jn2p", "quantity": 1, "inputs": { "iccid": "8944501234567890123" } }
]
}
```
`inputs.iccid` is what makes an item a top-up. A top-up offer has the same `publicId` as the plan sold as a new eSIM. The same item without `inputs.iccid` is quoted and ordered as a new eSIM, and no error reports the missing ICCID. Always send `inputs.iccid` with a top-up offer.
Top-up rules:
- `quantity` must be 1, and a top-up is always instant. `isInstant: false` gives `400 / 10001` (`NOT_ALLOWED`) at `items[i].inputs.isInstant`.
- An ICCID that is not 18 to 22 digits gives `400 / 10001` (`INVALID_VALUE`) at `items[i].inputs.iccid`.
- An unknown ICCID, or one that is not yours, gives `404 / 10004`.
- A package that can no longer top up the eSIM, for example because the eSIM was revoked, gives `400 / 10001`.
- On the order item, `purchasedProduct.details.orderType` is `topUp` (or `esim` for a new eSIM), and `fulfillment.result.details.mode` is `topUp`.
## Instant and deferred eSIMs [#instant-and-deferred-esims]
`inputs.isInstant` decides when the eSIM is created.
- **Instant** (the default): fulfillment creates the eSIM. The item becomes `fulfilled` with `mode` `instant`, `provisioning.status` `ready`, the ICCID and the installation details. While delivery is not yet confirmed, the item stays `pending`.
- **Deferred** (`isInstant: false`): fulfillment delivers an entitlement. The item is `fulfilled` with `mode` `deferred`, `provisioning.status` `notStarted`, `canProvision` true, `esimStatus` `new`, and no ICCID or `installation` yet. Create the eSIM later with [`POST /v1/esims/{id}/provisioning`](/docs/api-reference/esims/provision), where `id` is the order item id.
Provisioning a deferred eSIM:
- Send an `Idempotency-Key`. The optional body is `{ "travelStartDate": "2026-12-01" }`.
- It returns the eSIM as `GET /v1/esims/{iccid}/profile` does, and updates the item's result. `provisioning.status` moves to `processing` and then `ready`, and each published change is sent in an `order.fulfillment.updated` webhook.
- Repeating a provisioning that already succeeded, with the same key and body, returns `200` with the provisioned eSIM and provisions nothing again. While the first call is still running, the answer is `409 / 12002` with a `Retry-After` header.
- Only a deferred eSIM can be provisioned. An instant eSIM gives `400 / 10001`. An id that is not one of your eSIM purchases, such as a top-up item, gives `404 / 10004`.
- A plan that requires `travelStartDate` needs it here unless the order sent one (`400 / 10001`). A date different from the recorded one, or a new date after provisioning started, gives `409 / 10005`.
- If provisioning is refused for good, the item becomes `rejected` with `result` null and a `11001` failure, the order reads `fulfillmentFailed` (or `partiallyFulfilled` next to delivered items), and the item is refunded in full automatically.
## The order item [#the-order-item]
An eSIM order item carries `purchasedProduct`, what was bought, and `fulfillment.result`, what was delivered. There is no `value` and no `deliveredValue`.
```json
{
"id": "01a14329-9cc4-73a3-8ca6-22a3efdde687",
"orderId": "01a14329-9cb7-7b0e-9a28-981df5e29f24",
"productType": "esim",
"price": { "amount": 25.00, "currency": "USD" },
"purchasedProduct": {
"name": "Europe 3 GB 7 days",
"countryCode": null,
"logoUrl": "https://example.com/esims/europe.png",
"inputs": { "eid": null, "imei2": null, "iccid": null, "travelStartDate": null, "isInstant": true },
"details": {
"orderType": "esim",
"isInstant": true,
"destination": { "id": "destn_k3m7q2t5w4y6b2d4f6h3j5n7pq", "name": "Europe", "code": "EU" }
}
},
"fulfillment": {
"status": "fulfilled",
"result": {
"details": {
"iccid": "8944501234567890123",
"mode": "instant",
"provisioning": { "status": "ready" },
"canProvision": false,
"esimStatus": "ready",
"profileStatus": "new",
"installation": {
"lpaCode": "LPA:1$smdp.example.com$example-activation-code",
"smdpAddress": "smdp.example.com",
"activationCode": "example-activation-code",
"qrCodeUrl": null,
"iosQuickInstall": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$smdp.example.com$example-activation-code",
"androidQuickInstall": "https://esimsetup.android.com/esim_qrcode_provisioning?carddata=LPA:1$smdp.example.com$example-activation-code"
},
"pin": null,
"puk": null,
"phoneNumber": null,
"data": { "amount": 3072, "unit": "MB", "isUnlimited": false, "label": "3 GB" },
"voice": null,
"sms": null,
"apn": { "apn": "internet", "apnUsername": null, "apnPassword": null },
"addons": [],
"notes": [ "Data only. Calls and SMS are not included." ],
"fulfilledAt": "2026-10-16T05:22:43.59Z"
}
},
"failure": null
},
"actions": {
"amendment": { "availability": "notAvailable", "reason": null },
"cancellation": { "availability": "notAvailable", "reason": null },
"update": { "availability": "notAvailable", "reason": null }
},
"createdAt": "2026-10-16T05:22:43.059969Z",
"effectivePaidAmount": { "amount": 25.00, "currency": "USD" }
}
```
Before fulfillment, the same item has `fulfillment.status` `pending` and `result` null.
`purchasedProduct`:
- `inputs` echoes the item's inputs. `eid`, `imei2` and `iccid` are masked as `***` followed by the last four characters. `travelStartDate` and `isInstant` are returned as applied. An input the item did not take is null, and the price guard is not echoed.
- `details.orderType` is `esim` or `topUp`. `details.destination` is `{ id, name, code }`.
`fulfillment.result.details`:
| Key | Meaning |
|---|---|
| `iccid` | The eSIM's ICCID. It addresses the post-purchase routes and top-ups. Null until the eSIM is provisioned. |
| `mode` | `instant` or `deferred` for a new eSIM, `topUp` for a top-up. |
| `provisioning` | `{ status }`: `notStarted`, `processing`, `ready` or `failed`. |
| `canProvision` | True while a deferred eSIM waits for provisioning. |
| `esimStatus` | `new`, `procuring`, `pending`, `failed`, `ready`, `cancelled`, `revoked`, `expired` or `unknown`. |
| `profileStatus` | The installed profile's state: `empty`, `new`, `downloaded`, `installed`, `activated`, `inactive`, `deleted`, `revoked`, `expired` or `unknown`. |
| `installation` | `lpaCode`, `smdpAddress`, `activationCode`, `qrCodeUrl`, `iosQuickInstall` and `androidQuickInstall`. Null until the eSIM is provisioned. Generate a QR code from `lpaCode` when `qrCodeUrl` is null. |
| `pin`, `puk`, `phoneNumber` | Set when they are issued. |
| `data`, `voice`, `sms`, `apn` | The plan, in the shapes and units of the offer. `voice` and `sms` are null when the plan has none. |
| `addons` | Top-ups applied to the eSIM, as `{ packageName, usage }`. |
| `notes` | The plan's usage notes. |
| `fulfilledAt` | When the eSIM was delivered. |
A top-up item reads the eSIM it topped up, with `mode` `topUp`, and cannot be provisioned.
`GET /v1/orders/{id}` and the `order.fulfillment.updated` webhook ([reference](/docs/api-reference/webhooks/order-fulfillment-updated)) carry the same `result`. See [Orders](/docs/orders) for order and item statuses.
An eSIM cannot be cancelled, amended or updated once delivered. Cancel and its preview answer `422 / 18000`, amendments `422 / 18002`, and update `422 / 18004`. While the eSIM is still pending, cancel answers `409 / 18001`. A rejected eSIM is refunded in full automatically and reported by the `order-item.refunded` webhook.
## After the purchase [#after-the-purchase]
Routes under `/v1/esims/{iccid}/` read one of your eSIMs by ICCID. An ICCID that is not one of your eSIMs gives `404 / 10004`.
| Route | Returns |
|---|---|
| [`GET /v1/esims/{iccid}/profile`](/docs/api-reference/esims/get-esim) | The eSIM: plan, installation details, status, `expiresAt` and the base plan's usage. |
| [`GET /v1/esims/{iccid}/usage`](/docs/api-reference/esims/get-usage) | Current usage, with top-ups added to the plan. |
| [`GET /v1/esims/{iccid}/usage/details`](/docs/api-reference/esims/get-usage-details) | Usage plus a per-day breakdown in `usages`. |
| [`GET /v1/esims/{iccid}/usage/history`](/docs/api-reference/esims/get-usage-history) | Recorded usage readings, paged. |
| [`GET /v1/esims/{iccid}/status-events`](/docs/api-reference/esims/get-status-events) | Status changes over time, paged. |
| [`GET /v1/esims/{iccid}/location-events`](/docs/api-reference/esims/get-location-events) | Network and location events, paged. |
| [`POST /v1/esims/{iccid}/sms`](/docs/api-reference/esims/send-sms) | Sends a text message to the eSIM. Body: `{ "message": "..." }`. |
The three paged event and history routes take `page`, `limit` (1 to 100), `from` and `to` (ISO 8601 UTC).
Usage conventions:
- `start` and `end` are ISO 8601 UTC instants. Amounts use one unit each: `allowedData` and `remainingData` in MB, `allowedSms` and `remainingSms` in messages, `allowedVoice` and `remainingVoice` in whole minutes.
- An amount is null when it is unlimited (the matching `isDataUnlimited`, `isSmsUnlimited` or `isVoiceUnlimited` is then true), not reported or not included. A known allowance that is used up reads `0`.
- In `usage/details`, `date` is the calendar day the usage was counted for (`YYYY-MM-DD`), and it is not always a UTC day. `start` (inclusive) and `end` (exclusive) are the UTC instants that day runs between.
- `profile.expiresAt` is null until the eSIM is activated, then the end of the plan, extended by top-ups.
SMS:
- `200` with `{ "iccid": "..." }` means the message was sent.
- `422 / 22000` means the eSIM's plan cannot send text messages. Do not retry it.
- `502 / 10008` means the message could not be sent.
### Webhooks [#webhooks]
Subscribe to these events to follow an eSIM without polling. See [Webhooks](/docs/webhooks) for signatures, retries and deduplication by `eventId`.
- [`esim.profileStatus.updated`](/docs/api-reference/webhooks/esim-profile-status-updated) is sent when the installed profile's status changes. Its data has `orderId`, `orderItemId`, `iccid`, `start`, `end` and `profileStatus`.
- [`esim.usage.updated`](/docs/api-reference/webhooks/esim-usage-updated) is sent when usage crosses a threshold. A limited plan advances through 25, 50, 75, 90 and 100 percent used. An unlimited plan advances through 14, 7, 3 and 1 days left. Each threshold is sent at most once per eSIM, and a top-up does not reset it.
- [`order.fulfillment.updated`](/docs/api-reference/webhooks/order-fulfillment-updated) carries delivery and each provisioning change of a deferred eSIM.
```json
{
"eventId": "677335a8-e904-ff5c-9186-c9c2690461cd",
"eventType": "esim.usage.updated",
"timestamp": 1792128163,
"data": {
"orderId": "01a14329-9cb7-7b0e-9a28-981df5e29f24",
"orderItemId": "01a14329-9cc4-73a3-8ca6-22a3efdde687",
"iccid": "8944501234567890123",
"start": "2026-10-16T05:30:00Z",
"end": "2026-10-23T05:30:00Z",
"esimStatus": "ready",
"profileStatus": "activated",
"packageName": "Europe 3 GB 7 days",
"allowedData": 3072,
"remainingData": 768,
"isDataUnlimited": false,
"allowedSms": null,
"remainingSms": null,
"isSmsUnlimited": false,
"allowedVoice": null,
"remainingVoice": null,
"isVoiceUnlimited": false
}
}
```
`timestamp` is Unix seconds. Both eSIM events address the eSIM by `orderId`, `orderItemId` and `iccid`.
## Testing in Sandbox [#testing-in-sandbox]
Use [Sandbox](/docs/environments) with your Sandbox key. Authentication, pricing, wallet payment, refunds and webhooks behave as in production. The catalog is synthetic: prices and outcomes are test data, and the install details cannot install a working eSIM.
### Scenarios [#scenarios]
`POST /v1/esims/order` and the shared `POST /v1/orders` accept the `OpenRoam-Sandbox-Scenario` header:
| Value | Result |
|---|---|
| Omitted or `success` | The ordinary successful result. |
| `fulfillment.rejected` | The order is accepted and paid, then fulfillment is rejected. The item is refunded automatically. |
| `fulfillment.pending` | The item stays `pending` without blocking, and becomes eligible for success after about 15 minutes. |
| `fulfillment.late_success` | Pending, then success after about 2 minutes. |
| `fulfillment.late_rejected` | Pending, then rejection after about 2 minutes. |
```bash
curl -X POST https://api.sandbox.openroam.com/v1/esims/order \
-H "X-Partner-Key: $OPENROAM_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "OpenRoam-Sandbox-Scenario: fulfillment.late_success" \
-H "Content-Type: application/json" \
-d @esim-order.json
```
- The scenario is saved with the order and takes part in idempotency. The same key and body replay the order. The same key with a different scenario returns `409`.
- Search, quote and reads take no scenario header. Sending it there, or outside Sandbox, returns `400 / 10001` (`NOT_ALLOWED`). An unknown, empty or repeated value returns `400 / 10001` (`INVALID_VALUE`).
- Timing is approximate and is not a guarantee. A pending item may show `fulfillment.progress` with code `CONFIRMING_OUTCOME`. For an instant eSIM or a top-up, `result` is null until the outcome arrives. A deferred eSIM still delivers its entitlement at checkout, and the timing applies to its later provisioning.
- By default Sandbox fulfillment takes a few seconds, so read the order again before you assume a final state.
### Sandbox catalog [#sandbox-catalog]
The Sandbox catalog has 73 destinations and 587 finite data-only plans: 64 countries, eight regions and a global destination. There are no unlimited, voice or SMS plans. Do not hardcode offer ids: search returns them. These plans cover the input and top-up cases:
| Destination | Data | Validity | Extra inputs | Top-up |
|---|---:|---:|---|---|
| Azerbaijan (`AZ`, local) | 1024 MB | 7 days | none | yes |
| Azerbaijan (`AZ`, local) | 1024 MB | 3 days | `eid` | no |
| Azerbaijan (`AZ`, local) | 2048 MB | 7 days | `imei2` | no |
| Azerbaijan (`AZ`, local) | 3072 MB | 10 days | `travelStartDate` | no |
| Azerbaijan (`AZ`, local) | 5120 MB | 30 days | `eid`, `imei2`, `travelStartDate` | yes |
| Europe (`EU`, regional) | 3072 MB | 7 days | none | yes |
Find them with `GET /v1/esims/search?countryCode=AZ&category=local`, optionally with `validityDays`. For regional coverage use `countryCode=FR&category=regional` and pick the destination whose `details.destinationCode` is `EU`. For global coverage use `countryCode=US&category=global`.
Use synthetic inputs such as `eid` `89049032000000000000000000000001` and `imei2` `490154203237518`. Set `travelStartDate` to tomorrow's UTC date. To test a deferred eSIM with the 3072 MB / 10 day plan, order with `inputs.isInstant: false` and send the date at provisioning.
Sandbox behavior to expect:
- An instant purchase gives each eSIM its own ICCID. `qrCodeUrl` can be null, so generate a QR code from `lpaCode`.
- A top-up adds its validity to the existing eSIM. Top-up search on an eSIM from a plan marked "no" is empty.
- A Sandbox eSIM is never activated and nothing consumes data. Usage shows the plan's allowance plus completed top-ups, `usage.end` and `profile.expiresAt` stay null, and `usage/details` returns no daily events.
- `POST /v1/esims/{iccid}/sms` answers `200` with `{ iccid }` and sends no real message.
## Errors [#errors]
Paths below are for the `items[]` bodies. They are prefixed with `items[i].` on quote, order and the shared order.
| Status / code | When | Path (`reason`) |
|---|---|---|
| `400 / 10001` | A new eSIM is missing an input its offer requires | `inputs.` (`REQUIRED`) |
| `400 / 10001` | `inputs.value`, or `value` or `maxPrice` beside `inputs` | the field path (`INVALID_VALUE`) |
| `400 / 10001` | `inputs.maxPrice` in another currency than the order | `inputs.maxPrice.currency` (`CURRENCY_MISMATCH`) |
| `400 / 10001` | Top-up with `isInstant: false`, or a `quantity` other than 1 | `inputs.isInstant` (`NOT_ALLOWED`), `quantity` (`INVALID_VALUE`) |
| `400 / 10001` | Invalid ICCID | `inputs.iccid` (`INVALID_VALUE`) |
| `400 / 10001` | Unknown query parameter, invalid filter, or a malformed or mismatched catalog cursor | the parameter |
| `400 / 11004` | Unknown, malformed or foreign `publicId`, an item id, or an offer of another product | `items[i]` (`EXPIRED_OR_INVALID`) |
| `409 / 11003` | The offer cannot be sold now | `items[i]` (`UNAVAILABLE`) |
| `409 / 11002` | The current price is above `inputs.maxPrice` | `inputs.maxPrice` (`PRICE_CHANGED`) |
| `404 / 10004` | Unknown or foreign ICCID, unknown destination | none |
| `403 / 10003` | eSIM is not enabled for your account, or the key lacks the `manage` permission | `service` (`SERVICE_NOT_ENABLED`) |
| `422 / 22000` | SMS to an eSIM whose plan cannot send texts | none |
| `502 / 10008` | SMS could not be sent | none |
Check which services are enabled with [`GET /v1/account/services`](/docs/api-reference/account/get-services). Idempotency errors are shared across products; see [Idempotency](/docs/idempotency). For the common error format and the remaining codes, see [Errors](/docs/errors).
## Next steps [#next-steps]
- [Quickstart](/docs/quickstart) for your first order.
- [Authentication](/docs/authentication) and [Environments](/docs/environments) for keys and hosts.
- [Orders](/docs/orders) for order and item status, cancellation and amendments.
- [Webhooks](/docs/webhooks) for signing and retries.
# Flights (/docs/products/flights)
## What you can sell [#what-you-can-sell]
Flight tickets for one-way, return and multi-city trips. You search a trip for a set of passengers, get itineraries with
the fares bookable on each, quote a fare (with optional seats and paid extras such as bags), and book it for named
passengers. Prices are for all passengers together.
This page covers what is specific to flights. Authentication, environments, idempotency, errors, webhooks and the order
envelope are shared by every product:
[Quickstart](/docs/quickstart), [Authentication](/docs/authentication), [Environments](/docs/environments),
[Idempotency](/docs/idempotency), [Errors](/docs/errors), [Webhooks](/docs/webhooks) and [Orders](/docs/orders).
Flights are not available in Sandbox yet. Sandbox supports airtime, eSIM, gift cards, hotels and utility. See
[Testing in Sandbox](#testing-in-sandbox).
The examples on this page send to `$OPENROAM_URL` with `$OPENROAM_API_KEY`: set them to the base URL and key of an
environment where flights are enabled for your account (see [Environments](/docs/environments)). In Production, an
order is a real booking for named passengers, charged to your wallet.
## The flow [#the-flow]
| Step | Route |
|---|---|
| Search itineraries and fares | [`POST /v1/flights/search`](/docs/api-reference/flights/search) |
| Read a fare's seat map (optional) | [`GET /v1/flights/offers/{publicId}/seat-map`](/docs/api-reference/flights/get-seat-map) |
| Quote a fare | [`POST /v1/flights/quote`](/docs/api-reference/flights/quote) |
| Book it | [`POST /v1/flights/order`](/docs/api-reference/flights/create-order) |
Differences from the other products:
- **Search is a POST with a JSON body**, because trips and passengers do not fit a query string. It takes no query
parameters.
- **There is no browse list, one-item route or catalog.** An itinerary exists only in the search response that returned
it. There is also no airport or city lookup: send three-letter IATA airport or city codes.
- **Offers expire.** A fare's `publicId` (`flight_...`) is accepted until `details.expiresAt`. A fare that has already
expired is not listed.
- **Quote returns a new `publicId`** that keeps the quoted price. A quote charges nothing.
- **A price cap protects the order.** See [Price cap at order](#price-cap-at-order).
Every route needs your partner key and flights enabled for your account. Only `order` also needs the `manage`
permission and an `Idempotency-Key` header.
## Search [#search]
```bash
curl -X POST "$OPENROAM_URL/v1/flights/search" \
-H "X-Partner-Key: $OPENROAM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"currency": "USD",
"slices": [
{ "origin": "LHR", "destination": "JFK", "departureDate": "2027-03-12" },
{ "origin": "JFK", "destination": "LHR", "departureDate": "2027-03-19" }
],
"passengers": [ { "type": "adult" }, { "type": "child", "age": 7 } ],
"cabinClass": "economy",
"filters": { "maxStops": 1, "refundableOnly": false, "maxPrice": 1500 },
"page": 1,
"limit": 10
}'
```
| Field | Required | Rules |
|---|---|---|
| `slices` | yes | One per flight of the trip: one for one-way, two for a return, more for multi-city. Each has `origin` and `destination` (IATA airport or city codes) and `departureDate` (`yyyy-MM-dd`, the local date, today or later at the departure airport). |
| `passengers` | yes | One entry per traveller, with at least one `adult`. `type` is `adult`, `child`, `infantWithSeat` or `infantWithoutSeat`. `age` (0 to 17, on the travel date) is required for children and infants. |
| `cabinClass` | no | `economy`, `premiumEconomy`, `business` or `first`. |
| `filters` | no | See below. |
| `page`, `limit` | no | `page` starts at 1 (default 1). `limit` is 1 to 100 (default 10). They page itineraries, not fares. |
| `currency` | no | Three letters. Defaults to your API key's currency. |
Filters:
| Filter | Meaning |
|---|---|
| `maxStops` | At most this many connections in total. Use 0 for direct flights only. |
| `preferredAirlines` | Two-letter IATA airline codes. Keeps itineraries sold, marketed or flown by at least one of them. |
| `excludedAirlines` | Two-letter IATA airline codes. Drops itineraries sold, marketed or flown by any of them. |
| `refundableOnly` | When `true`, keeps only fares whose `details.terms.cancellation.type` is not `nonRefundable`. |
| `maxPrice` | Keeps fares whose price for all passengers is at most this number, in the search currency. |
Every filter you send must match. Every object of the body rejects an unknown member with `400 / 10001` at its JSON
path, for example `$.filters.minPrice`.
### Response [#response]
An item is one itinerary: the same flights sold by the same airline. The fares bookable on it are its `offers`,
cheapest first. Items are ordered by their cheapest fare.
```json
{
"items": [
{
"id": "itin_9f1c2a7d3e4b5c6d7e8f9a0b1c2d3e4f",
"name": "LHR ⇄ JFK · 12–19 Mar · Example Air",
"countryCode": "US",
"category": null,
"logoUrl": "https://cdn.example.com/airlines/EX.png",
"description": null,
"offers": [
{
"publicId": "flight_example1234567890abcdefgh",
"name": "Economy Basic, Non-refundable",
"description": null,
"price": { "amount": 1184.20, "currency": "USD" },
"details": {
"expiresAt": "2027-02-01T10:30:00Z",
"cabinClass": "economy",
"fare": { "fareBasisCode": "OXZ0RO", "brandName": "Basic", "fareFamily": "Economy Basic", "validatingCarrier": "EX" },
"terms": {
"payment": { "type": "payNow", "dueNow": { "amount": 1184.20, "currency": "USD" }, "dueLater": null, "dueLaterAt": null },
"cancellation": { "type": "nonRefundable", "freeUntil": null, "freeUntilLocalTime": null, "timezone": "Europe/London", "schedule": [], "fee": null },
"changes": { "allowed": true, "fee": null }
},
"includedBaggage": [ { "type": "carryOn", "quantity": 1, "weightKg": null, "description": null } ],
"priceBreakdown": { "base": { "amount": 980.00, "currency": "USD" }, "tax": { "amount": 204.20, "currency": "USD" } },
"offerPassengers": [
{ "passengerIndex": 1, "type": "adult", "age": null, "fareType": null, "includedBaggage": [], "availableServices": [] },
{ "passengerIndex": 2, "type": "child", "age": 7, "fareType": null, "includedBaggage": [], "availableServices": [] }
],
"availableServices": [],
"identityDocumentsRequired": true,
"supportedDocumentTypes": ["passport"]
}
}
],
"details": {
"owner": { "iataCode": "EX", "name": "Example Air", "logoUrl": "https://cdn.example.com/airlines/EX.png" },
"slices": [
{
"origin": { "iataCode": "LHR", "name": "Heathrow", "city": "London", "countryCode": "GB", "timezone": "Europe/London" },
"destination": { "iataCode": "JFK", "name": "Kennedy International", "city": "New York", "countryCode": "US", "timezone": "America/New_York" },
"departureAt": "2027-03-12T08:30:00Z", "departureLocalTime": "2027-03-12T08:30:00",
"arrivalAt": "2027-03-12T16:20:00Z", "arrivalLocalTime": "2027-03-12T12:20:00",
"durationMinutes": 470, "stops": 0,
"segments": [ { "marketingFlightNumber": "117", "isCodeshare": false, "...": "..." } ]
}
],
"totalDurationMinutes": 905,
"totalStops": 0,
"totalEmissionsKg": 612
}
}
],
"pagination": { "currentCount": 10, "totalCount": 37, "skip": 0, "limit": 10, "hasMore": true, "page": 1, "totalPages": 4 }
}
```
Points to know:
- The itinerary `id` (`itin_...`) names the itinerary within this response only. It is new on every search and cannot be
ordered: quote, order and the seat map treat it as an unknown offer (`400 / 11004`). Use it only as a UI key.
- Quote and order a fare's `publicId`. It belongs to your partner key and expires at `details.expiresAt`.
- An offer's `name` is the brand after its cabin, followed by its cancellation terms: `, Free cancellation` only for a
`fullyRefundable` fare, `, Non-refundable` for `nonRefundable`, and nothing for `partiallyRefundable`.
- `price` is the indicative price for all passengers in the search currency. The quote confirms it.
- Cabin, baggage and fare basis can differ between fares on the same flights, so they are on each offer. `details.segments`
gives cabin and baggage per segment.
- `identityDocumentsRequired` says whether every passenger needs an identity document for this fare, and
`supportedDocumentTypes` lists the types the airline takes (`passport`, `taxId`, `knownTravelerNumber`,
`passengerRedressNumber`).
- `offerPassengers[].passengerIndex` (from 1) is the position you use for each passenger in the order inputs.
- `availableServices` is empty in search. Quote the fare to list paid extras.
- A fare whose type of cancellation terms is not sold to you is not listed, and quote and order refuse it with
`409 / 11003`.
Each page runs a new search, so itineraries and prices can change between pages. Only the fares on the returned page get a
`publicId`. `items` is empty when no fare matches, when `page` is past the last page, and also when the airline could not
be searched at that moment. All three answer `200`, so search again before telling a customer there is no flight.
### Times and time zones [#times-and-time-zones]
Every flight time (slices, segments and stops) is a UTC instant ending in `Z`. Each airport carries its IANA `timezone`,
and each flight time has the clock of its airport beside it for display: `departureLocalTime` in the origin's zone and
`arrivalLocalTime` in the destination's. A clock is written `yyyy-MM-ddTHH:mm:ss` with no zone. Compute and compare with
the UTC instants. A clock is null when its airport's zone is unknown. In `details.terms.cancellation`, `timezone` is the
zone of the first departure airport, and `freeUntil`, each step's `from` and the matching `...LocalTime` fields follow
the same rule.
## Quote and order [#quote-and-order]
Quote and order take the same body. A quote may leave `inputs` out and then prices the fare alone; an order needs
`inputs` on every item.
```json
{
"currency": "USD",
"referenceId": "partner-trip-7",
"items": [
{
"publicId": "flight_example1234567890abcdefgh",
"quantity": 1,
"inputs": {
"passengers": [
{
"passengerIndex": 1, "title": "mr", "givenName": "Tom", "familyName": "Lee", "gender": "m",
"bornOn": "1988-04-02", "email": "tom@example.com", "phoneNumber": "+447700900123",
"identityDocuments": [ { "type": "passport", "uniqueIdentifier": "000000001", "issuingCountryCode": "GB", "expiresOn": "2031-06-30" } ],
"selectedSeats": [ { "sliceIndex": 1, "segmentIndex": 1, "seatDesignator": "32A" } ]
},
{
"passengerIndex": 2, "title": "ms", "givenName": "Mia", "familyName": "Lee", "gender": "f",
"bornOn": "2019-03-14", "email": "tom@example.com", "phoneNumber": "+447700900123",
"identityDocuments": [ { "type": "passport", "uniqueIdentifier": "000000002", "issuingCountryCode": "GB", "expiresOn": "2030-01-31" } ]
}
],
"selectedServices": [ { "id": "flight_service1234567890abcdefg", "quantity": 1 } ],
"maxPrice": { "amount": 1250.00, "currency": "USD" }
}
}
]
}
```
- `items` holds 1 to 5 items. `quantity` must be 1: an item books one fare for all its passengers.
- `publicId` is a fare's id from search, or one a quote returned (the item's own or a fare option's).
- `currency` defaults to your API key's currency. `referenceId` is your own reference, unique per partner, at most 128
characters.
### Product inputs [#product-inputs]
Positions (`passengerIndex`, `sliceIndex`, `segmentIndex`) are 1-based.
| Input | Required | Meaning |
|---|---|---|
| `passengers` | yes (order) | Every passenger of the fare exactly once, in `passengerIndex` order 1 to N. |
| `passengers[].title` | yes | For example `mr`, `ms` or `mrs`. |
| `passengers[].givenName`, `familyName` | yes | As on the travel document. |
| `passengers[].gender` | yes | `m` or `f`, as on the travel document. |
| `passengers[].bornOn` | yes | Date of birth, `yyyy-MM-dd`. |
| `passengers[].email` | yes | The passenger's email address. |
| `passengers[].phoneNumber` | yes | International format with a leading `+`, for example `+442080160509`. |
| `passengers[].identityDocuments` | when the fare's `identityDocumentsRequired` is `true` | At most one document. When required, every passenger needs a passport. Otherwise a document is optional and of a type in `supportedDocumentTypes`. Each has `type`, `uniqueIdentifier` (the number as printed), `issuingCountryCode` (ISO 3166-1 alpha-2) and `expiresOn`. |
| `passengers[].selectedSeats` | no | Seats from the seat map, at most one per segment: `sliceIndex`, `segmentIndex` and `seatDesignator` (for example `14B`). |
| `selectedServices` | no | Paid extras from the quote item's `details.availableServices`, such as bags. Send the service `id` (or `type` of `baggage` or `meal` with positions), and optionally `passengerIndex`, `sliceIndex`, `segmentIndex` and `quantity` (default 1, at most the service's `maxQuantity`). |
| `maxPrice` | no | The price cap. See below. |
Flights have no monetary value, so `inputs.value` is not accepted. An invalid input gives `400 / 10001` at its path
under `items[i].inputs`, for example `items[0].inputs.passengers[0].email`. Passengers out of `passengerIndex` order give
`400 / 10001` at `items[i].inputs.passengers`.
### The quote response [#the-quote-response]
```json
{
"currency": "USD",
"items": [
{
"publicId": "flight_example2234567890abcdefgh",
"quantity": 1,
"name": "LHR ⇄ JFK · 12–19 Mar · Economy Basic, Non-refundable",
"price": { "amount": 1214.20, "currency": "USD" },
"details": {
"expiresAt": "2027-02-01T10:30:00Z",
"quotedAt": "2027-02-01T10:05:12Z",
"hasSeatMaps": true,
"terms": { "payment": { "...": "..." }, "cancellation": { "...": "..." }, "changes": { "...": "..." } },
"includedBaggage": [ { "type": "carryOn", "quantity": 1, "weightKg": null, "description": null } ],
"priceBreakdown": { "base": { "amount": 980.00, "currency": "USD" }, "tax": { "amount": 204.20, "currency": "USD" } },
"availableServices": [
{
"id": "flight_service1234567890abcdefg", "type": "baggage", "price": { "amount": 30.00, "currency": "USD" },
"passengerIndexes": [1], "segments": [ { "sliceIndex": 1, "segmentIndex": 1 } ], "maxQuantity": 2,
"baggage": { "type": "checked", "maximumWeightKg": 23 }
}
],
"fareOptions": [
{ "publicId": "flight_example3234567890abcdefgh", "name": "Economy Standard", "price": { "amount": 1290.00, "currency": "USD" }, "details": { "...": "the fare's details, as in search" } }
]
}
}
],
"total": { "amount": 1214.20, "currency": "USD" }
}
```
- `price` is what the order charges now for all passengers: the fare with its taxes, plus the paid extras in `inputs`
when you send them. In the example the fare costs 1184.20 USD and the bag 30.00 USD.
- The new `publicId` keeps the fare's price as the cap of an order without `maxPrice`. Order it before `details.expiresAt`.
- `terms` are the terms you are buying, on the item's price.
- `hasSeatMaps` says whether the fare offers seats to choose.
- `availableServices` lists paid extras. A service `id` expires with the item's `publicId`.
- `fareOptions` lists the other fares on the same flights sold by the same airline, cheapest first. Quote or order a
fare option's `publicId` to switch fare.
### Price cap at order [#price-cap-at-order]
`inputs.maxPrice` is `{ amount, currency }`: the highest price you accept for the item, the fare plus its paid extras, in
the order currency. Before payment, the order checks the price again:
- With `maxPrice`, a higher current price gives `409 / 11002` at `items[i].inputs.maxPrice`, on the quote and on the order.
- Without `maxPrice`, an order is capped at the price returned with the `publicId`, by search or quote. A fare that costs
more now gives `409 / 11002` at `items[i]`. Paid extras are charged at their current prices, so an order can add bags
that the price did not include. Send `maxPrice` to cap the extras as well.
- That price is in the currency the `publicId` was returned in, so an order in another currency without `maxPrice` gives
`400 / 11005` at `items[i]`. Search or quote in the order currency, or send `maxPrice`.
- A `maxPrice` in another currency than the order gives `400 / 10001` at `items[i].inputs.maxPrice.currency`
(`CURRENCY_MISMATCH`).
- Nothing is created, charged or booked when these checks refuse an order. A lower price is charged as it is.
A `publicId` keeps the price and currency it was returned with. After `409 / 11002`, quote again and order with the
new `publicId`, or send a `maxPrice` you accept. Ordering the same `publicId` again without `maxPrice` is refused again
while the fare costs more.
### Place the order [#place-the-order]
In Production this books the flight and charges your wallet.
```bash
curl -X POST "$OPENROAM_URL/v1/flights/order" \
-H "X-Partner-Key: $OPENROAM_API_KEY" \
-H "Idempotency-Key: 2f6a9d41-7c3b-4b8e-a1d0-5e9f3c7b2a10" \
-H "Content-Type: application/json" \
-d @order.json
```
Follow the booking with [`GET /v1/orders/{id}`](/docs/api-reference/orders/get-by-id) or the
[`order.fulfillment.updated`](/docs/api-reference/webhooks/order-fulfillment-updated) webhook.
## Seat map [#seat-map]
[`GET /v1/flights/offers/{publicId}/seat-map`](/docs/api-reference/flights/get-seat-map) reads the current seat map of a
fare each time, so seats can change between calls. Use a fare's `publicId` from search or quote. The response is
`{ isSupported, segments, warnings }`.
- A segment is known by its 1-based `sliceIndex` and `segmentIndex` in the itinerary's `details.slices[].segments[]`.
A segment the airline has no seat map for is left out.
- Each seat lists the passengers who can take it in `availableFor`, as `{ passengerIndex, price }`. Prices are in your API
key's currency.
- Send a chosen seat in the order inputs as `passengers[].selectedSeats[]`. The order reads the seat map again and
refuses a seat that is no longer offered to that passenger.
## Booking terms [#booking-terms]
Every fare, quote item and purchased booking states its terms in `details.terms`, with the same shape as hotels:
`{ payment, cancellation, changes }`. Money is in the response currency and includes OpenRoam's fees.
- **Payment.** A flight is always `payNow`: `dueNow` is the price, and `dueLater` is null.
- **Cancellation.** `cancellation.type` comes from the fare's refund rule before departure: `fullyRefundable` (a full refund
until `freeUntil`, the first departure in UTC), `partiallyRefundable` or `nonRefundable`. `schedule` lists
`{ from, fromLocalTime, refund, penalty }` steps from now and from departure. After the first departure, cancelling keeps
everything. `fee` is OpenRoam's cancellation fee, already included in every penalty. A refund that the fare allows
without a stated penalty promises nothing, so it reads `nonRefundable`.
- **Changes.** `changes.allowed` follows the airline's change rule before departure, and `changes.fee` is OpenRoam's fee
per change, or null.
- The terms on a booked item never change afterwards.
## What the order item contains [#what-the-order-item-contains]
Read it with [`GET /v1/order-items/{id}`](/docs/api-reference/order-items/get-by-id) or in `items` of
`GET /v1/orders/{id}`.
```json
{
"id": "019a2b5c-4d7e-7f10-8a2b-3c4d5e6f7081",
"orderId": "019a2b5c-4d6a-7c33-9e15-7f2a8b4c6d10",
"productType": "flight",
"price": { "amount": 1214.20, "currency": "USD" },
"purchasedProduct": {
"name": "LHR ⇄ JFK · 12–19 Mar · Economy Basic, Non-refundable",
"countryCode": "US",
"logoUrl": "https://cdn.example.com/airlines/EX.png",
"inputs": {
"passengers": [
{
"passengerIndex": 1, "title": "mr", "givenName": "Tom", "familyName": "Lee", "gender": "m", "bornOn": "1988-04-02",
"email": "t***@example.com", "phoneNumber": "+44***0123",
"identityDocuments": [ { "type": "passport", "uniqueIdentifier": "***0001", "issuingCountryCode": "GB", "expiresOn": "2031-06-30" } ],
"selectedSeats": [ { "sliceIndex": 1, "segmentIndex": 1, "seatDesignator": "32A" } ]
}
],
"selectedServices": [ { "id": null, "type": "baggage", "passengerIndex": 1, "sliceIndex": 1, "segmentIndex": 1, "quantity": 1 } ]
},
"details": {
"owner": { "iataCode": "EX", "name": "Example Air", "logoUrl": "https://cdn.example.com/airlines/EX.png" },
"slices": [ { "...": "the flights bought, as in search" } ],
"cabinClass": "economy",
"terms": { "payment": { "...": "..." }, "cancellation": { "...": "..." }, "changes": { "...": "..." } },
"includedBaggage": [ { "type": "carryOn", "quantity": 1, "weightKg": null, "description": null } ],
"selectedServices": [ { "type": "baggage", "label": "1 × 23 kg", "passengerIndex": 1, "sliceIndex": 1, "segmentIndex": 1, "quantity": 1 } ],
"priceLines": [
{ "description": "Base fare", "amount": { "amount": 980.00, "currency": "USD" }, "quantity": 1, "serviceType": null, "category": "fare" },
{ "description": "Taxes", "amount": { "amount": 204.20, "currency": "USD" }, "quantity": 1, "serviceType": null, "category": "taxes" },
{ "description": "Checked bag", "amount": { "amount": 30.00, "currency": "USD" }, "quantity": 1, "serviceType": "baggage", "category": "selectedService" }
],
"totalDurationMinutes": 905,
"totalStops": 0
}
},
"fulfillment": {
"status": "fulfilled",
"result": {
"details": {
"bookingStatus": "confirmed",
"ticketDocuments": [ { "type": "electronicTicket", "uniqueIdentifier": "0000000000001" } ],
"booking": { "slices": [], "cabinClass": "economy", "passengers": [], "terms": {}, "includedBaggage": [], "selectedServices": [], "totalDurationMinutes": 905, "totalStops": 0 }
}
},
"failure": null
},
"actions": {
"amendment": { "availability": "available", "reason": null },
"cancellation": { "availability": "available", "reason": null },
"update": { "availability": "notAvailable", "reason": null }
},
"createdAt": "2027-02-01T10:31:07.214Z",
"effectivePaidAmount": { "amount": 1214.20, "currency": "USD" }
}
```
`purchasedProduct` is what was bought and does not change after purchase.
- `inputs` echoes the passengers and extras as applied. Names, titles, gender and date of birth read as sent. `email` and
`phoneNumber` are masked (`t***@example.com`, `+44***0123`). A document's `uniqueIdentifier` is masked to `***` plus
its last four characters. The `maxPrice` cap is not echoed.
- `details` holds the flights as bought (`slices`, with each segment's cabin and baggage), the cabin, the `terms` you
bought, included baggage, the extras bought with a readable `label` such as `1 × 23 kg`, and `priceLines`. The price
lines add up to the item's `price`; if rounding leaves a difference, one extra `Rounding adjustment` line carries it.
`fulfillment.result.details` is the booking's facts:
| Field | Meaning |
|---|---|
| `bookingStatus` | `confirmed`, `pending`, `cancelled` or `failed`. |
| `ticketDocuments` | The ticket documents issued, each `{ type, uniqueIdentifier }`. `type` is `electronicTicket`, `electronicMiscellaneousDocumentAssociated`, `electronicMiscellaneousDocumentStandalone` or `other`, and `uniqueIdentifier` is the document number, for example the e-ticket number. |
| `booking` | What is booked now: `slices`, `cabinClass`, `passengers`, `terms`, `includedBaggage`, `selectedServices`, `totalDurationMinutes` and `totalStops`. |
`booking` reads as the purchased product until a committed amendment changes it; then it has the flights, passengers and
extras booked now. Show "your trip" from `booking`, and what was paid for from `purchasedProduct`. The booking record
keeps no identity documents, so each passenger in `booking` has an empty `identityDocuments`. Changes the airline makes to
the schedule by itself are not processed yet.
The `order.fulfillment.updated` webhook is sent when the item's fulfillment changes. An amendment sends no webhook, so
read the order to see the changed `booking`.
## After purchase [#after-purchase]
These calls are shared by every product; see [Orders](/docs/orders).
- **Cancellation preview.** [`GET /v1/order-items/{id}/cancellation-preview`](/docs/api-reference/order-items/get-cancellation-preview)
returns `penaltyAmount`, `cancellationFee`, `refundAmount`, `isRefundable`, `appliedPenalties` and `checkInDate`
(always null for a flight, which has no check-in), in the order currency. It changes nothing.
- **Cancel.** [`POST /v1/order-items/{id}/cancel`](/docs/api-reference/order-items/cancel) takes
`{ "reason": "requestedByCustomer" }` (or `duplicate` or `fraudulent`), needs the `manage` permission and an
`Idempotency-Key`, and refunds what the fare's rules and OpenRoam's cancellation fee leave. The
[`order-item.refunded`](/docs/api-reference/webhooks/order-item-refunded) webhook reports the refund. A fee that takes
the whole refund still cancels the item with a refund of 0.
- **Fares that cannot be cancelled.** A non-refundable fare that would refund nothing cannot be cancelled: the preview
answers `isRefundable: false` and cancel answers `400 / 10001`. A refundable fare can always be cancelled, even when
nothing comes back. When a cancellation would be refunded as a voucher or airline credit, or its refund has not been
paid yet, both calls answer `400 / 10001` and nothing is cancelled.
- **Airline unavailable.** When the airline cannot answer while pricing a cancellation (an error, a timeout or a rate
limit), the preview, and cancel before any refund exists, answer `503 / 10007`. Nothing is cancelled: retry later.
- **Whole trip.** [`GET /v1/orders/{id}/cancellation-preview`](/docs/api-reference/orders/get-cancellation-preview)
previews every item of an order in one call. A flight that cannot be cancelled is listed as `notCancellable` with the
reason `notAllowed`. If the airline cannot answer, the whole call fails with `503 / 10007`.
- **Amendments.** Changes go through
[`POST /v1/order-items/{id}/amendments/quote`](/docs/api-reference/order-items/quote-amendment) and then
[`POST /v1/order-items/{id}/amendments/confirm`](/docs/api-reference/order-items/confirm-amendment), the same two-step
flow as hotels. The quote returns `amendmentRequestId`, `expiresAt` and `options`, each `{ id, amountToPay, amountToRefund, amendmentFee }`, and nothing is charged until you confirm. OpenRoam's change fee, when the item's terms
have one, is already included in each option's amounts. A committed amendment shows in
`fulfillment.result.details.booking`. List amendments with
[`GET /v1/order-items/{id}/amendments`](/docs/api-reference/order-items/get-amendments).
- **Update.** `POST /v1/order-items/{id}/update` is not supported for flights (`422 / 18004`). Use amendments.
## Testing in Sandbox [#testing-in-sandbox]
Flights are not available in Sandbox yet. Sandbox supports airtime, eSIM, gift cards, hotels and utility, and products
it does not support stay unavailable. The `OpenRoam-Sandbox-Scenario` header (`success`, `fulfillment.rejected`,
`fulfillment.pending`, `fulfillment.late_success` and `fulfillment.late_rejected`) works only on the order endpoints of
those products, not on flights. Build and test your flight integration against the request and response shapes on this
page, and use [Environments](/docs/environments) to see what each environment covers.
## Errors to handle [#errors-to-handle]
Shared error handling is in [Errors](/docs/errors). Flight specific cases:
| Status / code | Reason | Path | When and what to do |
|---|---|---|---|
| `400 / 10001` | `INVALID_VALUE` | the field, for example `slices[0].departureDate` | An invalid search field: no slice, an origin or destination that is not three letters, a past departure date, no adult, a child or infant without an age from 0 to 17, `limit` outside 1 to 100. |
| `400 / 10001` | `INVALID_VALUE` | the JSON path | An unknown member anywhere in the body, such as `$.maxResults` or `$.items[0].inputs.value`. |
| `400 / 10001` | `UNSUPPORTED_FIELD` | the parameter | A query parameter on search. |
| `400 / 10001` | `REQUIRED` | `items[i].inputs` | An order item without `inputs`. |
| `400 / 10001` | various | `items[i].inputs...` | An invalid passenger, document, seat or service input, at its path. |
| `400 / 10001` | `NOT_SUPPORTED` | `currency` | A currency OpenRoam does not support. |
| `400 / 11004` | `EXPIRED_OR_INVALID` | `items[i]` | An unknown, expired or foreign `publicId`, an itinerary `id` (`itin_...`), a service `id`, another product's offer, or a `publicId` that keeps no price. Search or quote again. On the seat map the error has no `details`. |
| `409 / 11002` | `PRICE_CHANGED` | `items[i].inputs.maxPrice` or `items[i]` | The price is above your `maxPrice`, or above the price returned with the `publicId`. Quote again, or send a `maxPrice` you accept. |
| `400 / 11005` | `CURRENCY_MISMATCH` | `items[i]` | An order without `maxPrice` in another currency than the price returned with the `publicId`. |
| `409 / 11003` | `UNAVAILABLE` | `items[i]` | The airline no longer sells the offer. |
| `400 / 10001` | none | none | Any other airline failure while pricing the fare. |
| `403 / 10003` | `SERVICE_NOT_ENABLED` | `service` | Flights are not enabled for your account. |
| `503 / 10007` | none | none | The airline cannot answer a cancellation preview or cancel. Retry later. |
| `409 / 18003` | `IN_PROGRESS` or `NOT_AVAILABLE` | `id` | An amendment cannot be quoted or confirmed now. |
| `422 / 18004` | none | none | `update` is not supported for flights. |
A failing request orders and charges nothing.
# Gift cards (/docs/products/gift-cards)
## What you can sell [#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](/docs/quickstart), [Authentication](/docs/authentication), [Environments](/docs/environments),
[Idempotency](/docs/idempotency), [Errors](/docs/errors), [Webhooks](/docs/webhooks) and [Orders](/docs/orders).
## The flow [#the-flow]
### Browse the catalog [#browse-the-catalog]
| Route | Use it to |
|---|---|
| [`GET /v1/giftcards/search`](/docs/api-reference/gift-cards/search) | List cards with their offers, one page at a time. |
| [`GET /v1/giftcards/cards/{id}`](/docs/api-reference/gift-cards/get-card) | Read one card by its `card_...` id. It returns the same item that search returns. |
| [`GET /v1/giftcards/catalog`](/docs/api-reference/gift-cards/get-catalog) | Walk every card in id order with a cursor, for example to build your own copy of the catalog. |
| [`GET /v1/giftcards/categories`](/docs/api-reference/gift-cards/get-categories) | Read the category list (`shopping`, `foodAndDining`, `entertainment`, `gaming`, `travel`, `paymentCards`, `softwareAndDigital`, `other`) with display names. |
### Quote [#quote]
[`POST /v1/giftcards/quote`](/docs/api-reference/gift-cards/quote) prices the items of an order body. It has no side
effects: nothing is reserved and nothing expires.
### Order [#order]
[`POST /v1/giftcards/order`](/docs/api-reference/gift-cards/create-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 [#read-the-result]
Follow the order with [`GET /v1/orders/{id}`](/docs/api-reference/orders/get-by-id) or the
[`order.fulfillment.updated`](/docs/api-reference/webhooks/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 [#search-and-read-cards]
```bash
curl "https://api.sandbox.openroam.com/v1/giftcards/search?countryCode=US&limit=10" \
-H "X-Partner-Key: $OPENROAM_API_KEY"
```
```json
{
"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:
| 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]
Quote and order take the same body.
```json
{
"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 [#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 [#the-quote-response]
```json
{
"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 [#place-the-order]
```bash
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 [#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`.
```json
{
"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 [#what-the-order-item-contains]
Read an item with [`GET /v1/order-items/{id}`](/docs/api-reference/order-items/get-by-id), or as one entry of
`items` in [`GET /v1/orders/{id}`](/docs/api-reference/orders/get-by-id).
```json
{
"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 [#after-purchase]
Gift cards use the shared order-item routes, described in [Orders](/docs/orders).
- **Change the gift recipient.** [`POST /v1/order-items/{id}/update`](/docs/api-reference/order-items/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](/docs/api-reference/order-items/cancel)
and its [preview](/docs/api-reference/order-items/get-cancellation-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`](/docs/api-reference/webhooks/order-item-refunded) webhook reports it. Cancelling with the
reason `fulfillmentFailed` returns that refund.
## Testing in Sandbox [#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](/docs/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 / 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.
| 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 [#errors-to-handle]
Shared error handling is in [Errors](/docs/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.` | 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.
# Hotels (/docs/products/hotels)
## What you can sell [#what-you-can-sell]
Hotel stays, booked and paid in advance. You search a place (or a list of hotels) for dates, rooms and a guest market,
pick a rate, quote it, and book it in the name of a lead guest. Every price you see is for the whole stay: all rooms
and all nights.
This page covers what is specific to hotels. Authentication, environments, idempotency, errors, webhooks and the
order envelope are shared by every product:
[Quickstart](/docs/quickstart), [Authentication](/docs/authentication), [Environments](/docs/environments),
[Idempotency](/docs/idempotency), [Errors](/docs/errors), [Webhooks](/docs/webhooks) and [Orders](/docs/orders).
## The flow [#the-flow]
| Step | Route |
|---|---|
| Find a place by name (optional) | [`GET /v1/hotels/destinations`](/docs/api-reference/hotels/get-destinations) |
| Search hotels and their offers | [`POST /v1/hotels/search`](/docs/api-reference/hotels/search) |
| Read one hotel's content (optional) | [`GET /v1/hotels/properties/{id}`](/docs/api-reference/hotels/get-property) |
| Quote a rate | [`POST /v1/hotels/quote`](/docs/api-reference/hotels/quote) |
| Book it | [`POST /v1/hotels/order`](/docs/api-reference/hotels/create-order) |
Reference data routes:
- [`GET /v1/hotels/amenities/catalog`](/docs/api-reference/hotels/get-amenity-catalog) lists every amenity code and
group with a label, to label `details.amenityGroups` and to fill the `amenityCodes` filter. Labels follow the
`Accept-Language` header.
- [`GET /v1/hotels/catalog/files`](/docs/api-reference/hotels/get-catalog-files) links downloadable files of the whole
hotel catalog, so you can build hotel pages up front. The files hold content only, never prices.
Four things work differently from the other products:
- **Search is a POST with a JSON body.** Rooms with child ages do not fit a query string. It is the one route that
does not browse with GET.
- **Offers expire.** An offer's `publicId` (`rate_...`) is accepted until `details.expiresAt`, at most 30 minutes after
the search.
- **Quote returns a new `publicId`.** It prices the rate again and returns a fresh `publicId` at the quoted price. A
quote reserves nothing and charges nothing.
- **A price cap protects the order.** See [Price cap at order](#price-cap-at-order).
Every route needs your partner key and hotels enabled for your account. Only `order` also needs the `manage`
permission and an `Idempotency-Key` header.
## Search [#search]
```bash
curl -X POST https://api.sandbox.openroam.com/v1/hotels/search \
-H "X-Partner-Key: $OPENROAM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"searchCriteria": { "location": { "cityCode": "DXB" } },
"checkIn": "2027-03-10",
"checkOut": "2027-03-13",
"rooms": [ { "adults": 2, "children": 1, "childrenAges": [7] } ],
"guestNationality": "GB",
"currency": "USD",
"filters": { "minStarRating": 4, "boardTypes": ["breakfast"], "maxPrice": 900 },
"limit": 20
}'
```
| Field | Required | Rules |
|---|---|---|
| `searchCriteria` | yes | `location` or `hotelIds`. A non-empty `hotelIds` wins and `location` is then ignored. |
| `searchCriteria.location` | one of the two | An area by `geoNodeId` (an id from the destinations route), `cityCode` (three characters) or `coordinates` with `radiusKm`. When several are sent, `geoNodeId` wins over `cityCode`, and `cityCode` over `coordinates`. |
| `searchCriteria.hotelIds` | one of the two | Up to 50 hotel ids (`hotel_...`) from an earlier search. Returns every rate of those hotels with the full detail, as one page. |
| `checkIn`, `checkOut` | yes | Dates (`yyyy-MM-dd`). `checkIn` is today or later in the hotel's time zone, and `checkOut` is after it and at most 30 nights later. |
| `rooms` | yes | 1 to 9 rooms. Each has `adults` (1 to 9, default 2), `children` (0 to 9) and, when `children` is above 0, exactly one age (0 to 17) per child in `childrenAges`. A room is matched by its 1-based position when you order. |
| `guestNationality` | yes | ISO 3166-1 alpha-2, for example `GB`. Rates are priced for this market. |
| `guestCountryOfResidence` | no | ISO 3166-1 alpha-2. Defaults to `guestNationality`. |
| `currency` | no | Three letters. Defaults to your API key's currency. |
| `filters` | no | `minStarRating`, `maxStarRating`, `minPrice`, `maxPrice` (for the whole stay), `boardTypes`, `amenityCodes` and `cancellationTypes`. No other member is accepted. |
| `cursor`, `limit` | no | Location searches only. `limit` is 1 to 50 (default 20). |
Coordinates search uses `radiusKm` from 1 to 150 km. There is no free-text name search on this route: use
[`GET /v1/hotels/destinations?q=`](/docs/api-reference/hotels/get-destinations) to turn a name into a `geoNodeId`.
Place ids are stable, so resolve one once and keep it. Every object of the body rejects an unknown member with
`400 / 10001` at its JSON path.
Filter details:
- `boardTypes` takes `roomOnly`, `breakfast`, `halfBoard`, `fullBoard` or `allInclusive`.
- `cancellationTypes` takes `fullyRefundable`, `partiallyRefundable` or `nonRefundable`, matched against the offer's
`details.terms.cancellation.type`. It is judged on the terms stated now: a free window that has already closed does
not count.
- `amenityCodes` takes codes from the amenity catalog. A hotel must have all of them.
### Paging [#paging]
A location search returns hotels with a cursor. Send the response's `nextCursor` back as `cursor`, with the same body,
until it is null. A page can hold fewer hotels than `limit`, even none, while `nextCursor` is still set, because hotels
without an orderable offer are left out: keep paging until `nextCursor` is null. A search with `hotelIds` is one
complete page.
### Location search and `hotelIds` search [#location-search-and-hotelids-search]
A location search keeps pages small: each hotel has one offer (its cheapest rate that matches), offers have empty
`nightlyPrices` and `surcharges`, and a hotel has no `description` and at most one image. To see every rate of a hotel
with the full detail, search again with that hotel's `id` in `searchCriteria.hotelIds`, using the same stay, rooms,
market and currency.
A hotel `id` from the OpenRoam catalog is stable. A hotel outside the catalog gets a temporary id that stops working
after 30 minutes, so do not store it.
### Response [#response]
```json
{
"items": [
{
"id": "hotel_example1234567890abcdefgh",
"name": "Hotel Example",
"countryCode": "AE",
"category": null,
"logoUrl": "https://cdn.example.com/hotel.jpg",
"description": "A hotel near the water.
",
"offers": [
{
"publicId": "rate_example1234567890abcdefgh",
"name": "Deluxe King, Breakfast, Free cancellation",
"description": null,
"price": { "amount": 642.10, "currency": "USD" },
"details": {
"expiresAt": "2027-02-01T10:30:00Z",
"rooms": [
{
"roomIndex": 1, "roomGroupKey": "4c8e3ae1d379f759bc372243", "name": "Deluxe King",
"description": null, "beds": [], "maxOccupancy": 3, "sizeSquareMeters": null,
"amenities": [], "imageUrls": [],
"adultsCount": 2, "childrenCount": 1, "childrenAges": [7]
}
],
"board": { "code": "BB", "name": "Bed and breakfast", "boardType": "breakfast" },
"terms": {
"payment": { "type": "payNow", "dueNow": { "amount": 642.10, "currency": "USD" }, "dueLater": null, "dueLaterAt": null },
"cancellation": {
"type": "fullyRefundable",
"freeUntil": "2027-03-08T20:00:00Z",
"freeUntilLocalTime": "2027-03-09T00:00:00",
"timezone": "Asia/Dubai",
"schedule": [
{
"from": "2027-03-08T20:00:00Z", "fromLocalTime": "2027-03-09T00:00:00",
"refund": { "amount": 0.00, "currency": "USD" }, "penalty": { "amount": 642.10, "currency": "USD" }
}
],
"fee": null
},
"changes": { "allowed": true, "fee": null }
},
"taxes": { "included": true, "totalTaxAmount": 41.20, "items": [] },
"priceIsBinding": true,
"nightlyPrices": [],
"surcharges": [],
"rateTags": [],
"remarks": [],
"withTransfers": false,
"rateRules": [],
"amendabilityStatus": "yes",
"guestNameRules": { "minLength": 2, "maxLength": 50, "pattern": "^[A-Za-z' -]+$", "allowedCharacters": "Letters, spaces, apostrophes and hyphens", "distinctFullNames": false }
}
}
],
"details": {
"starRating": 5,
"address": { "line1": "1 Example Street", "line2": null, "city": "Dubai", "stateProvince": null, "postalCode": null, "countryCode": "AE", "countryName": null },
"coordinates": { "latitude": 25.2, "longitude": 55.3 },
"imageUrls": ["https://cdn.example.com/hotel-1.jpg"],
"amenityGroups": [ { "key": "PropertyAmenities", "codes": ["FreeWifi", "Pool"] } ],
"contact": null,
"displayGroup": null
}
}
],
"pagination": { "currentCount": 1, "limit": 20, "hasMore": false },
"nextCursor": null,
"details": { "availableFilters": null }
}
```
The offer fields partners use most:
| Field | Meaning |
|---|---|
| `publicId` | The offer id you quote and order with, until `details.expiresAt`. It names the rate, not the hotel. |
| `price` | The price of the whole stay in the search currency, with your pricing rules applied. It is indicative: quote and order price the rate again. |
| `details.rooms` | One room per searched room, with `roomGroupKey`, which is equal for every rate of the same physical room. |
| `details.board` | `code` (`RO`, `BB`, `HB`, `FB`, `AI` or `OTHER`) and `boardType` (`roomOnly`, `breakfast`, `halfBoard`, `fullBoard`, `allInclusive` or `unknown`). |
| `details.terms` | The [booking terms](#booking-terms): payment, cancellation and changes. |
| `details.taxes` | Taxes already included in `price`. |
| `details.surcharges` | Fees outside the room rate. See [Surcharges](#surcharges). |
| `details.minimumSellingPrice` | When present, the lowest price at which you may resell the stay. See below. |
| `details.amendabilityStatus` | `yes`, `no` or `unknown`: whether the booking can be amended. |
| `details.guestNameRules` | What the booking accepts as a first and last name, so your form can validate before ordering. |
| `details.allowsSpecialRequests`, `details.specialRequestOptions` | When stated, whether requests are accepted and the `{ code, name }` options to send as `specialRequestCodes`. |
A rate that OpenRoam does not sell to you is not listed. Rates that are paid at the property or that need a deposit
are not sold at the moment: they are left out of search and refused at quote and order with `409 / 11003`.
**Minimum selling price.** When `details.minimumSellingPrice` is set, you must not sell the stay to the traveller below
that amount. It covers the whole stay and is separate from `price`. A null value means no minimum can be stated, not
that you may ignore a retail restriction. The quote returns the refreshed amount at
`items[].details.rate.minimumSellingPrice`, so check it again before you sell.
## Quote and order [#quote-and-order]
Quote and order take the same body. A quote may leave `inputs` out; an order needs them.
```json
{
"currency": "USD",
"referenceId": "partner-booking-42",
"items": [
{
"publicId": "rate_example1234567890abcdefgh",
"quantity": 1,
"inputs": {
"holder": { "title": "Ms", "firstName": "Ana", "lastName": "Garcia", "email": "ana@example.com", "phone": "+34600123456" },
"roomGuests": [
{
"roomIndex": 1,
"guests": [
{ "title": "Ms", "firstName": "Ana", "lastName": "Garcia", "age": 34 },
{ "title": "Mr", "firstName": "Luis", "lastName": "Garcia", "age": 36 },
{ "title": "Miss", "firstName": "Sofia", "lastName": "Garcia", "age": 7 }
]
}
],
"specialRequests": "Late arrival",
"maxPrice": { "amount": 650.00, "currency": "USD" }
}
}
]
}
```
- `items` holds 1 to 5 items. `quantity` must be 1: an item books one rate, which covers every searched room. Book
another rate as another item.
- `publicId` is an offer's id from search, or the newer one a quote returned. A hotel's own `id` is not an offer.
- The stay dates, rooms and child ages come from the offer, so you do not send them.
- `currency` defaults to your API key's currency. An order must be in the currency the offer was priced in.
- `referenceId` is your own reference, unique per partner, at most 128 characters.
### Inputs [#inputs]
Every hotel offer takes the same inputs, so offers do not list `requiredInputs`.
| Input | Required | Meaning |
|---|---|---|
| `holder` | yes | The lead guest. The booking is made in this name and the hotel contacts this person: `title` (optional), `firstName`, `lastName`, `email` (up to 100 characters) and `phone` (international format with a leading `+`, for example `+14155552671`). |
| `roomGuests` | yes | One entry per searched room: `roomIndex` (1-based, each room once) and `guests`, every adult and child in the room. |
| `specialRequests` | no | Free text, at most 500 characters, for rates without a code list. The hotel may not honour it. |
| `specialRequestCodes` | no | Up to 32 distinct codes from the rate's `specialRequestOptions`, applied to every room. |
| `maxPrice` | no | The price cap. See below. |
A guest has `title` (`Mr`, `Mrs`, `Ms`, `Miss` or `Dr`), `firstName`, `lastName`, optional `middleName`, `age`,
`nationality` and `countryOfResidence`. A guest aged 18 or more, or sent without an age, is an adult; a guest aged 0 to
17 is a child. Each room's guests must match its searched adults and children with the same child ages, in any order.
Names must follow the offer's `details.guestNameRules`. Some rates require `nationality` and `countryOfResidence` to
match the market the rate was priced for.
Hotel stays have no monetary value, so `inputs.value` is not accepted.
### The quote response [#the-quote-response]
```json
{
"currency": "USD",
"items": [
{
"publicId": "rate_example2234567890abcdefgh",
"quantity": 1,
"name": "Hotel Example · Deluxe King, Breakfast, Free cancellation",
"price": { "amount": 648.90, "currency": "USD" },
"details": {
"expiresAt": "2027-02-01T10:42:00Z",
"availability": "confirmed",
"checkInDate": "2027-03-10",
"checkOutDate": "2027-03-13",
"requestedRooms": [ { "adults": 2, "children": 1, "childrenAges": [7] } ],
"terms": { "payment": { "...": "..." }, "cancellation": { "...": "..." }, "changes": { "...": "..." } },
"rate": { "rooms": [], "board": {}, "taxes": {}, "surcharges": [], "rateConditions": [], "...": "..." }
}
}
],
"total": { "amount": 648.90, "currency": "USD" }
}
```
- `publicId` is a new offer id for the rate at the quoted `price`. It is accepted until `details.expiresAt`, at most 30
minutes after the quote. The id you quoted keeps the price it was returned with.
- `details.availability` is `confirmed` when the rate can be booked now, or `onRequest` when it can only be held on
request. An order refuses an `onRequest` rate with `409 / 11003`.
- `details.terms` are the terms you are buying, stated at the time of the quote on the quoted `price`.
- `details.rate` holds the rate in detail. Its `surcharges` list is the binding one.
- If the rate is no longer sold, the quote answers `409 / 11003`.
### Price cap at order [#price-cap-at-order]
Before any money moves, the order prices each rate again and caps the fresh price:
| Item | Quote | Order |
|---|---|---|
| With `inputs.maxPrice` | A fresh price above `maxPrice` gives `409 / 11002` and no `publicId`. | The same. At or below `maxPrice`, the rate is charged at its fresh price. |
| Without `inputs.maxPrice` | `200` with the fresh price and a new `publicId`. | A fresh price above the one returned with the `publicId` gives `409 / 11002` at `items[i]`. |
`maxPrice` is `{ amount, currency }` in the order currency. A `maxPrice` above the price you were shown accepts a rise
up to it, and one below it refuses even that price. After a refusal, quote again and order the new `publicId`, or order
again with a `maxPrice` you accept. A refused order creates and charges nothing.
### Held rate [#held-rate]
Where a rate can be held, the order holds it before charging. If you order a `publicId` that a quote returned and the
cancellation terms on the hold are stricter than the quote's (a larger share kept, or kept from an earlier instant),
the order fails with `409 / 11006` and the reason `TERMS_CHANGED` at `items[i]` before any money moves. Quote the rate
again, check its terms, and order the new `publicId`. Terms that only moved on with the clock, such as a `freeUntil` that
has passed, are not a change.
### Place the order [#place-the-order]
```bash
curl -X POST https://api.sandbox.openroam.com/v1/hotels/order \
-H "X-Partner-Key: $OPENROAM_API_KEY" \
-H "Idempotency-Key: 8c3f6a1e-2b7d-4e55-9b0a-1d2c3e4f5a60" \
-H "Content-Type: application/json" \
-d @order.json
```
The booking completes after payment. Follow it with [`GET /v1/orders/{id}`](/docs/api-reference/orders/get-by-id) or
the [`order.fulfillment.updated`](/docs/api-reference/webhooks/order-fulfillment-updated) webhook.
## Booking terms [#booking-terms]
Every offer, quote item and purchased booking states its terms in `details.terms`, with the same shape for hotels and
flights: `{ payment, cancellation, changes }`. Money is `{ amount, currency }` in the response currency, with
OpenRoam's fees already included.
- **Payment.** `payment.type` is `payNow` for every hotel rate sold today: `dueNow` is the price, and `dueLater` and
`dueLaterAt` are null.
- **Cancellation.** `cancellation.type` is `fullyRefundable` (a full refund until `freeUntil`), `partiallyRefundable`
(a share is always kept, for example because a fee applies) or `nonRefundable`. `schedule` lists steps, each
`{ from, fromLocalTime, refund, penalty }`: cancelling at or after `from`, and before the next step, gives back
`refund` and keeps `penalty`. `fee` is OpenRoam's cancellation fee, or null; it is already included in every penalty
and turns a free window into a `partiallyRefundable` one.
- **Changes.** `changes.allowed` says whether the booking can be amended, and `changes.fee` is OpenRoam's fee per
change, or null.
- The offer's `name` follows the cancellation type: `Free cancellation` only for `fullyRefundable`, `Non-refundable`
for `nonRefundable`, and no terms part for `partiallyRefundable`.
- The terms on a booked item never change afterwards, not even when the free window closes. Ask the cancellation
preview what cancelling costs now.
### Times and time zones [#times-and-time-zones]
Every instant (`freeUntil`, each step's `from`, `expiresAt`) is a UTC instant ending in `Z`. A hotel states its
deadlines on its own clock, and OpenRoam converts them with the hotel's time zone. For display, `cancellation.timezone`
is the hotel's IANA time zone (for example `Europe/Madrid`), and `freeUntilLocalTime` and each step's `fromLocalTime`
are the same instants on the hotel's clock, written `yyyy-MM-ddTHH:mm:ss` with no zone. Those clocks are for display
only: compute and compare with the UTC instants. When the time zone is not known, `timezone` and every clock are null,
and the UTC deadlines are chosen so a free window never ends later than the hotel's own deadline. A charge that applies
whatever the date has `from` set to `0001-01-01T00:00:00Z` and a null clock.
### Surcharges [#surcharges]
`details.surcharges` lists fees outside the room rate, such as a city tax, a resort fee or a deposit. Each entry is
`{ type, description, price, approxPrice, includedInTotal, payableAt }`.
- Never add a surcharge to the offer's `price`. With `includedInTotal: false` the fee is not money OpenRoam charges, and
with `true` it is already in the price. Most are paid by the guest at the hotel (`payableAt: property`).
- `price` is in the property's currency and is never converted. `approxPrice` is an estimate in your currency, and is
null when it could not be converted: show `price` then, and label `approxPrice` as approximate.
- Show one line per entry. Two rooms with the same deposit mean the guest owes it twice.
- An empty list does not mean the hotel charges nothing: a location search leaves it empty, and the quote returns the
binding list. Nothing says whether a fee is refundable, so do not promise money back.
## What the order item contains [#what-the-order-item-contains]
Read it with [`GET /v1/order-items/{id}`](/docs/api-reference/order-items/get-by-id) or in `items` of
`GET /v1/orders/{id}`.
```json
{
"id": "019a2b5c-4d7e-7f10-8a2b-3c4d5e6f7081",
"orderId": "019a2b5c-4d6a-7c33-9e15-7f2a8b4c6d10",
"productType": "hotel",
"price": { "amount": 642.10, "currency": "USD" },
"purchasedProduct": {
"name": "Hotel Example · Deluxe King, Breakfast, Free cancellation",
"countryCode": "AE",
"logoUrl": "https://cdn.example.com/hotel.jpg",
"inputs": {
"holder": { "title": "Ms", "firstName": "Ana", "lastName": "Garcia", "email": "a***@example.com", "phone": "+34***3456" },
"roomGuests": [ { "roomIndex": 1, "guests": [ { "title": "Ms", "firstName": "Ana", "lastName": "Garcia", "middleName": null, "age": 34, "nationality": null, "countryOfResidence": null } ] } ],
"specialRequests": "Late arrival"
},
"details": {
"checkInDate": "2027-03-10",
"checkOutDate": "2027-03-13",
"requestedRooms": [ { "adults": 2, "children": 1, "childrenAges": [7] } ],
"hotel": { "name": "Hotel Example", "starRating": 5, "address": { "...": "..." }, "coordinates": { "...": "..." }, "description": "...
", "imageUrls": [], "amenityGroups": [], "contact": null },
"terms": { "payment": { "...": "..." }, "cancellation": { "...": "..." }, "changes": { "...": "..." } },
"rate": { "rooms": [], "board": {}, "taxes": {}, "nightlyPrices": [], "surcharges": [], "amendabilityStatus": "yes", "...": "..." }
}
},
"fulfillment": {
"status": "fulfilled",
"result": {
"details": {
"bookingStatus": "confirmed",
"hotelConfirmationNumber": "1234-ABC",
"amendmentComposition": {
"guests": { "addMore": false, "remove": false, "guestType": false, "names": true, "ages": true },
"rooms": { "addMore": false, "remove": false },
"dates": { "change": true },
"holder": { "change": true }
},
"booking": {
"checkInDate": "2027-03-10",
"checkOutDate": "2027-03-13",
"holder": { "title": "Ms", "firstName": "Ana", "lastName": "Garcia", "email": "a***@example.com", "phone": "+34***3456" },
"roomGuests": [ { "roomIndex": 1, "guests": [ "..." ] } ]
}
}
},
"failure": null
},
"actions": {
"amendment": { "availability": "available", "reason": null },
"cancellation": { "availability": "available", "reason": null },
"update": { "availability": "notAvailable", "reason": null }
},
"createdAt": "2027-02-01T10:31:07.214Z",
"effectivePaidAmount": { "amount": 642.10, "currency": "USD" }
}
```
`purchasedProduct` is the stay as bought and never changes after purchase.
- `inputs` echoes the holder, `roomGuests` and `specialRequests`. Names, titles, ages, nationalities and countries of
residence are returned as sent, so you can service the booking. The holder's `email` and `phone` are masked (for
example `a***@example.com` and `+34***3456`): show them as returned and do not use them as contact details. The
`maxPrice` cap is not echoed.
- `details` holds the stay dates, `requestedRooms`, the `hotel` content as stored with the purchase, the `terms` you
bought and the `rate` (rooms, board, taxes, nightly prices, surcharges and so on). `rate.surcharges[].approxPrice`
is derived again on every read in the order currency, so it moves with exchange rates.
`fulfillment.result.details` is the booking's facts:
| Field | Meaning |
|---|---|
| `bookingStatus` | `confirmed`, `pending`, `onRequest`, `cancelled` or `failed`. |
| `hotelConfirmationNumber` | The hotel's own confirmation number, the one the guest gives at the front desk. Null until the hotel issues one, and it can arrive after the item is `fulfilled`. |
| `amendmentComposition` | What an amendment may change about the booking: guests, rooms, dates and holder. It is decided per booking. When OpenRoam cannot tell, every value is `false`. |
| `booking` | The stay as booked now, always filled: `checkInDate`, `checkOutDate`, `holder` and `roomGuests`. It reads as the stay bought until an amendment changes it. Show the stay from `booking`. |
A hotel confirmation number that arrives after fulfillment creates a new `fulfillmentVersion`, and an
`order.fulfillment.updated` webhook carries the number, once per new number. An amendment changes what a read returns
without sending that webhook, so read the order again after an amendment.
## After purchase [#after-purchase]
These calls are shared by every product; see [Orders](/docs/orders).
### Cancel [#cancel]
1. [`GET /v1/order-items/{id}/cancellation-preview`](/docs/api-reference/order-items/get-cancellation-preview) shows what
cancelling now costs. It changes nothing and returns `penaltyAmount`, `cancellationFee`, `refundAmount`,
`isRefundable`, `appliedPenalties`, `effectiveCancellationDate` and `checkInDate`. Amounts are measured on what was
paid for the item (amendments included), in the order currency. `isRefundable: false` means the penalty alone keeps
everything that was paid.
2. [`POST /v1/order-items/{id}/cancel`](/docs/api-reference/order-items/cancel) cancels the booking and refunds what the
penalty and any cancellation fee leave. The body is `{ "reason": "requestedByCustomer" }` (or `duplicate` or
`fraudulent`), and it needs the `manage` permission and an `Idempotency-Key`. The money goes back to the wallet that
paid, and the [`order-item.refunded`](/docs/api-reference/webhooks/order-item-refunded) webhook reports it.
A booking whose penalty keeps everything that was paid is not cancelled: cancel answers `400 / 10001`, and
`actions.cancellation.availability` is `notAvailable`. The preview and the refund price the cancellation again with the
band in effect at that moment, so the amount can differ from an earlier preview.
To preview a whole trip, such as a hotel and a flight in one order, use
[`GET /v1/orders/{id}/cancellation-preview`](/docs/api-reference/orders/get-cancellation-preview). Each item reads
`previewable` with its preview, or `notCancellable` with a reason, and `totals.isComplete` is `true` only when every
item can be previewed.
### Amend by API [#amend-by-api]
Where a booking can be amended by API (`actions.amendment.availability` is `available`):
1. [`POST /v1/order-items/{id}/amendments/quote`](/docs/api-reference/order-items/quote-amendment) takes
`{ "attributes": { ... } }` with the changes you want and returns `amendmentRequestId`, `expiresAt` and `options`,
each `{ id, amountToPay, amountToRefund, amendmentFee }`. Nothing is charged yet.
2. [`POST /v1/order-items/{id}/amendments/confirm`](/docs/api-reference/order-items/confirm-amendment) takes
`{ "amendmentRequestId": "...", "paymentMethod": "balance", "selectedOptionId": "...", "maxPrice": { ... } }`.
`maxPrice` is optional and caps what you accept to pay for this amendment.
An amendment is priced on the terms the booking was bought on. By default it adds to the price, or refunds part of it,
in the same proportion as it changes the stay. Your account's booking terms can add a change fee, which is already
included in `amountToPay` and `amountToRefund`. A change never refunds more than your share of what you paid for the
part it removes. Only one amendment runs at a time: a confirm answers `409` while another is in progress. List
amendments with [`GET /v1/order-items/{id}/amendments`](/docs/api-reference/order-items/get-amendments), or across
items with [`GET /v1/amendments`](/docs/api-reference/order-items/list-partner-amendments).
`amendmentComposition` on the booking says what can change: guests, rooms, dates and holder. Some bookings of two
or more rooms can lose a room: send `attributes.roomGuests` listing the rooms to keep, as booked. The last room cannot be
removed; cancel the booking instead. A change the booking does not allow returns `400 / 21114` (rooms and guests) or
`400 / 21115` (dates and holder).
### Manual amendments [#manual-amendments]
When a booking cannot be changed by API, `actions.amendment.availability` reads `manualReview` and the quote answers
`409 / 18003` with the reason `MANUAL_REVIEW`. Changes then go through a manual amendment, which OpenRoam quotes.
| Step | Route |
|---|---|
| Request one | [`POST /v1/order-items/{id}/manual-amendments`](/docs/api-reference/hotel-manual-amendments/create-manual-amendment) with `{ "attributes": { ... } }`. Returns `{ amendmentId }`. Needs an `Idempotency-Key`. |
| Approve the quote | [`POST /v1/order-items/{id}/manual-amendments/{amendmentId}/approve`](/docs/api-reference/hotel-manual-amendments/approve-manual-amendment). Charges your wallet. Needs an `Idempotency-Key`. The body can carry an optional `walletId` to settle from another of your wallets. |
| Decline the quote | [`POST /v1/order-items/{id}/manual-amendments/{amendmentId}/decline`](/docs/api-reference/hotel-manual-amendments/decline-manual-amendment). Nothing is charged. |
| Cancel an unquoted request | [`POST /v1/order-items/{id}/manual-amendments/{amendmentId}/cancel`](/docs/api-reference/hotel-manual-amendments/cancel-manual-amendment). Any other status returns `400 / 21103`. |
Read an amendment and its quoted amounts with `GET /v1/order-items/{id}/amendments` and
`GET /v1/order-items/{id}/amendments/{amendmentId}`. The `attributes` object can hold `checkInDate` and
`checkOutDate`, a `holder`, and `roomGuests` with a 1-based `roomIndex` and its `guests`. Anything you leave out keeps
its booked value. The holder's `email` and `phone` are masked on reads: send one back as returned, or empty, to keep
the booked one. Any other masked value is refused with `400 / 10001`.
Progress is sent by the [`order-item.manual-amendment.status`](/docs/api-reference/webhooks/order-item-manual-amendment-status)
webhook. Its `data` carries `orderId`, `orderItemId`, `amendmentId`, `status`, `actionRequired`, `amountToPay`,
`amountToRefund` and `currencyCode`. `status` is `quoted` (with `actionRequired: true`, so you can approve or decline),
`completed`, `failed` or `cancelled`. Read the order again after each event.
Manual amendments, like any amendment, need hotels to be enabled for your account. Approving a quote with a wallet
balance that is too low returns `400 / 21107`: fund the wallet and approve again.
## Hotel catalog files [#hotel-catalog-files]
[`GET /v1/hotels/catalog/files`](/docs/api-reference/hotels/get-catalog-files) returns `generatedAt`, `hotelCount` and
links to downloadable zips: `withoutImages` (the main image only) and `withImages` (every gallery image). It also
returns a `replacements` file that maps replaced hotel ids to current ones. Each zip holds `hotels.jsonl`, one hotel per
line, in the shape `GET /v1/hotels/properties/{id}` returns, without offers and prices. Price a catalog hotel with a
`hotelIds` search. The files are rebuilt about twice a month and are empty until the first build. Download from the link
directly, and keep your last import until new files are listed. Use the same `generatedAt` for the hotel file and the
replacement map, and replace your previous map instead of appending to it.
## Testing in Sandbox [#testing-in-sandbox]
Sandbox supports hotels. It uses the same routes, validation, pricing and webhooks as production with a synthetic
catalog and test wallet funds; see [Environments](/docs/environments). Search issues fresh, stay-specific offers each
time, and availability does not run out.
- **Destinations.** There are 103 synthetic hotels in 16 destinations. Search by `cityCode` or coordinates:
`GYD` (Baku), `DXB` (Dubai), `AUH` (Abu Dhabi), `TYO` (Tokyo), `PAR` (Paris), `KUL` (Kuala Lumpur), `BKK` (Bangkok),
`HKT` (Phuket), `CNX` (Chiang Mai), `KBV` (Krabi), `LON` (London), `IST` (Istanbul), `SIN` (Singapore),
`NYC` (New York), `ROM` (Rome) and `DPS` (Bali). The destination lookup and the catalog files are not populated in
Sandbox.
- **Stays.** Normal validation applies: 1 to 9 rooms and 1 to 30 nights. Every hotel has a standard room-only rate paid
now, and a standard cancellation: free until check-in at 00:00 UTC, the full price from then.
- **Amendments.** Amendments are not available in Sandbox. Cancel and book a new stay.
Baku walkthrough: search `GYD` with `guestNationality` `AZ`, `currency` `USD`, future dates and `rooms` of
`[{"adults":2}]`. Find Sandbox Baku City Hotel and copy its `id`, then search again with
`searchCriteria.hotelIds` and the same stay to see all its rates. Choose by `details.board.boardType`:
| `boardType` | Room | Cancellation |
|---|---|---|
| `roomOnly` | Standard room | Standard cancellation |
| `breakfast` | Standard room | Standard cancellation |
| `unknown` (Brunch package) | Deluxe room | Standard cancellation |
| `halfBoard` | Deluxe room | Free until 00:00 UTC two days before check-in, 25% kept from then, 100% at check-in midnight |
| `fullBoard` | Deluxe room | Non-refundable from purchase |
| `allInclusive` | Suite | Free until 00:00 UTC one day before check-in, 100% kept from then |
Ways to exercise the edge cases:
- Book the half-board rate with check-in two UTC days away to enter the 25% band right away, then check
`GET /v1/order-items/{id}/cancellation-preview`.
- Send an `inputs.maxPrice` one minor unit below the quoted price to get `409 / 11002`.
- Reuse an offer after its `details.expiresAt` to see an expired offer, then search again for a fresh one.
- Sandbox Baku Guesthouse has a half-board Family room whose quote returns `availability: "onRequest"`; ordering it
returns `409 / 11003` before any charge.
On `POST /v1/hotels/order` (and the shared `POST /v1/orders`), the `OpenRoam-Sandbox-Scenario` header selects the
outcome:
| Header value | Result |
|---|---|
| `success` (or no header) | A confirmed reservation and a readable result. |
| `fulfillment.rejected` | A terminal failed reservation after payment, with no fulfilled result. 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 is saved with the order and is part of idempotency: the same key, body and scenario replay the same order,
and changing the scenario with that key returns `409`. Search, quote and cancel requests do not accept the header; it
returns `400 / 10001` with `NOT_ALLOWED`. Pending results carry no hotel confirmation. A hotel item can end `fulfilled`
before a progress message appears, and completion is seen on the next reconciliation pass, so the durations are not a
guaranteed delay. Even with `success`, a booking takes from about 20 to 60 seconds to confirm, so read the order again
or wait for the webhook.
A rejected booking is refunded automatically, and cancelling with the reason `fulfillmentFailed` returns that refund.
Use the same cancel route to cancel a refundable confirmed booking.
## Errors to handle [#errors-to-handle]
Shared error handling is in [Errors](/docs/errors). Branch on `code`, not on the message, and keep `requestId` for
support.
| Status / code | Name or reason | When and what to do |
|---|---|---|
| `400 / 10001` | `INVALID_VALUE` | An invalid body field, including guests that do not fit the searched rooms, names the booking refuses, or an unknown member. The `details[].path` names it, for example `inputs.roomGuests` or `inputs.holder.email`. |
| `400 / 10001` | `MAX_STAY_EXCEEDED` | The stay is longer than 30 nights, at `checkOut`. |
| `400 / 10001` | `REQUIRED` | An order item without `inputs`, at `items[i].inputs`. |
| `400 / 10001` | `NOT_SUPPORTED` | A currency OpenRoam does not support, at `currency`. |
| `400 / 11004` | `EXPIRED_OR_INVALID` | An unknown, expired or foreign offer id, a hotel's own `id`, or another product's offer. Search again for a fresh offer. |
| `409 / 11003` | `UNAVAILABLE` | The rate is no longer sold, or it can only be held on request. Pick another offer. |
| `409 / 11002` | `PRICE_CHANGED` | The fresh price is above your cap or above the price returned with the `publicId`. Nothing is charged. Quote again. |
| `409 / 11006` | `TERMS_CHANGED` | The cancellation terms got stricter than the quote's. Quote again and check the terms. |
| `400 / 11005` | `CURRENCY_MISMATCH` | The offer was priced in another currency than the order. Search or quote in the order currency. |
| `403 / 10003` | `SERVICE_NOT_ENABLED` | Hotels are not enabled for your account. |
| `404 / 10004` | none | `GET /v1/hotels/properties/{id}` with an id of no catalog hotel. |
| `400 / 21000` | `HOTEL_ID_INVALID` | A `hotelIds` entry that is not a hotel id. |
| `400 / 21010` | `HOTEL_OCCUPANCY_MISMATCH` | The rate's room layout no longer matches the searched rooms. Search again. |
| `503 / 21003` | `HOTEL_RATE_CONTEXT_UNAVAILABLE` | Hotel offers are temporarily unavailable. Retry a search or quote later. After an order, check the existing order before retrying. |
| `502 / 21007`, `504 / 21008`, `503 / 21009` | `HOTEL_REQUEST_FAILED`, `HOTEL_RESPONSE_TIMEOUT`, `HOTEL_TEMPORARILY_UNAVAILABLE` | The hotel request failed, timed out or is unavailable. Retry read-only calls later. For writes, check the order state before retrying. |
| `503 / 10007` | none | The destination lookup is unavailable. Retry. |
| `400 / 21004` | `HOTEL_BOOKING_UNAVAILABLE` | The item has no valid booking to cancel or amend. Reload the order. |
| `400 / 21005` | `HOTEL_AMENDMENT_UNSUPPORTED` | This booking does not support the amendment mode you tried. |
| `400 / 21102` | `HOTEL_AMENDMENT_TICKET_ALREADY_OPEN` | A manual amendment is already open for this booking. Use the existing one. |
| `400 / 21103` | `HOTEL_AMENDMENT_INVALID_STATE` | The action is not allowed in the amendment's current state. Reload it first. |
| `400 / 21107` | `HOTEL_AMENDMENT_INSUFFICIENT_BALANCE` | The wallet cannot cover the amendment. Fund it, then approve again. |
| `409 / 21111` | `HOTEL_AMENDMENT_ORDER_BUSY` | The booking is being processed. Try again shortly. |
| `409 / 21112` | `HOTEL_AMENDMENT_CONCURRENT_CHANGE` | Another request updated the amendment. Reload and retry. |
| `400 / 21113` | `HOTEL_AMENDMENT_INVALID_GUEST_COMPOSITION` | The requested rooms, guests, names or ages are invalid. |
| `400 / 21114`, `400 / 21115` | `HOTEL_AMENDMENT_GUEST_COMPOSITION_CHANGE_UNSUPPORTED`, `HOTEL_AMENDMENT_CHANGE_UNSUPPORTED` | The room or guest change (21114), or the date or holder change (21115), is not supported for this booking. Check `amendmentComposition`. |
| `400 / 21108`, `409 / 21109` | `HOTEL_AMENDMENT_SETTLEMENT_FAILED`, `HOTEL_AMENDMENT_SETTLEMENT_CONFLICT` | The settlement could not be completed. Do not retry automatically: reload the amendment and contact support. |
| `409 / 18003` | `MANUAL_REVIEW`, `IN_PROGRESS` or `NOT_AVAILABLE` | An amendment cannot be quoted or confirmed now. `MANUAL_REVIEW` points to manual amendments. |
| `422 / 18004` | none | `update` is not supported for hotel bookings. Use amendments. |
Browse routes reject any unknown query parameter with `400 / 10001` and the reason `UNSUPPORTED_FIELD`. A failing quote
or order creates and charges nothing.
# Utility bill payments (/docs/products/utility)
## What you can sell [#what-you-can-sell]
A biller is one payee in one country, such as an electricity company or a television operator. Billers belong to a category (`electricity`, `water`, `gas`, `internet`, `television`, `landline`, `voip`, `toll` or `other`) and a service type (`prepaid` or `postpaid`).
A biller sells fixed amounts, a range of amounts, or both. Two kinds of delivery exist:
- **`directCredit`**: the payment reaches the biller. The item has no token.
- **`token`**: the payment returns a usable token, such as a prepaid meter token or a PIN.
OpenRoam sells ranged and fixed bill payments and recharges with the inputs listed on each offer. Each item pays one bill, so `quantity` is always 1. To pay the same biller twice, send two items.
## The flow [#the-flow]
### Search [#search]
[`GET /v1/utility/search`](/docs/api-reference/utility/search) returns billers with their offers, one page at a time. `countryCode` is required. Other filters are `category`, `serviceType`, `q` (text in the biller name, at most 100 characters), `currency`, `page` and `limit`.
Related routes:
- [`GET /v1/utility/billers/{id}`](/docs/api-reference/utility/get-biller) returns one biller in the shape search returns.
- [`GET /v1/utility/catalog`](/docs/api-reference/utility/get-catalog) walks every biller in id order, page by page with a cursor. `countryCode` is optional here.
Utility has no list of summaries, and no value or price filters: `valueType`, `minValue`, `maxValue`, `minPrice` and `maxPrice` are unknown parameters. Unknown parameters are rejected with `400 / 10001` (`UNSUPPORTED_FIELD`).
### Quote [#quote]
[`POST /v1/utility/quote`](/docs/api-reference/utility/quote) prices an order body. It has no side effects: no token, no reservation, no expiry, no payment, and no check of the customer's account with the biller. To hold a quoted price, send it as `inputs.maxPrice` in the order.
### Order [#order]
[`POST /v1/utility/order`](/docs/api-reference/utility/create-order) takes the same body as the quote. It needs an `Idempotency-Key` header and an API key with the `manage` permission. The response is the shared order envelope, read later with [`GET /v1/orders/{id}`](/docs/api-reference/orders/get-by-id). See [Idempotency](/docs/idempotency) and [Orders](/docs/orders).
You can also pay bills together with other products through [`POST /v1/orders`](/docs/api-reference/orders/create-order), where each item adds `productType: "utility"`.
## Search [#search-1]
```bash
curl "https://api.sandbox.openroam.com/v1/utility/search?countryCode=AZ" \
-H "X-Partner-Key: $OPENROAM_API_KEY"
```
```json
{
"items": [
{
"id": "biller_3jx464dkw4ekdjgj4qxuib5wki",
"name": "Fixed postpaid",
"countryCode": "AZ",
"category": "other",
"logoUrl": null,
"description": null,
"offers": [
{
"publicId": "utility_7tq2mw5kxr3nbv6hzc4dpe2ysa",
"name": "Local tier",
"description": null,
"value": { "type": "fixed", "amount": 40, "currency": "AZN" },
"price": { "amount": 27.5, "currency": "USD" },
"requiredInputs": [
{ "name": "accountNumber", "type": "text", "required": true, "description": "The customer's account or meter number with the biller." }
]
}
],
"details": { "serviceType": "postpaid", "deliveryType": "directCredit" }
},
{
"id": "biller_jeicjoplfgowwmc2h7mbwbatqe",
"name": "Range prepaid",
"countryCode": "AZ",
"category": "other",
"logoUrl": null,
"description": null,
"offers": [
{
"publicId": "utility_k4hv2cq7wnz5jr3xmtb6eyl2pa",
"name": "Range prepaid 20–200 AZN",
"description": null,
"value": { "type": "range", "min": 20, "max": 200, "step": 0.01, "currency": "AZN" },
"price": { "min": 14.38, "max": 132.5, "currency": "USD" },
"requiredInputs": [
{ "name": "accountNumber", "type": "text", "required": true, "description": "The customer's account or meter number with the biller." }
]
}
],
"details": { "serviceType": "prepaid", "deliveryType": "token" }
}
],
"pagination": { "currentCount": 2, "totalCount": 2, "skip": 0, "limit": 10, "hasMore": false, "page": 1, "totalPages": 1 }
}
```
### Billers [#billers]
- `id` is the biller's opaque token, starting with `biller_`. It names the biller, not something to buy. Quote and order take an offer's `publicId`. Sending a biller id, or any malformed id, as a `publicId` gives `400 / 11004`.
- `countryCode` is the biller's ISO 3166-1 alpha-2 country and is never null.
- `category` is one of the values above. A category OpenRoam does not map is `other`.
- `details.serviceType` is `prepaid` or `postpaid`. `details.deliveryType` is `token` or `directCredit`.
- `billers/{id}` returns `404 / 10004` for an unknown id, an id that does not start with `biller_`, and a biller without an orderable offer. Search does not list such billers either.
- A search page holds fewer billers than `limit` when some billers on it cannot be priced. `pagination.totalCount` counts billers that match the filters and have an orderable route.
### Catalog walks [#catalog-walks]
Continue with `nextCursor`, the same filters and the same currency until `nextCursor` is null. A page can hold fewer billers than `limit`, even none, while `nextCursor` is not null. A cursor reused with other filters or another currency gives `400 / 10001`, so start the walk again.
The walk is not a frozen snapshot. A biller that stays available during the whole walk appears exactly once, and one that appears or disappears during the walk may be missing. Update your copy by biller `id`, and remove a biller only when a complete walk with the same filters did not return it. On `429`, wait for `Retry-After` and request the same page again.
## Offers [#offers]
A biller's offers are:
- one fixed offer per **package**: a product sold under its own label, such as a fixed recharge or a PIN. Two packages can have the same amount, so the amount does not name one;
- one fixed offer per fixed amount without a package, per currency;
- one range offer per currency and set of required inputs.
Fixed offers come first, by ascending value, then the range offers.
- `publicId` is an opaque token starting with `utility_`. Order with it exactly as browse returns it. Do not build or parse it. The id stays the same while the biller has that offer. When a biller stops selling an offer its id names nothing, and a new offer gets a new id. The offer id alone decides what is bought: there is no package or option input.
- `name` is the stored label of a package or fixed amount when one exists, for example `Local tier`. Otherwise it is built from the biller and the value, such as `Fixed postpaid 40 AZN` or `Range prepaid 20–200 AZN`.
- `value` is in the currency the biller is paid in: `{ type: "fixed", amount, currency }` or `{ type: "range", min, max, step, currency }`. A range's `max` is null when there is no upper bound. Use the offer's currency, not a country-wide assumption: a country can have billers paid in local currency and in USD.
- `price` is indicative and in the requested currency. A range's `price` is `{ min, max, currency }`, the price of its minimum and maximum value, and `price.max` is null when `value.max` is. The quote is authoritative, and it can be higher or lower than the browse price. An offer whose price cannot be computed is left out.
- One range offer can combine several ranges in the same currency that take the same inputs. Its `min` is the lowest minimum and its `max` the highest maximum. An amount must be on the published range and step. An amount on that grid that none of the underlying ranges sells gives `409 / 11003` at `items[i]`. An amount outside the published range gives `400 / 10001` (`INVALID_VALUE`).
### Required inputs [#required-inputs]
`requiredInputs` lists the customer inputs an offer takes. Each listed input is required.
| `name` | `type` | Listed when the biller needs |
|---|---|---|
| `accountNumber` | `text` | The customer's account or meter number. |
| `mobileNumber` | `phone` | The customer's mobile number with the biller. |
| `beneficiaryMobileNumber` | `phone` | The mobile number of the person who receives the payment. |
| `invoiceId` | `text` | The id of the bill to pay, as the biller issued it. At most 64 characters. Only for an offer that lists it. |
- A value is trimmed, must not be empty, and has at most 128 characters. Account numbers keep their leading zeros.
- A `phone` value must be an international number starting with `+` or `00`. Spaces, hyphens and brackets are removed, and `00` becomes `+`. Bare digits such as `994501234567` are rejected with `INVALID_VALUE` at `items[i].inputs.mobileNumber` (or `beneficiaryMobileNumber`), because OpenRoam does not guess the country.
- A listed input the item leaves out is `REQUIRED` at `items[i].inputs.`. An input the offer does not list is `NOT_ALLOWED` at the same path, before any purchase is attempted.
- An offer can list no inputs, for example a PIN product. `inputs` may then be omitted, unless the offer is a range, which needs `inputs.value`.
`inputs` also takes the standard `value` and `maxPrice` fields. `requiredInputs` never lists them.
## Quote and order [#quote-and-order]
Quote and order take the same body. The fixed offer below is bought without a value, and the range offer at 50 AZN:
```json
{
"currency": "USD",
"referenceId": "partner-order-42",
"items": [
{
"publicId": "utility_7tq2mw5kxr3nbv6hzc4dpe2ysa",
"quantity": 1,
"inputs": {
"accountNumber": "1234567",
"maxPrice": { "amount": 30, "currency": "USD" }
}
},
{
"publicId": "utility_k4hv2cq7wnz5jr3xmtb6eyl2pa",
"quantity": 1,
"inputs": {
"accountNumber": "7654321",
"value": { "amount": 50, "currency": "AZN" },
"maxPrice": { "amount": 35, "currency": "USD" }
}
}
]
}
```
```bash
curl -X POST https://api.sandbox.openroam.com/v1/utility/quote \
-H "X-Partner-Key: $OPENROAM_API_KEY" \
-H "Content-Type: application/json" \
-d @utility-order.json
curl -X POST https://api.sandbox.openroam.com/v1/utility/order \
-H "X-Partner-Key: $OPENROAM_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d @utility-order.json
```
Quote response:
```json
{
"currency": "USD",
"items": [
{
"publicId": "utility_7tq2mw5kxr3nbv6hzc4dpe2ysa",
"quantity": 1,
"name": "Fixed postpaid 40 AZN",
"value": { "amount": 40, "currency": "AZN" },
"price": { "amount": 27.5, "currency": "USD" },
"details": { "deliveryType": "directCredit" }
},
{
"publicId": "utility_k4hv2cq7wnz5jr3xmtb6eyl2pa",
"quantity": 1,
"name": "Range prepaid 50 AZN",
"value": { "amount": 50, "currency": "AZN" },
"price": { "amount": 34.06, "currency": "USD" },
"details": { "deliveryType": "token" }
}
],
"total": { "amount": 61.56, "currency": "USD" }
}
```
- 1 to 5 items. `quantity` must be 1.
- `currency` is the price currency, the one you are charged in. It is optional, and the default is your API key's currency. It is separate from the value currency.
- `referenceId` is your own reference. Quote validates it and ignores it.
- `publicId` in the quote response is always the one you sent.
- Items are checked one at a time in request order, and the first failing item ends the request. Quote and order report the same error for it.
`inputs.value` is the amount to pay the biller, `{ amount, currency }`, in the offer's value currency:
- A range offer requires it, on the published range and step. A range offer without it fails with `REQUIRED` at `items[i].inputs.value`.
- A fixed offer takes it optionally. When sent, it must equal the offer's amount. A fixed offer without it pays its own amount.
- An amount outside the published range, off its step, or other than the fixed offer's amount is `400 / 10001` (`INVALID_VALUE`) at `items[i].inputs.value.amount`. A value in another currency is `CURRENCY_MISMATCH` at `items[i].inputs.value.currency`.
- An amount is above 0 and has at most the decimals of its currency (two in most currencies, none in JPY, three in KWD).
`inputs.maxPrice` is the highest unit price you accept, `{ amount, currency }`, in the order currency. It is optional.
- Order recalculates every price. A lower price is charged as calculated. A higher price is accepted up to `maxPrice`. Above it, the order fails with `409 / 11002` at `items[i].inputs.maxPrice` and nothing is charged.
- Without `maxPrice`, the current price is charged, including an increase since the quote.
- The amount paid to the biller is never reduced to fit `maxPrice`.
A purchase name is the same in the quote and on the order item. A package keeps its stored label, or the biller name when its label is blank. Any other purchase is named from the biller and the purchased value, for example `Range prepaid 50 AZN`. A range purchase is never named by its bounds.
## Delivery types and the order item [#delivery-types-and-the-order-item]
`deliveryType` says what a paid bill delivers, and when the item becomes `fulfilled`:
| `deliveryType` | `fulfillment.status` becomes `fulfilled` when | `result.details.token` |
|---|---|---|
| `token` | The payment is confirmed and a usable token is returned, such as a prepaid meter token or a PIN. | The token |
| `directCredit` | The payment is confirmed as reaching the biller. | null |
A payment that is confirmed without the token it promised stays `pending` until it is resolved. A reference alone does not mean fulfilled.
```json
{
"id": "01a14331-d5f1-7e18-8963-7fcdc3b15eab",
"orderId": "01a14331-d5d2-7a25-9f98-9bbd58e02e05",
"productType": "utility",
"price": { "amount": 34.06, "currency": "USD" },
"purchasedProduct": {
"name": "Range prepaid 50 AZN",
"countryCode": "AZ",
"logoUrl": null,
"value": { "amount": 50, "currency": "AZN" },
"inputs": { "accountNumber": "***4321", "mobileNumber": null, "beneficiaryMobileNumber": null, "invoiceId": null },
"details": { "serviceType": "prepaid", "deliveryType": "token" }
},
"fulfillment": {
"status": "fulfilled",
"result": {
"deliveredValue": { "amount": 50, "currency": "AZN" },
"details": { "token": "example-meter-token" }
},
"failure": null
},
"actions": {
"amendment": { "availability": "notAvailable", "reason": null },
"cancellation": { "availability": "notAvailable", "reason": null },
"update": { "availability": "notAvailable", "reason": null }
},
"createdAt": "2026-10-16T05:31:41.959678Z",
"effectivePaidAmount": { "amount": 34.06, "currency": "USD" }
}
```
`purchasedProduct`:
- `name` is the purchase name. `countryCode` is the biller's country. `logoUrl` is always null on the item, so read the logo from the biller. `value` is the amount paid to the biller.
- `inputs` echoes `accountNumber`, `mobileNumber`, `beneficiaryMobileNumber` and `invoiceId`, and an input the item did not store is null. Masking:
- `accountNumber` and `invoiceId` are masked as `***` followed by the last four characters. A value of four characters or fewer is shown as `***`.
- `mobileNumber` and `beneficiaryMobileNumber` are masked as a plus sign, the country code, `***` and the last four digits.
- `value` and `maxPrice` are not echoed. The amount is `purchasedProduct.value`.
- `details` has `serviceType` and `deliveryType`. It reads `unknown` for items bought before the delivery type was stored.
`fulfillment.result`:
- `deliveredValue` is the amount confirmed as received by the customer. It is null until confirmed and is never copied from `purchasedProduct.value`. A later confirmation sends another `order.fulfillment.updated` webhook with a higher `fulfillmentVersion`.
- `details.token` is the token of a `token` biller once the payment is ready, and null otherwise. Handle it as a secret: show it only to the customer who paid.
`fulfillment.status` stays `pending` until the payment is confirmed and, for a `token` biller, the token is known. Read the order with [`GET /v1/orders/{id}`](/docs/api-reference/orders/get-by-id). The [`order.fulfillment.updated` webhook](/docs/api-reference/webhooks/order-fulfillment-updated) carries the same `result`. See [Webhooks](/docs/webhooks) and [Orders](/docs/orders).
A bill payment cannot be taken back or changed. Once delivered, cancel and its preview answer `422 / 18000`, amendments `422 / 18002` and update `422 / 18004`. While the payment is pending, cancel answers `409 / 18001`. A rejected payment is refunded in full automatically and reported by the `order-item.refunded` webhook. A reversal after delivery does not credit your wallet by itself.
## Testing in Sandbox [#testing-in-sandbox]
Use [Sandbox](/docs/environments) with your Sandbox key. Authentication, validation, pricing, wallet payment and webhooks behave as in production. The catalog and outcomes are synthetic, and no real account lookup or payment happens.
### Scenarios [#scenarios]
`POST /v1/utility/order` and the shared `POST /v1/orders` accept the `OpenRoam-Sandbox-Scenario` header:
| Value | Result |
|---|---|
| Omitted or `success` | Confirmed delivery. A `directCredit` item has no token. A `token` item returns a code starting with `SANDBOX-NONREDEEMABLE-`, which cannot pay a real bill. |
| `fulfillment.rejected` | A definitive rejection, with no delivered value and no token. The item is refunded automatically. |
| `fulfillment.pending` | The item stays `pending` without blocking, and becomes eligible for success after about 15 minutes. |
| `fulfillment.late_success` | Pending, then success after about 2 minutes. |
| `fulfillment.late_rejected` | Pending, then rejection after about 2 minutes. |
```bash
curl -X POST https://api.sandbox.openroam.com/v1/utility/order \
-H "X-Partner-Key: $OPENROAM_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "OpenRoam-Sandbox-Scenario: fulfillment.rejected" \
-H "Content-Type: application/json" \
-d @utility-order.json
```
- The scenario is saved with the order and takes part in idempotency. The same key and body replay the order. Omitted and explicit `success` are equivalent. The same key with a different scenario returns `409`.
- Search, billers, catalog, quote, reads and refunds take no scenario header. Sending it there, or outside Sandbox, returns `400 / 10001` (`NOT_ALLOWED`). An unknown, empty or repeated value returns `400 / 10001` (`INVALID_VALUE`).
- Timing is approximate and not a guarantee. A pending item may show `fulfillment.progress` with code `CONFIRMING_OUTCOME`. By default Sandbox fulfillment takes a few seconds, during which `GET /v1/orders/{id}` shows the item as `pending`.
- The delivered value in a successful result is confirmed test data, not a copy of the purchased value.
### Sandbox catalog [#sandbox-catalog]
The Sandbox catalog covers 35 countries with 95 services, 190 billers and 760 offers. Each service has one fixed biller with seven offers and one range biller with one offer. Names, categories and currencies follow real catalog entries, and amounts, steps, inputs and prices are synthetic. Do not hardcode offer ids: search, billers and the catalog return them. A valid country without fixtures returns an empty `items` array, not an error.
Test values:
- `accountNumber`: `001234567`
- `mobileNumber` and `beneficiaryMobileNumber`: `+994501234567`. A value such as `00 994 (50) 123-45-67` normalizes to the same number.
Azerbaijan has test billers that cover each delivery shape:
| Biller | Category / service type | Delivery | Offers | Required input |
|---|---|---|---|---|
| AZ Electricity (fixed) | electricity / postpaid | `directCredit` | seven fixed values | `accountNumber` |
| AZ Electricity (range) | electricity / postpaid | `directCredit` | one range | `mobileNumber` |
| AZ Water (fixed) | water / prepaid | `token` | seven fixed values | `beneficiaryMobileNumber` |
| AZ Water (range) | water / prepaid | `token` | one range | `accountNumber` |
| AZ Gas | gas / postpaid | `directCredit` | seven fixed values and one range | `accountNumber` and `mobileNumber` |
| AZ Internet PIN | internet / prepaid | `token` | seven fixed packages and one range | none |
- The fixed AZ values are 10, 20, 40, 60, 100, 150 and 200 AZN. The AZ ranges run from 20 to 200 AZN in steps of 5.
- Find AZ Gas with `GET /v1/utility/search?countryCode=AZ&category=gas&serviceType=postpaid`. Quote its range at 50 AZN with both `accountNumber` and `mobileNumber`. A successful order credits the test account and issues no token.
- Find the AZ Internet PIN services with `GET /v1/utility/search?countryCode=AZ&category=internet&q=AZ%20Internet%20PIN`. Its packages are 5, 10, 15, 20, 25, 50 and 100 USD, and its range accepts 5 to 100 USD in steps of 1, with only `inputs.value` required. A successful order issues a test token.
- Invoice payment flows are not enabled in Sandbox. An input an offer does not list, including `invoiceId`, is `NOT_ALLOWED`.
## Errors [#errors]
Paths below are for the `items[]` bodies. They are prefixed with `items[i].` on quote, order and the shared order.
| Status / code | When | Path (`reason`) |
|---|---|---|
| `400 / 10001` | A listed input is missing, not allowed, or malformed | `inputs.` (`REQUIRED`, `NOT_ALLOWED` or `INVALID_VALUE`) |
| `400 / 10001` | A range offer without `inputs.value` | `inputs.value` (`REQUIRED`) |
| `400 / 10001` | `inputs.value` outside the published range, off its step, or not the fixed offer's amount | `inputs.value.amount` (`INVALID_VALUE`) |
| `400 / 10001` | `inputs.value` in another currency than the offer's | `inputs.value.currency` (`CURRENCY_MISMATCH`) |
| `400 / 10001` | `inputs.maxPrice` in another currency than the order's | `inputs.maxPrice.currency` (`CURRENCY_MISMATCH`) |
| `400 / 10001` | An amount not above 0 or with too many decimals, or a currency that is not three letters | `inputs.value.amount`, `inputs.maxPrice.amount`, `inputs.value.currency`, `inputs.maxPrice.currency` (`INVALID_VALUE`) |
| `400 / 10001` | `quantity` other than 1, or no items or more than 5 | `quantity` (`INVALID_VALUE`), `items` |
| `400 / 10001` | A `value` or `maxPrice` beside `inputs`, or any unknown member | the field path (`INVALID_VALUE`) |
| `400 / 10001` | Unknown query parameter, invalid filter, or a catalog cursor issued for other filters or another currency | the parameter |
| `400 / 11004` | Unknown or malformed `publicId`, a biller id, or an offer of another product | `items[i]` (`EXPIRED_OR_INVALID`) |
| `409 / 11003` | The offer cannot be sold now, or no range sells an amount on a combined range | `items[i]` (`UNAVAILABLE`) |
| `409 / 11002` | The current price is above `inputs.maxPrice` | `inputs.maxPrice` (`PRICE_CHANGED`) |
| `404 / 10004` | `billers/{id}` with an unknown id, an id that does not start with `biller_`, or a biller with no orderable offer | none |
| `403 / 10003` | Utility is not enabled for your account, or the key lacks the `manage` permission | `service` (`SERVICE_NOT_ENABLED`) |
| `503 / 10007` | The service or the price calculation is temporarily unavailable. Nothing is charged. | none |
Where an error path starts depends on the request. On quote and the product order, an unknown member inside `inputs` is reported as `$.items[i].inputs.`, and a member beside `inputs` as `$.items[i].`. The mixed `POST /v1/orders` reports a member inside `inputs` as `items[i].inputs.`.
Check which services are enabled with [`GET /v1/account/services`](/docs/api-reference/account/get-services). Idempotency errors are shared across products; see [Idempotency](/docs/idempotency). For the common error format, see [Errors](/docs/errors).
## Next steps [#next-steps]
- [Quickstart](/docs/quickstart) for your first order.
- [Authentication](/docs/authentication) and [Environments](/docs/environments) for keys and hosts.
- [Orders](/docs/orders) for order and item status.
- [Webhooks](/docs/webhooks) for signing and retries.
# Quickstart (/docs/quickstart)
This walkthrough buys an eSIM in Sandbox with `curl`. Every product follows the same steps; only the search parameters and the inputs differ.
You need a Sandbox API key with the `manage` permission (see [Authentication](/docs/authentication)) and a funded Sandbox wallet.
```bash
export OPENROAM_API_KEY="your Sandbox key"
export OPENROAM_URL="https://api.sandbox.openroam.com"
```
### Check your account [#check-your-account]
[`GET /v1/account/services`](/docs/api-reference/account/get-services) confirms the key works and lists the products enabled for your account.
```bash
curl "$OPENROAM_URL/v1/account/services" -H "X-Partner-Key: $OPENROAM_API_KEY"
```
### Search [#search]
[`GET /v1/esims/search`](/docs/api-reference/esims/search) returns eSIM destinations that cover a country, each with its offers.
```bash
curl "$OPENROAM_URL/v1/esims/search?countryCode=FR¤cy=USD&limit=5" \
-H "X-Partner-Key: $OPENROAM_API_KEY"
```
```json
{
"items": [
{
"id": "destn_...",
"name": "France",
"countryCode": "FR",
"category": "local",
"logoUrl": "https://...",
"description": null,
"offers": [
{
"publicId": "esim_...",
"name": "France 5 GB 30 days",
"description": null,
"price": { "amount": 9.5, "currency": "USD" },
"requiredInputs": [
{ "name": "isInstant", "type": "boolean", "required": false, "description": "..." }
],
"details": { "...": "plan details" }
}
]
}
],
"pagination": { "currentCount": 1, "totalCount": 1, "skip": 0, "limit": 5, "hasMore": false, "page": 1, "totalPages": 1 }
}
```
Pick an offer and keep its `publicId`. Its `requiredInputs` lists the inputs the order needs; add every required one under `inputs`.
### Quote [#quote]
[`POST /v1/esims/quote`](/docs/api-reference/esims/quote) validates the body and returns the current price. Nothing is charged or reserved.
```bash
curl -X POST "$OPENROAM_URL/v1/esims/quote" \
-H "X-Partner-Key: $OPENROAM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"currency": "USD",
"items": [{ "publicId": "esim_...", "quantity": 1, "inputs": {} }]
}'
```
```json
{
"currency": "USD",
"items": [
{ "publicId": "esim_...", "quantity": 1, "name": "France 5 GB 30 days", "price": { "amount": 9.5, "currency": "USD" }, "details": {} }
],
"total": { "amount": 9.5, "currency": "USD" }
}
```
Order with the `publicId` the quote returns: for hotels, flights and gift cards it can differ from the one you sent.
### Order [#order]
[`POST /v1/esims/order`](/docs/api-reference/esims/create-order) takes the same body, plus an `Idempotency-Key` header: a new UUID for each purchase. Keep the key until you have the response, so a retry after a timeout cannot buy twice (see [Idempotency](/docs/idempotency)).
To cap the price, send the quoted unit price as `inputs.maxPrice`. A higher price is refused with `409 / 11002` and nothing is charged.
```bash
IDEMPOTENCY_KEY=$(uuidgen)
curl -X POST "$OPENROAM_URL/v1/esims/order" \
-H "X-Partner-Key: $OPENROAM_API_KEY" \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
-H "Content-Type: application/json" \
-d '{
"currency": "USD",
"referenceId": "my-order-42",
"items": [{
"publicId": "esim_...",
"quantity": 1,
"inputs": { "maxPrice": { "amount": 9.5, "currency": "USD" } }
}]
}'
```
The response is the order. OpenRoam charged your wallet and is delivering the item:
```json
{
"id": "04b817c4-05d4-4e06-954b-e2470a87b620",
"origin": { "channel": "api" },
"status": "processing",
"total": { "amount": 9.5, "currency": "USD" },
"refunded": { "amount": 0, "currency": "USD" },
"payment": { "status": "completed", "method": "balance", "amount": { "amount": 9.5, "currency": "USD" }, "wallet": null, "failure": null },
"items": [
{
"id": "5d6650ea-03f0-4a24-94f8-0c5d66a567e7",
"orderId": "04b817c4-05d4-4e06-954b-e2470a87b620",
"productType": "esim",
"price": { "amount": 9.5, "currency": "USD" },
"purchasedProduct": { "name": "France 5 GB 30 days", "...": "..." },
"fulfillment": { "status": "pending", "result": null, "failure": null }
}
],
"timeline": [{ "status": "processing", "occurredAt": "2026-11-16T10:00:00Z" }],
"createdAt": "2026-11-16T10:00:00Z",
"updatedAt": "2026-11-16T10:00:00Z",
"fulfillmentVersion": 1
}
```
If your wallet cannot pay, the order is refused with `402 / 16000` and nothing is kept. Top up, then send the same request with the same `Idempotency-Key`.
### Follow delivery [#follow-delivery]
Read the order with [`GET /v1/orders/{id}`](/docs/api-reference/orders/get-by-id), or subscribe to the [`order.fulfillment.updated`](/docs/webhooks) webhook. When the item's `fulfillment.status` is `fulfilled`, `fulfillment.result` holds what was delivered: for an eSIM, the details your customer needs to install it.
```bash
curl "$OPENROAM_URL/v1/orders/04b817c4-05d4-4e06-954b-e2470a87b620" \
-H "X-Partner-Key: $OPENROAM_API_KEY"
```
## Next steps [#next-steps]
- Read the guide of the product you sell: [eSIMs](/docs/products/esims), [Airtime](/docs/products/airtime), [Utility](/docs/products/utility), [Gift cards](/docs/products/gift-cards), [Hotels](/docs/products/hotels) or [Flights](/docs/products/flights).
- Handle [errors](/docs/errors) and [webhooks](/docs/webhooks).
- Learn what happens to an order after purchase in [Orders](/docs/orders).
- Try other outcomes with the [Sandbox scenario header](/docs/environments#choose-a-fulfillment-outcome).
# SDKs (/docs/sdks)
The SDKs are in private beta and not on public package registries yet. OpenRoam sends you the release files to install. Before version 1.0 the API of the clients can change between minor versions.
OpenRoam publishes one client library per language, all generated from the same [OpenAPI specification](/openapi.json) and released together under one version number.
| Language | Package |
|---|---|
| TypeScript and JavaScript | `@openroam/sdk` |
| Python | `openroam` |
| Go | `github.com/OpenRoamHQ/openroam-go` |
| PHP | `openroam/sdk` |
| Java | `com.openroam:openroam-sdk` |
| .NET | `OpenRoam` |
| Dart | `openroam` |
| Ruby | `openroam` |
Every SDK:
- names the Sandbox and Production [environments](/docs/environments) and accepts any other base URL;
- sends your key in `X-Partner-Key`;
- creates an `Idempotency-Key` for each order and lets you pass your own;
- raises one error type with the API's `code`, `name`, `message`, `requestId` and `details`;
- has an opt-in retry layer for network errors, `429` and `502`, `503` and `504`, which repeats purchases with the same `Idempotency-Key`;
- includes a helper that verifies [webhook](/docs/webhooks) signatures.
## TypeScript example [#typescript-example]
```ts
import { OpenRoam, OpenRoamError } from '@openroam/sdk';
const openroam = new OpenRoam({
apiKey: process.env.OPENROAM_API_KEY,
environment: 'sandbox', // the default is 'production'
});
const found = await openroam.esims.search({ countryCode: 'JP' });
const offer = found.items[0]?.offers[0];
if (offer) {
const items = [{ publicId: offer.publicId, quantity: 1, inputs: {} }];
const quote = await openroam.esims.quote({ currency: 'USD', items });
try {
const order = await openroam.esims.order(
{ currency: 'USD', items },
{ idempotencyKey: myPurchaseId }, // a UUID you stored for this purchase
);
console.log(order.id, order.status, quote.total);
} catch (error) {
if (error instanceof OpenRoamError && error.code === 16000) {
// The wallet could not pay: top up, then repeat with the same idempotency key.
}
throw error;
}
}
```
Each product is a property of the client: `esims`, `airtime`, `utilities`, `giftCards`, `hotels` and `flights`, plus `orders`, `orderItems`, `wallets`, `account`, `currencies`, `countries` and `mobileNetworks`. Buying is always `search`, `quote`, `order`.
Each SDK's README covers installation and its own examples.
# Webhooks (/docs/webhooks)
OpenRoam sends events to an HTTPS endpoint you register in the partner dashboard. Each environment has its own webhooks and signing secrets. When you create a webhook you choose its events; for `order.fulfillment.updated` you can also choose the order origins it receives (`api`, `dashboard`, or both).
## Events [#events]
| Event | Sent when |
|---|---|
| [`order.fulfillment.updated`](/docs/api-reference/webhooks/order-fulfillment-updated) | An order's delivery changes: items delivered or rejected, a later result, a confirmed cancellation of a delivered item, or the order reaching `partiallyRefunded` or `refunded` |
| [`order-item.refunded`](/docs/api-reference/webhooks/order-item-refunded) | A refund of an item progresses or completes, including the automatic refund of a rejected item |
| [`order-item.manual-amendment.status`](/docs/api-reference/webhooks/order-item-manual-amendment-status) | A hotel manual amendment changes status, including when it needs your action |
| [`esim.profileStatus.updated`](/docs/api-reference/webhooks/esim-profile-status-updated) | An eSIM's profile status changes, for example when it is installed |
| [`esim.usage.updated`](/docs/api-reference/webhooks/esim-usage-updated) | An eSIM's data usage crosses a threshold |
| [`partner.balance.low`](/docs/api-reference/webhooks/partner-balance-low) | A wallet balance falls into a lower configured threshold band |
The [API reference](/docs/api-reference/webhooks/order-fulfillment-updated) documents the body of each event.
## The request [#the-request]
Each delivery is a `POST` with a JSON body and four headers:
| Header | Value |
|---|---|
| `X-OpenRoam-Webhook-Id` | The id of the webhook that delivers the event |
| `X-OpenRoam-Timestamp` | The signing time, in Unix seconds (UTC) |
| `X-OpenRoam-Event-Id` | The event id. Deduplicate by it |
| `X-OpenRoam-Signature` | The HMAC-SHA256 signature, lowercase hex |
```json
{
"eventId": "9e9ac90f-0df2-4533-a3c6-7a0dc4a6c08f",
"eventType": "order.fulfillment.updated",
"timestamp": 1770000000,
"data": {
"orderId": "3db22f3e-8a20-4e64-9f89-5ab49ef39f4d",
"origin": { "channel": "api" },
"status": "fulfillmentFailed",
"fulfillmentVersion": 2,
"items": [
{
"id": "11111111-2222-3333-4444-555555555555",
"productType": "airtime",
"fulfillment": {
"status": "rejected",
"result": null,
"failure": { "code": 11001, "name": "FULFILLMENT_REJECTED", "message": "The order item could not be fulfilled." }
}
}
]
}
}
```
The `order.fulfillment.updated` item carries `id`, `productType` and `fulfillment` only. `fulfillment.result` has the same shape as in the order read. Read the order for everything else.
## Verify the signature [#verify-the-signature]
OpenRoam signs the string `timestamp.eventId.rawBody` with your webhook's signing secret (not your API key):
```text
signature = hex(HMAC_SHA256(signingSecret, `${timestamp}.${eventId}.${rawBody}`))
```
`rawBody` is the request body exactly as received, before any JSON parsing. A minimal Node.js receiver with Express:
```ts
import crypto from 'node:crypto';
import express from 'express';
const app = express();
const secret = process.env.OPENROAM_WEBHOOK_SECRET!;
const maxDriftSeconds = 300;
// Keep the raw bytes: the signature covers the body exactly as sent.
app.post('/webhooks/openroam', express.raw({ type: '*/*' }), (req, res) => {
const timestamp = req.header('X-OpenRoam-Timestamp') ?? '';
const eventId = req.header('X-OpenRoam-Event-Id') ?? '';
const signature = (req.header('X-OpenRoam-Signature') ?? '').toLowerCase();
const age = Math.abs(Date.now() / 1000 - Number(timestamp));
if (!Number.isFinite(age) || age > maxDriftSeconds) return res.sendStatus(401);
const expected = crypto
.createHmac('sha256', secret)
.update(`${timestamp}.${eventId}.${req.body.toString('utf8')}`)
.digest('hex');
// A signature is 64 hex characters; anything else is refused before the comparison, which needs equal lengths.
const valid =
/^[0-9a-f]{64}$/.test(signature) &&
crypto.timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(signature, 'hex'));
if (!valid) return res.sendStatus(401);
const event = JSON.parse(req.body.toString('utf8'));
// Store the event, deduplicated by event.eventId, then process it in the background.
res.sendStatus(200);
});
```
The [SDKs](/docs/sdks) include a helper that verifies the signature for you.
## Delivery and retries [#delivery-and-retries]
- Delivery is **at least once**. You may receive an event more than once: deduplicate by `X-OpenRoam-Event-Id`.
- Events can arrive **out of order**, and several can arrive at the same time. For `order.fulfillment.updated`, never replace a higher `fulfillmentVersion` with a lower one.
- Answer `2xx` once you have stored the event. Process it afterwards: each attempt times out after about 60 seconds.
- Any other answer, a timeout or a network error is retried, except `410 Gone`, which stops delivery of that event for good.
- Retries wait `30s`, `2m`, `5m`, `15m`, `30m`, `1h`, `2h`, `4h`, `8h` and `12h`: up to 11 attempts over about 28 hours. Each retry has a fresh timestamp and signature.
- A `401` for a bad signature is retried too, so an event still arrives once you fix your clock or secret.
- OpenRoam support can deliver an event again on request, with the same event id and body.
The partner dashboard shows the delivery history of each webhook, with every attempt and its result.
## Test deliveries [#test-deliveries]
From the dashboard you can send a test event to a webhook. It arrives like a real event, with the usual headers and signature, and a top-level `"isTest": true` in the body. Verify it as usual, acknowledge it with `2xx`, and keep it out of your business processing.
## Events and the order read [#events-and-the-order-read]
An event is a snapshot of the moment it was sent. The order read always returns the current state, so read the order when you need the full picture. Refunds and amendments have their own events and do not change `fulfillmentVersion`, with two exceptions: the confirmed cancellation of a delivered item, and the completed refund that moves the order to `partiallyRefunded` or `refunded`. Both also send `order.fulfillment.updated`.
# API reference (/docs/api-reference)
This reference is generated from the Partner API [OpenAPI specification](/openapi.json). Each page shows an operation's parameters, request body, responses and code samples.
- **Base URLs:** `https://api.sandbox.openroam.com` (Sandbox) and `https://api.openroam.com` (Production). Every path starts with `/v1`. Code samples use Sandbox.
- **Authentication:** the `X-Partner-Key` header on every request. See [Authentication](/docs/authentication).
- **Errors:** every error has the body described in [Errors](/docs/errors).
## Shared [#shared]
| Section | Covers |
|---|---|
| [Account](/docs/api-reference/account/get-services) | The products enabled for your account |
| [Orders](/docs/api-reference/orders/create-order) | Mixed orders and quotes, reading orders, cancellation previews, email resend |
| [Order items](/docs/api-reference/order-items/get-by-id) | Reading, cancelling, updating and amending what you bought |
| [Wallets](/docs/api-reference/wallets/get-all) | Wallet balances, transactions and transfers |
| [Currencies](/docs/api-reference/currencies/get-all) | Supported currencies and their rates |
| [Reference data](/docs/api-reference/common/get-countries) | Countries and mobile network codes |
## Products [#products]
| Section | Guide |
|---|---|
| [eSIMs](/docs/api-reference/esims/search) | [eSIMs guide](/docs/products/esims) |
| [Airtime](/docs/api-reference/airtime/search) | [Airtime guide](/docs/products/airtime) |
| [Utility](/docs/api-reference/utility/search) | [Utility guide](/docs/products/utility) |
| [Gift cards](/docs/api-reference/gift-cards/search) | [Gift cards guide](/docs/products/gift-cards) |
| [Hotels](/docs/api-reference/hotels/search) and [hotel manual amendments](/docs/api-reference/hotel-manual-amendments/create-manual-amendment) | [Hotels guide](/docs/products/hotels) |
| [Flights](/docs/api-reference/flights/search) | [Flights guide](/docs/products/flights) |
## Webhook events [#webhook-events]
The [webhook events](/docs/api-reference/webhooks/order-fulfillment-updated) section documents the body of every event OpenRoam sends. See [Webhooks](/docs/webhooks) for signatures and delivery.
# List account services (/docs/api-reference/account/get-services)
`GET /v1/account/services`
Lists every service OpenRoam sells through the Partner API, with whether the account may sell it.
Returns `{ services }`, one entry per service, ordered by `productType`, without paging. Each entry is
`{ productType, enabled, requestable }`. `enabled` is `true` when the account may search, quote
and order the service now; any other request that sells it returns `403` with code `10003`.
`requestable` is `true` when the account can ask OpenRoam to enable the service; an enabled service is
never requestable. A service OpenRoam does not offer at the moment is not listed. The endpoint takes no query
parameters; an unknown parameter returns `400` with code `10001`.
## Responses
### 200
OK
- `text/plain`: `AccountServiceList`
- `application/json`: `AccountServiceList`
- `text/json`: `AccountServiceList`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 401
Unauthorized
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Airtime catalog (/docs/api-reference/airtime/catalog)
`GET /v1/airtime/catalog`
Returns the operator directory, page by page, for partner inventory.
Returns `{ items: [{ id, name, countryCode, category, logoUrl }], nextCursor }`, ordered by operator ID.
Pass `nextCursor` back as `cursor` with the same `countryCode` until it is null; a page can hold
fewer items than `limit`, and the cursor does not expire. A cursor reused with another `countryCode`,
or a blank or invalid `countryCode`, gives 400 / 10001. Offers are not exported: they depend on whether
the operator is detected or chosen, so read them with `operators/{id}?phoneNumber=`.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `countryCode` | query | no | `string` | Optional ISO 3166-1 alpha-2 country filter, in either case; every country when omitted. A blank or invalid value gives 400 / 10001. |
| `cursor` | query | no | `string` | The `nextCursor` of the previous page; omit it for the first page. Reuse it only with the same `countryCode`. |
| `limit` | query | no | `integer` | Page size, 1 to 100; default 100. |
## Responses
### 200
OK
- `text/plain`: `AirtimeCatalogPage`
- `application/json`: `AirtimeCatalogPage`
- `text/json`: `AirtimeCatalogPage`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Search airtime by phone number (/docs/api-reference/airtime/search)
`GET /v1/airtime/search`
Searches for a phone number's operator by carrier lookup and returns it with its offers (detected flow).
Returns `{ items, pagination, details: { phoneLookup: { status, carrierName, countryCode } } }`.
`items` holds at most the detected operator with its offers. It is empty when `status` is not
`detected` or no offer remains after the filters; then let the customer choose the operator with
`GET operators?countryCode=`, using `details.phoneLookup.countryCode`. Each call makes exactly one
carrier lookup and returns at most one item, so `page` must be 1. A `phoneNumber` that is not in
international format gives 400 / 10001; a carrier lookup that fails gives 503 / 10007, retry later.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `phoneNumber` | query | yes | `string` | The recipient's number in international format, starting with + or 00; spaces, hyphens and parentheses are allowed. |
| `valueType` | query | no | `string` | Keep only `fixed` or only `range` offers. |
| `valueCurrency` | query | no | `string` | Currency of `minValue` and `maxValue`, three letters; required with either of them. |
| `minValue` | query | no | `number` | Keep the offers whose value reaches at least this amount, in `valueCurrency`. |
| `maxValue` | query | no | `number` | Keep the offers whose value starts at or below this amount, in `valueCurrency`. |
| `minPrice` | query | no | `number` | Keep the offers whose indicative price reaches at least this amount, in the price currency. |
| `maxPrice` | query | no | `number` | Keep the offers whose indicative price starts at or below this amount, in the price currency. A filter, not the `inputs.maxPrice` limit of a purchase. |
| `currency` | query | no | `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` | query | no | `integer` | Must be 1: search returns at most one operator. |
| `limit` | query | no | `integer` | Page size, 1 to 100; default 10. |
## Responses
### 200
OK
- `text/plain`: `AirtimeSearchResult`
- `application/json`: `AirtimeSearchResult`
- `text/json`: `AirtimeSearchResult`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Look up a phone number (/docs/api-reference/airtime/lookup-number)
`GET /v1/airtime/number-lookup`
Describes a phone number and returns its carrier from a carrier lookup when the number is valid.
Describes the number from numbering-plan data and, for a valid number, adds carrier information from a live
carrier lookup. A number without the international shape gives 400 / 10001; a number its country does not
assign returns 200 with `isValid: false` and `carrier: null`, without a carrier lookup. Returns
503 / 10007 when the carrier lookup is unavailable. The carrier is for display only and nothing is stored; use
search to find a sellable operator.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `phoneNumber` | query | yes | `string` | The number in international format, starting with + or 00; spaces, hyphens and parentheses are allowed. |
## Responses
### 200
OK
- `text/plain`: `NumberLookup`
- `application/json`: `NumberLookup`
- `text/json`: `NumberLookup`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
### 503
Service Unavailable
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# List airtime operators (/docs/api-reference/airtime/get-operators)
`GET /v1/airtime/operators`
Lists the operators of a country that the customer can choose manually (manual flow, step 1).
Returns the complete list, without paging or prices, as
`{ items: [{ id, name, countryCode, category, logoUrl }] }`, ordered by name. Only operators with an
offer that can be sold for a chosen operator are listed. An invalid `countryCode` gives 400 / 10001.
Continue with `operators/{id}?phoneNumber=`.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `countryCode` | query | yes | `string` | Required ISO 3166-1 alpha-2 country code, in either case, for example the `details.phoneLookup.countryCode` of a search. |
## Responses
### 200
OK
- `text/plain`: `AirtimeOperatorList`
- `application/json`: `AirtimeOperatorList`
- `text/json`: `AirtimeOperatorList`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Get an airtime operator (/docs/api-reference/airtime/get-operator)
`GET /v1/airtime/operators/{id}`
Returns one operator with its offers for a phone number of its country (manual flow, step 2).
Returns the operator in the item shape that search returns, without a carrier lookup. A number of another
country than the operator's gives 400 / 10001 with `COUNTRY_MISMATCH` at `phoneNumber`. An unknown
ID, including any value that is not an operator ID, or an operator without an orderable offer, gives
404 / 10004. Offer filters that match none of the operator's offers leave `offers` empty. A manual choice
is not checked against the number's carrier, so have the customer confirm the operator before ordering.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `id` | path | yes | `string` | The operator ID (`operator_…`) from the operator list, the catalog or search. |
| `phoneNumber` | query | yes | `string` | The recipient's number in international format, starting with + or 00. It must belong to the operator's country. |
| `valueType` | query | no | `string` | Keep only `fixed` or only `range` offers. |
| `valueCurrency` | query | no | `string` | Currency of `minValue` and `maxValue`, three letters; required with either of them. |
| `minValue` | query | no | `number` | Keep the offers whose value reaches at least this amount, in `valueCurrency`. |
| `maxValue` | query | no | `number` | Keep the offers whose value starts at or below this amount, in `valueCurrency`. |
| `minPrice` | query | no | `number` | Keep the offers whose indicative price reaches at least this amount, in the price currency. |
| `maxPrice` | query | no | `number` | Keep the offers whose indicative price starts at or below this amount, in the price currency. A filter, not the `inputs.maxPrice` limit of a purchase. |
| `currency` | query | no | `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`. |
## Responses
### 200
OK
- `text/plain`: `AirtimeOperator`
- `application/json`: `AirtimeOperator`
- `text/json`: `AirtimeOperator`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Quote airtime (/docs/api-reference/airtime/quote)
`POST /v1/airtime/quote`
Prices the order body with current prices, without placing an order.
Takes the same body as order and resolves the number's operator as the order does, with a carrier lookup per
item. Each item is priced on its own, in request order; the first failing item aborts the quote and is named at
`items[i]`, for example 409 / 11002 at `items[i].inputs.maxPrice` when the current price is above
it. 409 / 20000 means the lookup shows that the offer's operator cannot be the number's: search again. A
carrier lookup that fails gives 503 / 10007. A quote reserves nothing and does not expire; to hold the quoted
price, send it as `inputs.maxPrice` in the order.
## Request body
- `application/json`: `AirtimeOrderRequest`
- `text/json`: `AirtimeOrderRequest`
- `application/*+json`: `AirtimeOrderRequest`
## Responses
### 200
OK
- `text/plain`: `AirtimeQuote`
- `application/json`: `AirtimeQuote`
- `text/json`: `AirtimeQuote`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 409
Conflict
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Order airtime (/docs/api-reference/airtime/create-order)
`POST /v1/airtime/order`
Places an airtime top-up 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. The number's operator is looked up again, as in quote; item errors are named
at `items[i]`, and a current price above `inputs.maxPrice` gives 409 / 11002 before anything is
charged. Track fulfillment with 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.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | yes | `string` | UUID idempotency key for safe retries of this operation. |
## Request body
- `application/json`: `AirtimeOrderRequest`
- `text/json`: `AirtimeOrderRequest`
- `application/*+json`: `AirtimeOrderRequest`
## Responses
### 200
OK
- `text/plain`: `AirtimeOrder`
- `application/json`: `AirtimeOrder`
- `text/json`: `AirtimeOrder`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 402
Payment Required
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 409
The offer changed since it was quoted: its price rose (11002, for products that check the quoted price) or it is no longer available (11003). Or the idempotency key: a request with this key is still running (12002): send the same request, key and body again after Retry-After seconds; it was used for a different request (12001); or its history is ambiguous.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
### 503
Idempotency state is temporarily unavailable; retry the same request and key.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# List countries (/docs/api-reference/common/get-countries)
`GET /v1/common/countries`
Lists every country and territory with its codes, English name, calling code and flag.
Returns `{ items }`, the whole list ordered by `countryCode`, without paging. `countryCode` is
the ISO 3166-1 alpha-2 code every service filters and reports by. The endpoint takes no query parameters; an
unknown parameter returns `400` with code `10001`.
## Responses
### 200
OK
- `text/plain`: `CountryList`
- `application/json`: `CountryList`
- `text/json`: `CountryList`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# List mobile networks (/docs/api-reference/common/get-mobile-networks)
`GET /v1/common/mccmnc`
Lists mobile network codes (MCC/MNC) with their operator, country and calling code.
Returns `{ items }` ordered by `mcc` then `mnc`, without paging. Optional filters:
`countryCode` (ISO 3166-1 alpha-2, either case) and `mcc` (3 digits); both together return the
networks matching both. A malformed filter or an unknown query parameter returns `400` with code
`10001`.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `countryCode` | query | no | `string` | Only networks of this country: an ISO 3166-1 alpha-2 code, in either case. |
| `mcc` | query | no | `string` | Only networks with this 3-digit mobile country code, for example `400`. |
## Responses
### 200
OK
- `text/plain`: `MobileNetworkList`
- `application/json`: `MobileNetworkList`
- `text/json`: `MobileNetworkList`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# List currencies (/docs/api-reference/currencies/get-all)
`GET /v1/currencies`
Lists every supported currency with its current rate to USD.
Returns `{ currencies }`, the whole list without paging. Use a currency's `code` wherever a
request takes a `currency`, and its `id` as `currencyId` when creating a wallet.
`rateToUsd` is the USD value of one unit of the currency, as of `rateDate`.
## Responses
### 200
OK
- `text/plain`: `CurrencyList`
- `application/json`: `CurrencyList`
- `text/json`: `CurrencyList`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Search eSIM plans (/docs/api-reference/esims/search)
`GET /v1/esims/search`
Searches eSIM destinations and returns them with their plans, one page at a time.
Returns `{ items, pagination }`. `countryCode` keeps the destinations whose coverage includes that
country, so local, regional and global destinations can match; `category` and `region` select
destinations, and `validityDays` and `isUnlimited` select plans within them. Pages count destinations
with an orderable plan. With `iccid` it returns the plans that can top up that eSIM instead, under its
destination, and takes no filter other than `currency` (400 / 10001, `NOT_ALLOWED`); an unknown or
foreign ICCID gives 404 / 10004. Prices are indicative, in `currency`.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `countryCode` | query | no | `string` | Optional ISO 3166-1 alpha-2 country, in either case: keeps the destinations whose coverage includes it, regional and global ones too. A blank value is rejected. |
| `category` | query | no | `string` | Keep `local`, `regional` or `global` destinations. |
| `region` | query | no | `string` | Keep the destinations of this region, in display or slug form, for example `North America` or `north-america`. |
| `validityDays` | query | no | `integer` | Keep the plans valid for exactly this many days; at least 1. |
| `isUnlimited` | query | no | `boolean` | Keep the unlimited (`true`) or the limited (`false`) plans. |
| `iccid` | query | no | `string` | Top-up search: the ICCID (18 to 22 digits) of your eSIM to list the plans that can top it up. No other filter than `currency` is allowed with it. |
| `currency` | query | no | `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` | query | no | `integer` | Page number, from 1; default 1. |
| `limit` | query | no | `integer` | Page size, 1 to 100; default 10. |
## Responses
### 200
OK
- `text/plain`: `EsimSearchResult`
- `application/json`: `EsimSearchResult`
- `text/json`: `EsimSearchResult`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 404
Not Found
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# List eSIM destinations (/docs/api-reference/esims/get-destinations)
`GET /v1/esims/destinations`
Lists every destination with an orderable plan, as summaries without plans.
Returns the complete list `{ items }`, ordered by name, without paging or prices. Read a destination's plans
with `destinations/{id}`.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `category` | query | no | `string` | Filter by category: local, regional or global. |
| `region` | query | no | `string` | Filter by region name (e.g. "Europe", "North America"), in display or slug form. |
## Responses
### 200
OK
- `text/plain`: `EsimDestinationList`
- `application/json`: `EsimDestinationList`
- `text/json`: `EsimDestinationList`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Get an eSIM destination (/docs/api-reference/esims/get-destination)
`GET /v1/esims/destinations/{id}`
Returns one destination with its plans, in the item shape that search returns.
An unknown ID, or a destination that search does not list, gives 404 / 10004. After a purchase, the order item's
`purchasedProduct.details.destination.id` gives the coverage of the destination the eSIM was bought for.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `id` | path | yes | `string` | The destination `id` from search, the destination list or the catalog. |
| `currency` | query | no | `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`. |
## Responses
### 200
OK
- `text/plain`: `EsimDestination`
- `application/json`: `EsimDestination`
- `text/json`: `EsimDestination`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# eSIM catalog (/docs/api-reference/esims/get-catalog)
`GET /v1/esims/catalog`
Returns every destination with its plans, page by page, for partner inventory.
Returns `{ items, nextCursor }`, in a fixed order, with the search filters except `iccid`.
Continue with `nextCursor` as `cursor`, the same filters and the same `currency` until it is
null. A cursor reused with other filters or another currency gives 400 / 10001. Quote confirms the final price
and availability.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `countryCode` | query | no | `string` | Optional ISO 3166-1 alpha-2 country, in either case: keeps the destinations whose coverage includes it, regional and global ones too. A blank value is rejected. |
| `category` | query | no | `string` | Keep `local`, `regional` or `global` destinations. |
| `region` | query | no | `string` | Keep the destinations of this region, in display or slug form, for example `North America` or `north-america`. |
| `validityDays` | query | no | `integer` | Keep the plans valid for exactly this many days; at least 1. |
| `isUnlimited` | query | no | `boolean` | Keep the unlimited (`true`) or the limited (`false`) plans. |
| `currency` | query | no | `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`. |
| `cursor` | query | no | `string` | The `nextCursor` of the previous page; omit it for the first page. Reuse it only with the same filters and currency. |
| `limit` | query | no | `integer` | Page size, 1 to 100; default 100. |
## Responses
### 200
OK
- `text/plain`: `EsimCatalogPage`
- `application/json`: `EsimCatalogPage`
- `text/json`: `EsimCatalogPage`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# List compatible devices (/docs/api-reference/esims/get-compatible-devices)
`GET /v1/esims/compatible-devices`
Lists the devices known to support eSIM.
Returns an array of `{ brand, model, os, deviceType, name, notes }`, without paging.
## Responses
### 200
OK
- `text/plain`: `EsimCompatibleDevice[]`
- `application/json`: `EsimCompatibleDevice[]`
- `text/json`: `EsimCompatibleDevice[]`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Order eSIMs (/docs/api-reference/esims/create-order)
`POST /v1/esims/order`
Places an order for new eSIMs or a top-up 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.
A top-up is an offer from `search?iccid=` ordered with `inputs.iccid` and quantity 1; without
`inputs.iccid` the same offer is bought as a new eSIM. A new eSIM is instant unless `inputs.isInstant`
is false, which delivers an entitlement to provision later. Every price is recalculated: a current price above
`inputs.maxPrice` gives 409 / 11002 before anything is charged. 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. An unknown or foreign
`inputs.iccid` gives 404 / 10004 and charges nothing.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | yes | `string` | UUID idempotency key for safe retries of this operation. |
## Request body
- `application/json`: `EsimOrderRequest`
- `text/json`: `EsimOrderRequest`
- `application/*+json`: `EsimOrderRequest`
## Responses
### 200
OK
- `text/plain`: `EsimOrder`
- `application/json`: `EsimOrder`
- `text/json`: `EsimOrder`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 402
Payment Required
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 404
Not Found
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 409
The offer changed since it was quoted: its price rose (11002, for products that check the quoted price) or it is no longer available (11003). Or the idempotency key: a request with this key is still running (12002): send the same request, key and body again after Retry-After seconds; it was used for a different request (12001); or its history is ambiguous.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
### 503
Idempotency state is temporarily unavailable; retry the same request and key.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Quote eSIMs (/docs/api-reference/esims/quote)
`POST /v1/esims/quote`
Prices the order body with current prices, without placing an order.
Takes the same body as order and, as the order does, checks each item completely (its inputs, its
`publicId` and its price) before the next one, in request order. The first failure aborts the quote, and an
item error is named at `items[i]`, for example 409 / 11002 at `items[i].inputs.maxPrice` when the
current price is above it. An eSIM has no monetary value, so `inputs.value` is an unknown member
(400 / 10001). An unknown or foreign `inputs.iccid` gives 404 / 10004. A quote reserves nothing and does
not expire.
## Request body
- `application/json`: `EsimOrderRequest`
- `text/json`: `EsimOrderRequest`
- `application/*+json`: `EsimOrderRequest`
## Responses
### 200
OK
- `text/plain`: `EsimQuote`
- `application/json`: `EsimQuote`
- `text/json`: `EsimQuote`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 404
Not Found
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 409
Conflict
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Get an eSIM (/docs/api-reference/esims/get-esim)
`GET /v1/esims/{iccid}/profile`
Returns one of your eSIMs by its ICCID, with its installation details, plan and top-ups.
Returns the eSIM as last recorded, without a live refresh: `esimStatus` and `profileStatus` as the
order item names them, the SIM details (LPA code, QR code URL and quick-install links), the plan, its data
(MB), SMS (messages) and voice (minutes) allowances, any top-ups, and `expiresAt`, null until the eSIM is
activated. An ICCID that is not one of your eSIMs gives 404 / 10004.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `iccid` | path | yes | `string` | The eSIM's ICCID, from the order item's `fulfillment.result.details.iccid`. |
## Responses
### 200
OK
- `text/plain`: `EsimProfile`
- `application/json`: `EsimProfile`
- `text/json`: `EsimProfile`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 401
Unauthorized
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 404
Not Found
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
### 500
Internal Server Error
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Get eSIM usage (/docs/api-reference/esims/get-usage)
`GET /v1/esims/{iccid}/usage`
Returns the current data, SMS and voice usage of an eSIM.
Reads the live usage when the request is made and returns `esimStatus`, `profileStatus` and the allowed
and remaining data (MB), SMS (messages) and voice (minutes), including top-ups. An amount is null when it is
unlimited (`isDataUnlimited`, `isSmsUnlimited`, `isVoiceUnlimited`), not reported or not
included. When the usage cannot be read live, or the plan does not report live usage, it returns the last known
usage. An ICCID that is not one of your eSIMs gives 404 / 10004.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `iccid` | path | yes | `string` | The eSIM's ICCID, from the order item's `fulfillment.result.details.iccid`. |
## Responses
### 200
OK
- `text/plain`: `EsimCurrentUsage`
- `application/json`: `EsimCurrentUsage`
- `text/json`: `EsimCurrentUsage`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 401
Unauthorized
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 404
Not Found
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
### 500
Internal Server Error
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Get eSIM usage by day (/docs/api-reference/esims/get-usage-details)
`GET /v1/esims/{iccid}/usage/details`
Returns the current usage of an eSIM with a per-day breakdown.
Returns the same summary as `usage` plus `usages`, the per-day consumption entries
`{ date, usage, location }` with the data used in MB and `location` null when no country was reported.
`usages` is empty when the eSIM's plan does not report a per-day breakdown or it cannot be read.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `iccid` | path | yes | `string` | The eSIM's ICCID, from the order item's `fulfillment.result.details.iccid`. |
## Responses
### 200
OK
- `text/plain`: `EsimDailyUsage`
- `application/json`: `EsimDailyUsage`
- `text/json`: `EsimDailyUsage`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 401
Unauthorized
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 404
Not Found
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
### 500
Internal Server Error
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# List eSIM usage history (/docs/api-reference/esims/get-usage-history)
`GET /v1/esims/{iccid}/usage/history`
Lists the recorded usage readings of an eSIM, newest first.
Returns `{ items, pagination }`, one item per usage reading, with its allowances, remaining amounts and
usage and expiry bands. `from` and `to` limit the readings by `capturedAt`, both inclusive. An
ICCID that is not one of your eSIMs gives 404 / 10004.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `iccid` | path | yes | `string` | The eSIM's ICCID, from the order item's `fulfillment.result.details.iccid`. |
| `page` | query | no | `integer` | Page number, from 1; default 1. |
| `limit` | query | no | `integer` | Page size, 1 to 100; default 10. |
| `from` | query | no | `string` | Only readings captured at or after this UTC time. ISO 8601 date-time. A value with Z or an offset is converted to UTC; a value without a zone is read as UTC, and a date alone means 00:00 UTC on that day. |
| `to` | query | no | `string` | Only readings captured at or before this UTC time. ISO 8601 date-time. A value with Z or an offset is converted to UTC; a value without a zone is read as UTC, and a date alone means 00:00 UTC on that day. |
## Responses
### 200
OK
- `text/plain`: `EsimUsageReadingList`
- `application/json`: `EsimUsageReadingList`
- `text/json`: `EsimUsageReadingList`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 401
Unauthorized
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 404
Not Found
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# List eSIM status events (/docs/api-reference/esims/get-status-events)
`GET /v1/esims/{iccid}/status-events`
Lists the status changes of an eSIM, newest first.
Returns `{ items, pagination }`, one item per status change with `esimStatus`, `profileStatus` and
`occurredAt`. `from` and `to` limit the events by
`occurredAt`, both inclusive. An ICCID that is not one of your eSIMs gives 404 / 10004.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `iccid` | path | yes | `string` | The eSIM's ICCID, from the order item's `fulfillment.result.details.iccid`. |
| `page` | query | no | `integer` | Page number, from 1; default 1. |
| `limit` | query | no | `integer` | Page size, 1 to 100; default 10. |
| `from` | query | no | `string` | Only events that occurred at or after this UTC time. ISO 8601 date-time. A value with Z or an offset is converted to UTC; a value without a zone is read as UTC, and a date alone means 00:00 UTC on that day. |
| `to` | query | no | `string` | Only events that occurred at or before this UTC time. ISO 8601 date-time. A value with Z or an offset is converted to UTC; a value without a zone is read as UTC, and a date alone means 00:00 UTC on that day. |
## Responses
### 200
OK
- `text/plain`: `EsimStatusEventList`
- `application/json`: `EsimStatusEventList`
- `text/json`: `EsimStatusEventList`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 401
Unauthorized
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 404
Not Found
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# List eSIM location events (/docs/api-reference/esims/get-location-events)
`GET /v1/esims/{iccid}/location-events`
Lists the networks and locations where an eSIM registered, newest first.
Returns `{ items, pagination }`, one item per registration with its MCC, MNC, location, network and
`occurredAt`. `from` and `to` limit the events by `occurredAt`, both inclusive. An ICCID that
is not one of your eSIMs gives 404 / 10004.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `iccid` | path | yes | `string` | The eSIM's ICCID, from the order item's `fulfillment.result.details.iccid`. |
| `page` | query | no | `integer` | Page number, from 1; default 1. |
| `limit` | query | no | `integer` | Page size, 1 to 100; default 10. |
| `from` | query | no | `string` | Only events that occurred at or after this UTC time. ISO 8601 date-time. A value with Z or an offset is converted to UTC; a value without a zone is read as UTC, and a date alone means 00:00 UTC on that day. |
| `to` | query | no | `string` | Only events that occurred at or before this UTC time. ISO 8601 date-time. A value with Z or an offset is converted to UTC; a value without a zone is read as UTC, and a date alone means 00:00 UTC on that day. |
## Responses
### 200
OK
- `text/plain`: `EsimLocationEventList`
- `application/json`: `EsimLocationEventList`
- `text/json`: `EsimLocationEventList`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 401
Unauthorized
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 404
Not Found
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Provision a deferred eSIM (/docs/api-reference/esims/provision)
`POST /v1/esims/{id}/provisioning`
Provisions a deferred eSIM bought with `inputs.isInstant: false` and returns it.
Creates the eSIM for an order item that delivered an entitlement, and returns it as `GET /esims/{iccid}`
does. The item's result moves to `provisioning.status` `processing` and then `ready`, and each
change sends an `order.fulfillment.updated` webhook. An `Idempotency-Key` header with a UUID is
required: a retry with the same key and body after the call finished returns the eSIM as it reads now and starts
nothing again, 409 / 12002 with `Retry-After` while the call is still running, and a changed body gives
409 / 12001. The optional body
`{ travelStartDate }` is needed when the plan requires the first day of travel and the order did not send
it (400 / 10001 without it); a date other than the one recorded, or a new date once provisioning has started,
gives 409 / 10005. An instant eSIM gives 400 / 10001, and an ID that names no eSIM purchase of yours, such as a
top-up item, gives 404 / 10004.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `id` | path | yes | `string` | The order item ID of the deferred eSIM purchase. |
| `Idempotency-Key` | header | yes | `string` | UUID idempotency key for safe retries of this operation. |
## Request body
- `application/json`: `EsimProvisioningRequest`
- `text/json`: `EsimProvisioningRequest`
- `application/*+json`: `EsimProvisioningRequest`
## Responses
### 200
OK
- `text/plain`: `EsimProfile`
- `application/json`: `EsimProfile`
- `text/json`: `EsimProfile`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 403
Forbidden
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 404
Not Found
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 409
The idempotency key: a request with this key is still running (12002): send the same request, key and body again after Retry-After seconds; or it was used for a different request (12001). A finished request sent again with the same key and body returns 200 with the result of the first call, rebuilt from the record that call created as it reads now: nothing runs again, and a status that has moved on since shows its current value.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
### 503
Idempotency state is temporarily unavailable; retry the same request and key.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Send an SMS to an eSIM (/docs/api-reference/esims/send-sms)
`POST /v1/esims/{iccid}/sms`
Sends a text message to one of your eSIMs.
Takes `{ message }`, which must not be empty, and returns `{ iccid }` only when the message was sent.
An eSIM whose plan cannot be sent messages this way gives 422 / 22000 (`ESIM_SMS_NOT_SUPPORTED`); do not
retry it. A message that was not sent gives 502 / 10008. An ICCID that is not one of your eSIMs gives
404 / 10004.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `iccid` | path | yes | `string` | The eSIM's ICCID, from the order item's `fulfillment.result.details.iccid`. |
## Request body
- `application/json`: `EsimSmsRequest`
- `text/json`: `EsimSmsRequest`
- `application/*+json`: `EsimSmsRequest`
## Responses
### 200
OK
- `text/plain`: `EsimSmsResult`
- `application/json`: `EsimSmsResult`
- `text/json`: `EsimSmsResult`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 403
Forbidden
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 404
Not Found
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 422
Unprocessable Content
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
### 502
Bad Gateway
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Search flights (/docs/api-reference/flights/search)
`POST /v1/flights/search`
Searches flight itineraries and the fares bookable on them.
Send one slice per flight (one for one-way, two for a return, more for a multi-city trip) and every passenger;
at least one passenger must be an `adult`, and children and infants need an `age`. Optional
`filters`: `maxStops`, `preferredAirlines` and `excludedAirlines` select itineraries;
`refundableOnly` and `maxPrice` select fares, and an itinerary left without a fare is not returned.
The body rejects an unknown field at every level, and the route takes no query parameters.
Returns `{ items, pagination }`. Each item is one itinerary, the same flights sold by the same airline, with
its fares as `offers`, cheapest first; items are ordered by their cheapest fare, then total duration.
`page` and `limit` (defaults 1 and 10, `limit` at most 100) page through itineraries, and
`pagination.totalCount` counts them. Each page runs a new airline search, so fares can change between pages.
An item's `id` is valid only within this response and cannot be ordered; quote and order an offer's
`publicId` before its `details.expiresAt`. Prices are for all passengers, in `currency` or the API
key's currency, and are indicative.
Errors: an invalid or unknown field, or a query parameter, 400 / 10001; an unsupported `currency`
404 / 10004.
## Request body
- `application/json`: `FlightSearchRequest`
- `text/json`: `FlightSearchRequest`
- `application/*+json`: `FlightSearchRequest`
## Responses
### 200
OK
- `text/plain`: `FlightSearchResult`
- `application/json`: `FlightSearchResult`
- `text/json`: `FlightSearchResult`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Quote flights (/docs/api-reference/flights/quote)
`POST /v1/flights/quote`
Prices flight fares again with the airline, without placing an order.
Takes the same body as order: `{ currency, referenceId, items[] }` with 1 to 5 items, each
`{ publicId, quantity, inputs }` and `quantity` 1. `inputs` may be left out: the quote then prices
the fare alone. Inputs that are sent are checked as the order checks them, and their paid extras are added to
the price. Prices are in `currency`, or in the API key's currency when it is omitted. Nothing is charged or
held.
Returns `{ currency, items, total }`. Each item has a new `publicId`: order with it before
`details.expiresAt`. It keeps the fare's price, which caps an order without `inputs.maxPrice`.
`details` carries the fare's conditions, included baggage and price breakdown, `hasSeatMaps`, the paid
extras (`availableServices`) that can be sent in the order's `inputs.selectedServices`, and
`fareOptions`: the fares for the same flights and airline, cheapest first and including the quoted one, each
with its own `publicId` that can be quoted or ordered.
A higher airline price is returned with 200; only `inputs.maxPrice` stops a quote. Each item is checked
completely, its inputs, its `publicId` and its price, before the next one, and the first failure names its
item: an invalid input or a `quantity` other than 1 gives 400 / 10001 at its path under `items[i]`; a
price above `inputs.maxPrice` 409 / 11002 at `items[i].inputs.maxPrice`; an offer the airline no
longer sells 409 / 11003 at `items[i]`; an unknown, expired or another partner's `publicId`, or a
search itinerary `id`, 400 / 11004 at `items[i]`. An unsupported `currency` gives 400 / 10001 at
`currency`.
## Request body
- `application/json`: `FlightOrderRequest`
- `text/json`: `FlightOrderRequest`
- `application/*+json`: `FlightOrderRequest`
## Responses
### 200
OK
- `text/plain`: `FlightQuote`
- `application/json`: `FlightQuote`
- `text/json`: `FlightQuote`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 409
Conflict
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Order flights (/docs/api-reference/flights/create-order)
`POST /v1/flights/order`
Places and pays for flight bookings, one fare per item.
Takes the same body as quote, with `inputs` required. 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 ticketing completes asynchronously: track it with `GET /orders/{id}` or the
`order.fulfillment.updated` webhook.
`publicId` is a fare's `publicId` from search, or one that a quote returned. `inputs.passengers`
lists every passenger of the fare exactly once, in `passengerIndex` order 1 to N, optionally with seats in
`selectedSeats`; paid baggage and other services go in `inputs.selectedServices`. Seats and services
are checked against the airline's current offer and seat map, and their prices are added to the item's price.
Each item is priced again with the airline before payment, and the price is capped. With the optional
`inputs.maxPrice`, in the order currency, a higher price for the item (the fare with its paid extras) gives
409 / 11002 at `items[i].inputs.maxPrice`. Without it, the fare may not cost more than the price returned
with the `publicId` (409 / 11002 at `items[i]`), and the order must be in the currency of that price
(400 / 11005 at `items[i]`).
A `publicId` keeps that price: after 409 / 11002, quote again and order with the `publicId` the quote
returns, or send `inputs.maxPrice`.
Each item is checked completely before the next one, and the first failure names its item: an invalid input or
missing `inputs` gives 400 / 10001 at its path under `items[i]`, for example
`items[0].inputs.passengers[0].email`; an unknown, expired or another partner's `publicId`
400 / 11004 at `items[i]`; an offer the airline no longer sells 409 / 11003 at `items[i]`. 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.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | yes | `string` | UUID idempotency key for safe retries of this operation. |
## Request body
- `application/json`: `FlightOrderRequest`
- `text/json`: `FlightOrderRequest`
- `application/*+json`: `FlightOrderRequest`
## Responses
### 200
OK
- `text/plain`: `FlightOrder`
- `application/json`: `FlightOrder`
- `text/json`: `FlightOrder`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 402
Payment Required
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 409
The offer changed since it was quoted: its price rose (11002, for products that check the quoted price) or it is no longer available (11003). Or the idempotency key: a request with this key is still running (12002): send the same request, key and body again after Retry-After seconds; it was used for a different request (12001); or its history is ambiguous.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
### 503
Idempotency state is temporarily unavailable; retry the same request and key.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Get a flight seat map (/docs/api-reference/flights/get-seat-map)
`GET /v1/flights/offers/{publicId}/seat-map`
Returns the seat map of a flight offer, with the seats each passenger can take and their prices.
The seat map is read from the airline on each call, so availability can change between calls; prices are in
the API key's currency. `isSupported` is false when the airline offers no seat selection for the offer.
Segments are named by `sliceIndex` and `segmentIndex`, their 1-based position in the offer; a
segment without a seat map is left out. A seat can be booked only for the passengers in its
`availableFor`. Send chosen seats in the order's `inputs.passengers[].selectedSeats`, one per
passenger per segment. An unknown, expired or another partner's `publicId` returns 400 / 11004.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `publicId` | path | yes | `string` | An offer or fare option `publicId` from search or quote. |
## Responses
### 200
OK
- `text/plain`: `SeatMap`
- `application/json`: `SeatMap`
- `text/json`: `SeatMap`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# List gift card categories (/docs/api-reference/gift-cards/get-categories)
`GET /v1/giftcards/categories`
Lists the gift card categories with their display names.
Returns the complete list `{ items: [{ category, name }] }`, without paging. Use a `category` value to
filter search and the catalog. The route takes no query parameters.
## Responses
### 200
OK
- `text/plain`: `GiftCardCategoryList`
- `application/json`: `GiftCardCategoryList`
- `text/json`: `GiftCardCategoryList`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Search gift cards (/docs/api-reference/gift-cards/search)
`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`.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `countryCode` | query | no | `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` | query | no | `string` | Keep the cards of this category; `categories` lists the values. |
| `valueType` | query | no | `string` | Keep only `fixed` or only `range` offers; a card left without an offer is dropped. |
| `q` | query | no | `string` | Brand name or card ID, case-insensitive; at most 100 characters, without control characters. |
| `isRedeemableGlobally` | query | no | `boolean` | `true` keeps only cards that can be redeemed in any country. |
| `currency` | query | no | `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` | query | no | `integer` | Page number, from 1; default 1. |
| `limit` | query | no | `integer` | Page size, 1 to 100; default 10. |
## Responses
### 200
OK
- `text/plain`: `GiftCardSearchResult`
- `application/json`: `GiftCardSearchResult`
- `text/json`: `GiftCardSearchResult`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Gift card catalog (/docs/api-reference/gift-cards/get-catalog)
`GET /v1/giftcards/catalog`
Returns every gift card with its offers, page by page, for partner inventory.
Returns `{ items, nextCursor }`, ordered by card ID, with the search filters except `q`. Continue with
`nextCursor` as `cursor`, the same filters and the same `currency` until it is null; a page can
hold fewer cards than `limit`, even none, while `nextCursor` is not null. A cursor reused with other
filters or another currency gives 400 / 10001. The walk is not a frozen snapshot: a card that appears or
disappears during it may be missing. Quote confirms the final price and availability.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `countryCode` | query | no | `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` | query | no | `string` | Keep the cards of this category; `categories` lists the values. |
| `valueType` | query | no | `string` | Keep only `fixed` or only `range` offers; a card left without an offer is dropped. |
| `isRedeemableGlobally` | query | no | `boolean` | `true` keeps only cards that can be redeemed in any country. |
| `currency` | query | no | `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`. |
| `cursor` | query | no | `string` | The `nextCursor` of the previous page; omit it for the first page. Reuse it only with the same filters and currency. |
| `limit` | query | no | `integer` | Page size, 1 to 100; default 100. |
## Responses
### 200
OK
- `text/plain`: `GiftCardCatalogPage`
- `application/json`: `GiftCardCatalogPage`
- `text/json`: `GiftCardCatalogPage`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Get a gift card (/docs/api-reference/gift-cards/get-card)
`GET /v1/giftcards/cards/{id}`
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.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `id` | path | yes | `string` | The card's `id` (`card_…`) from search or the catalog. |
| `currency` | query | no | `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`. |
## Responses
### 200
OK
- `text/plain`: `GiftCard`
- `application/json`: `GiftCard`
- `text/json`: `GiftCard`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Order gift cards (/docs/api-reference/gift-cards/create-order)
`POST /v1/giftcards/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.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | yes | `string` | UUID idempotency key for safe retries of this operation. |
## Request body
- `application/json`: `GiftCardOrderRequest`
- `text/json`: `GiftCardOrderRequest`
- `application/*+json`: `GiftCardOrderRequest`
## Responses
### 200
OK
- `text/plain`: `GiftCardOrder`
- `application/json`: `GiftCardOrder`
- `text/json`: `GiftCardOrder`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 402
Payment Required
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 409
The offer changed since it was quoted: its price rose (11002, for products that check the quoted price) or it is no longer available (11003). Or the idempotency key: a request with this key is still running (12002): send the same request, key and body again after Retry-After seconds; it was used for a different request (12001); or its history is ambiguous.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
### 503
Idempotency state is temporarily unavailable; retry the same request and key.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Quote gift cards (/docs/api-reference/gift-cards/quote)
`POST /v1/giftcards/quote`
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.
## Request body
- `application/json`: `GiftCardOrderRequest`
- `text/json`: `GiftCardOrderRequest`
- `application/*+json`: `GiftCardOrderRequest`
## Responses
### 200
OK
- `text/plain`: `GiftCardQuote`
- `application/json`: `GiftCardQuote`
- `text/json`: `GiftCardQuote`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 409
Conflict
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Request a manual amendment (/docs/api-reference/hotel-manual-amendments/create-manual-amendment)
`POST /v1/order-items/{id}/manual-amendments`
Requests a manual change to a confirmed hotel booking.
Requires an `Idempotency-Key` header (a UUID) and an API key with order-manage permission. Send the
requested change as `attributes`: new `checkInDate` and `checkOutDate`, `holder` or
`roomGuests` (one entry per booked room, `roomIndex` 1-based); anything omitted keeps its booked
value. Returns `{ amendmentId }`; the request starts as `Pending` and nothing is charged until you
approve a quote.
The order item must be fulfilled, not refunded, use the manual amendment flow and have no open request
(`Pending`, `InProgress`, `Quoted` or `PartnerApproved`). Errors: 400 / 21100 invalid
request, 21101 booking not amendable, 21102 a request is already open, 21104 manual amendments not available,
21113 or 21114 invalid or unsupported room and guest changes; 404 / 10004 when the order item is not found.
The same key after the request finished gives 409 / 12000: read the request it created with
`GET /order-items/{id}/amendments`. While it is still running the key gives 409 / 12002 with
`Retry-After`, and with a different body 409 / 12001.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `id` | path | yes | `string` | The hotel order item's `id`, from `items[].id` of the order. |
| `Idempotency-Key` | header | yes | `string` | UUID idempotency key for safe retries of this operation. |
## Request body
- `application/json`: `ManualAmendmentCreateRequest`
- `text/json`: `ManualAmendmentCreateRequest`
- `application/*+json`: `ManualAmendmentCreateRequest`
## Responses
### 200
OK
- `text/plain`: `ManualAmendmentResult`
- `application/json`: `ManualAmendmentResult`
- `text/json`: `ManualAmendmentResult`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 409
The idempotency key: it was used by a request that finished (12000), so use a new key for a new request; a request with this key is still running (12002): send the same request, key and body again after Retry-After seconds; or it was used for a different request (12001).
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
### 503
Idempotency state is temporarily unavailable; retry the same request and key.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Cancel a manual amendment (/docs/api-reference/hotel-manual-amendments/cancel-manual-amendment)
`POST /v1/order-items/{id}/manual-amendments/{amendmentId}/cancel`
Cancels a manual amendment request that has not been worked on yet.
Only a `Pending` request can be cancelled; once it is `Quoted`, decline it instead. No body. Returns
`{ amendmentId }` and moves the request to `Cancelled`. Errors: 400 / 21103 in any other status,
400 / 21104 when the booking does not use manual amendments, 404 / 10004 when not found.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `id` | path | yes | `string` | The hotel order item's `id`, from `items[].id` of the order. |
| `amendmentId` | path | yes | `string` | The `amendmentId` returned when the request was created. |
## Responses
### 200
OK
- `text/plain`: `ManualAmendmentResult`
- `application/json`: `ManualAmendmentResult`
- `text/json`: `ManualAmendmentResult`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Approve a manual amendment (/docs/api-reference/hotel-manual-amendments/approve-manual-amendment)
`POST /v1/order-items/{id}/manual-amendments/{amendmentId}/approve`
Approves the quoted price of a manual amendment and settles it from your wallet.
Requires an `Idempotency-Key` header (a UUID). Only a `Quoted` request can be approved: show the
quoted `amountToPay` or `amountToRefund` first. On approval `amountToPay` is debited and the
request becomes `PartnerApproved`; `amountToRefund` is credited only after the change is confirmed.
The body is optional; `walletId` picks the wallet to settle from. Returns `{ amendmentId }`.
Errors: 400 / 21103 when the request is not `Quoted`; 400 / 21107 when the wallet balance is too low
(the request stays `Quoted`; top up and approve again); 400 / 21106 when changing the wallet while an
approval is in progress; 21105 or 21108–21112 for settlement and concurrency failures (reload the request
and contact support before retrying a 21108).
The same key and body after the approval finished returns `{ amendmentId }` again and approves and charges
nothing again. While it is still running the key gives 409 / 12002 with `Retry-After`, and with a
different body 409 / 12001.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `id` | path | yes | `string` | The hotel order item's `id`, from `items[].id` of the order. |
| `amendmentId` | path | yes | `string` | The `amendmentId` returned when the request was created. |
| `Idempotency-Key` | header | yes | `string` | UUID idempotency key for safe retries of this operation. |
## Request body
- `application/json`: `ManualAmendmentApproveRequest`
- `text/json`: `ManualAmendmentApproveRequest`
- `application/*+json`: `ManualAmendmentApproveRequest`
## Responses
### 200
OK
- `text/plain`: `ManualAmendmentResult`
- `application/json`: `ManualAmendmentResult`
- `text/json`: `ManualAmendmentResult`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 409
The idempotency key: a request with this key is still running (12002): send the same request, key and body again after Retry-After seconds; or it was used for a different request (12001). A finished request sent again with the same key and body returns 200 with the result of the first call, rebuilt from the record that call created as it reads now: nothing runs again, and a status that has moved on since shows its current value.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
### 503
Idempotency state is temporarily unavailable; retry the same request and key.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Decline a manual amendment (/docs/api-reference/hotel-manual-amendments/decline-manual-amendment)
`POST /v1/order-items/{id}/manual-amendments/{amendmentId}/decline`
Declines the quoted price of a manual amendment.
Only a `Quoted` request can be declined. No body and no money moves. Returns `{ amendmentId }` and
moves the request to `Cancelled`; the booking is unchanged. Errors: 400 / 21103 in any other status,
404 / 10004 when not found.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `id` | path | yes | `string` | The hotel order item's `id`, from `items[].id` of the order. |
| `amendmentId` | path | yes | `string` | The `amendmentId` returned when the request was created. |
## Responses
### 200
OK
- `text/plain`: `ManualAmendmentResult`
- `application/json`: `ManualAmendmentResult`
- `text/json`: `ManualAmendmentResult`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Search hotels (/docs/api-reference/hotels/search)
`POST /v1/hotels/search`
Searches hotels by location or hotel IDs and returns their bookable rates for the stay.
Send `searchCriteria.location` or `searchCriteria.hotelIds`; a non-empty `hotelIds` wins and
`location` is then ignored. `checkIn`, `checkOut`, `rooms` and `guestNationality`
are required: rates are priced for the occupancy, child ages and guest market sent here. A stay longer than
30 nights returns 400 / 10001 with reason `MAX_STAY_EXCEEDED` at `checkOut`. The body rejects an
unknown member at every level, `filters`, `searchCriteria.location` and `rooms[]` included,
and the route takes no query parameters: either gives 400 / 10001.
Returns `{ items, pagination, nextCursor, details }`. Each item is a hotel: `id`, `name`,
`countryCode`, `category` (always null), `logoUrl` (the main image), `description`, its
`offers`, and `details` with the star rating, address, coordinates, images, amenity groups and
contact. Each offer is one rate: an opaque `publicId`, a `name` such as "Deluxe King, Breakfast,
Free cancellation", a `price` for the whole stay (all rooms and nights), and the rate terms in
`details`, including `expiresAt`. Pass an offer's
`publicId` to quote or order before it expires. The hotel's `id` is not an offer; send it in
`searchCriteria.hotelIds` to search that hotel again. A hotel without an orderable offer is not
listed. `details.availableFilters` holds the amenity filter values of a `cityCode` search.
Location searches are paged: `limit` is 1–50 (default 20) and the next page is requested by sending
the response's `nextCursor` back as `cursor` with the same body; a null `nextCursor` is the
last page. A page can hold fewer hotels than `limit`, even none, while `nextCursor` is not null:
keep paging until it is null. `pagination` is `{ currentCount, limit, hasMore }`: the walk states
no page number and no total. To keep pages small, each hotel on a page has one offer, its cheapest rate,
with empty `nightlyPrices` and `surcharges`, and no description and one image. A
`hotelIds` search returns every rate of those hotels with the full detail, as one complete page; an
empty `items` there means none of those hotels has an orderable offer.
Errors: an ID that is not a hotel ID returns 400 / 21000; an unknown or expired hotel ID 400 / 11004;
503 / 21003 when offers are temporarily unavailable (retry the search); 502, 504 or 503 with
21007–21009 when the hotel system fails, times out or is unavailable.
## Request body
- `application/json`: `HotelSearchRequest`
- `text/json`: `HotelSearchRequest`
- `application/*+json`: `HotelSearchRequest`
## Responses
### 200
OK
- `text/plain`: `HotelSearchResult`
- `application/json`: `HotelSearchResult`
- `text/json`: `HotelSearchResult`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
### 503
Service Unavailable
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Get a hotel (/docs/api-reference/hotels/get-property)
`GET /v1/hotels/properties/{id}`
Returns one hotel's content: the item that search returns, without `offers`.
Use it to show a hotel's information: name, description, star rating, address, images, amenities and
contact. A hotel has no price without a stay, so the response has no `offers` key; send the `id`
in a search's `searchCriteria.hotelIds` for its rates. The route serves the hotels of the OpenRoam catalog,
as the catalog files list them. An ID that is unknown, not a hotel ID, or not in the catalog (such as a
temporary ID a search gave a hotel outside the catalog) gives 404 / 10004. The route takes no query
parameters.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `id` | path | yes | `string` | The hotel's `id` (`hotel_…`) from search or the catalog files. |
## Responses
### 200
OK
- `text/plain`: `CatalogHotel`
- `application/json`: `CatalogHotel`
- `text/json`: `CatalogHotel`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 404
Not Found
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Search hotel destinations (/docs/api-reference/hotels/get-destinations)
`GET /v1/hotels/destinations`
Finds the places to search hotels in by name: a country, a region, a city or a district.
Returns `{ items }`: at most `limit` places whose names match `q`, most relevant first, without
paging. Send a place's `id` as `searchCriteria.location.geoNodeId` in a search; it finds the
hotels of every place inside it. `name` includes the place's parents, for example "Downtown Dubai,
Dubai, United Arab Emirates", and `category` is its level: `country`, `region`, `city`
or `area`. Only places where OpenRoam has had hotels are listed.
`q` is required: plain text, at most 100 characters, without control characters. `countryCode`
keeps the places of one ISO 3166-1 alpha-2 country; `limit` is 1–100 (default 10). An invalid or blank
value, or any other query parameter, gives 400 / 10001. 503 / 10007 when the destination index is
unavailable or does not answer within 5 seconds: retry.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `q` | query | yes | `string` | Required. Free text over place names, for example `downtown dub`; at most 100 characters, without control characters. |
| `countryCode` | query | no | `string` | Optional ISO 3166-1 alpha-2 country, in either case: only places in that country. A blank value is rejected. |
| `limit` | query | no | `integer` | The most places to return, 1 to 100; default 10. |
## Responses
### 200
OK
- `text/plain`: `HotelDestinationList`
- `application/json`: `HotelDestinationList`
- `text/json`: `HotelDestinationList`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
### 503
Service Unavailable
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# List hotel amenities (/docs/api-reference/hotels/get-amenity-catalog)
`GET /v1/hotels/amenities/catalog`
Returns the amenity catalog: every amenity code and group with its display label.
Use it to label the `amenityGroups` codes in hotel content and to build an amenity filter; send codes
back in search `filters.amenityCodes`. `notesLabel` is the heading for a hotel's uncoded
`amenityNotes`. Labels follow the request language, as `Accept-Language` sets it; the route takes no
query parameters.
## Responses
### 200
OK
- `text/plain`: `AmenityCatalog`
- `application/json`: `AmenityCatalog`
- `text/json`: `AmenityCatalog`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Get hotel catalog files (/docs/api-reference/hotels/get-catalog-files)
`GET /v1/hotels/catalog/files`
Returns download links for the current hotel catalog files.
Returns `{ generatedAt, hotelCount, files: [{ variant, url, sizeBytes }] }`, one zip per variant. Each
zip holds `hotels.jsonl`: one hotel per line, in the item shape that search and
`properties/{id}` return, with `offers` empty. `withoutImages` carries each hotel's main
image as `logoUrl` and an empty `details.imageUrls`; `withImages` also lists every gallery
image there. `generatedAt` is null and `files` empty before the first catalog is built, and after
a release that changes the line format until the first build in the new format: the route never links a
file whose lines have another format. The route takes no query parameters.
## Responses
### 200
OK
- `text/plain`: `HotelCatalogExport`
- `application/json`: `HotelCatalogExport`
- `text/json`: `HotelCatalogExport`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Quote hotel rates (/docs/api-reference/hotels/quote)
`POST /v1/hotels/quote`
Prices up to 5 searched or quoted rates again with the hotel system and issues a new offer for each.
Takes the same body as order, `{ currency, referenceId, items }`, and checks it the same way: the whole
body first, so a body error gives 400 / 10001 also when it is in a later item, then each item completely
(its inputs, its `publicId`, then a fresh price from the hotel system) before the next, in request order.
`inputs` may be left out; when sent, they are checked as the order checks them. The body and every
object in it reject an unknown member (400 / 10001). Stay dates and rooms come from the offer and are
returned in each item's `details`. Nothing is charged or reserved.
Each item returns a new `publicId` for its rate at the current `price` (the whole stay, all rooms
and nights): order with it before `details.expiresAt`, which is at most 30 minutes away and never past
an expiry the hotel system states. A price that rose since the search is returned with 200; only
`inputs.maxPrice` stops a quote, with 409 / 11002 at `items[i].inputs.maxPrice`.
`details.availability` is `onRequest` for a rate that is held only on request, which an
order refuses with 409 / 11003.
Errors name the failing item: a rate that is no longer sold is 409 / 11003, and an unknown, expired or
another partner's `publicId`, another product's offer, a hotel's own `id` or an expired search
session (search again) is 400 / 11004, each at `items[i]`; input errors (400 / 10001) are at
`items[i].inputs…`. Offer and hotel-system failures return their hotel codes without a path:
503 / 21003 when offers are temporarily unavailable, 21007–21009, and 400 / 21010 when the hotel's room
layout no longer matches the searched occupancy (search again).
## Request body
- `application/json`: `HotelOrderRequest`
- `text/json`: `HotelOrderRequest`
- `application/*+json`: `HotelOrderRequest`
## Responses
### 200
OK
- `text/plain`: `HotelQuote`
- `application/json`: `HotelQuote`
- `text/json`: `HotelQuote`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 409
Conflict
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
### 503
Service Unavailable
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Book hotels (/docs/api-reference/hotels/create-order)
`POST /v1/hotels/order`
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.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | yes | `string` | UUID idempotency key for safe retries of this operation. |
## Request body
- `application/json`: `HotelOrderRequest`
- `text/json`: `HotelOrderRequest`
- `application/*+json`: `HotelOrderRequest`
## Responses
### 200
OK
- `text/plain`: `HotelOrder`
- `application/json`: `HotelOrder`
- `text/json`: `HotelOrder`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 402
Payment Required
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 409
The offer changed since it was quoted: its price rose (11002, for products that check the quoted price) or it is no longer available (11003). Or the idempotency key: a request with this key is still running (12002): send the same request, key and body again after Retry-After seconds; it was used for a different request (12001); or its history is ambiguous.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
### 503
Idempotency state is temporarily unavailable; retry the same request and key.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# List partner amendments (/docs/api-reference/order-items/list-partner-amendments)
`GET /v1/amendments`
Lists amendments across the authenticated partner's orders.
Requires the read order permission. Includes manual and automatic amendments in all
statuses. Optional repeated statuses, productType, amendmentMode, orderId, orderItemId and inclusive
UTC from/to timestamps filter the result. Use flat page (default 1) and limit (default 10,
maximum 100) query parameters. Nested paging keys return 400 with code 10001.
Amounts retain their original currency; a quote does not imply settlement.
Example response:
```{"items":[{"id":"b7428a30-f760-46e8-b504-a670bf9bed19","orderId":"a46ee792-287e-44ef-a641-48de1a0f72fd","orderItemId":"cf4a49ac-b785-43d4-912a-4be3443e48bd","productType":"hotel","amendmentMode":"manual","status":"quoted","createdAt":"2026-11-03T09:00:00Z","amountToPay":{"amount":25,"currency":"USD"},"amountToRefund":{"amount":0,"currency":"USD"}}],"pagination":{"currentCount":1,"totalCount":1,"skip":0,"limit":10,"hasMore":false,"page":1,"totalPages":1}}```
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `page` | query | no | `integer` | One-based page number. Default 1. |
| `limit` | query | no | `integer` | Page size, 1 to 100. Default 10. |
| `statuses` | query | no | `string[]` | Repeat to match any of the requested statuses. |
| `productType` | query | no | `string` | |
| `amendmentMode` | query | no | `string` | |
| `orderId` | query | no | `string` | |
| `orderItemId` | query | no | `string` | |
| `from` | query | no | `string` | Inclusive creation timestamp with UTC offset. ISO 8601 date-time. A value with Z or an offset is converted to UTC; a value without a zone is read as UTC, and a date alone means 00:00 UTC on that day. |
| `to` | query | no | `string` | Inclusive creation timestamp with UTC offset. Send the end of a UTC day to include that whole day. ISO 8601 date-time. A value with Z or an offset is converted to UTC; a value without a zone is read as UTC, and a date alone means 00:00 UTC on that day. |
## Responses
### 200
OK
- `text/plain`: `AmendmentList`
- `application/json`: `AmendmentList`
- `text/json`: `AmendmentList`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 401
Unauthorized
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 403
Forbidden
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Get an order item (/docs/api-reference/order-items/get-by-id)
`GET /v1/order-items/{id}`
Gets an order item: what was bought, its delivery, its refund and what you can do next.
Requires the `read` order permission. Returns the item exactly as it appears in `items[]` of the
order response, including `orderId`, the order it belongs to. `fulfillment.status` and
`refund.status` give its state; `actions.cancellation` says whether it can be cancelled now,
`actions.amendment` whether it can be amended and `actions.update` whether it can be updated. An
item of another partner, or an unknown id, returns
`404` with code `10004`; a malformed id or an unknown query parameter returns `400` with code
`10001`.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `id` | path | yes | `string` | Order item id (`items[].id` from the order response). |
## Responses
### 200
OK
- `text/plain`: `OrderItem`
- `application/json`: `OrderItem`
- `text/json`: `OrderItem`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 401
Unauthorized
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 403
Forbidden
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 404
Not Found
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Preview an item cancellation (/docs/api-reference/order-items/get-cancellation-preview)
`GET /v1/order-items/{id}/cancellation-preview`
Previews the cancellation penalty and expected refund for an order item.
Requires the `read` order permission. Returns `penaltyAmount`, the `cancellationFee` kept in
addition to it (`null` when none applies) and the expected `refundAmount`, all in the order
currency, `isRefundable`, the cancellation band in effect, priced at the penalty
(`appliedPenalties`: at most one `{ from, penaltyAmount }`), `effectiveCancellationDate` and
`checkInDate`, calculated with the same rules as the partner portal. The fee comes out of what the
penalty leaves, so the refund is never negative. `isRefundable: false` means the penalty alone keeps
the whole price, so the item cannot be cancelled; it is not an error. A fee that takes what the penalty leaves
does not make it false: the item can still be cancelled, with a refund of 0. The preview does
not cancel the item or change its state, and it does not lock the penalty: the cancel call recalculates it,
so a later cancellation band may apply.
The preview refuses what the cancel refuses. A delivered item of a kind that cannot take back a delivery
(airtime, utility, gift cards, eSIMs) can never be cancelled and returns `422` with code `18000`
(`CANCELLATION_NOT_SUPPORTED`). Otherwise, when the item's `actions.cancellation` is not
`available`, it returns `409` with code `18001` (`CANCELLATION_NOT_AVAILABLE`), and
`details[0].reason` repeats `actions.cancellation.availability`. A refund started by OpenRoam
support returns the same `409` with `MANUAL_REVIEW`. A delivered item is priced with its product's
cancellation rules. An item that
was not delivered has no cancellation to price: a rejected item whose automatic refund has not started
previews a full refund of what was paid (after a failed refund, the amounts that refund is retried with), with a `penaltyAmount`
of 0 and no `cancellationFee` or `appliedPenalties`. A cancellation the product refuses, for
example after check-out, returns `400` with code `10001`. An item of another partner, or an unknown
id, returns `404` with code `10004`.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `id` | path | yes | `string` | Order item id (`items[].id` from the order response). |
## Responses
### 200
OK
- `text/plain`: `OrderItemCancellationPreview`
- `application/json`: `OrderItemCancellationPreview`
- `text/json`: `OrderItemCancellationPreview`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 401
Unauthorized
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 403
Forbidden
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 404
Not Found
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 409
Conflict
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 422
Unprocessable Content
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Quote an amendment (/docs/api-reference/order-items/quote-amendment)
`POST /v1/order-items/{id}/amendments/quote`
Quotes a change to a delivered order item.
Available only when the item's `actions.amendment` is `available`: the item must be fulfilled,
not refunded, and its product must support automatic changes. Items whose changes need manual review show
`manualReview` and use the manual amendment routes instead. A kind of item that can never be amended
returns `422` with code `18002` (`AMENDMENT_NOT_SUPPORTED`); otherwise an amendment that is
not allowed now returns `409` with code `18003` (`AMENDMENT_NOT_AVAILABLE`), and
`details[0].reason` repeats `actions.amendment.availability` (`MANUAL_REVIEW` or
`NOT_AVAILABLE`). An item of another partner, or an unknown id, returns `404` with code
`10004`.
Send the requested change in `attributes`, in the shape the item's product defines; top-level names that
start with `_` are reserved for OpenRoam and ignored. The response
has an `amendmentRequestId`, the time the quote was made (`processedAt`), the time it expires
(`expiresAt`) and one or more `options`, each with an `id`, an `amountToPay` and an
`amountToRefund` in the API key's currency, and an `amendmentFee`: a fee for the change, already
included in those amounts, or `null` when none applies. Nothing changes and nothing is charged until
you confirm the quote with `POST /order-items/{id}/amendments/confirm`, before `expiresAt`.
Requires an `Idempotency-Key` header (a UUID). Repeating a completed request with the same key
returns `409` with code `12000` (`IDEMPOTENCY_KEY_ALREADY_USED`): a quote is not kept, so
request a new one with a new key. One still running returns `409` with code `12002`
(`IDEMPOTENCY_KEY_IN_PROGRESS`) and a `Retry-After` header, and a different body with the same
key `409` with code `12001`. A request that ended in an error can be sent again with the same key
and body.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `id` | path | yes | `string` | Order item id (`items[].id` from the order response). |
| `Idempotency-Key` | header | yes | `string` | UUID idempotency key for safe retries of this operation. |
## Request body
- `application/json`: `AmendmentQuoteRequest`
- `text/json`: `AmendmentQuoteRequest`
- `application/*+json`: `AmendmentQuoteRequest`
## Responses
### 200
OK
- `text/plain`: `AmendmentQuote`
- `application/json`: `AmendmentQuote`
- `text/json`: `AmendmentQuote`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 404
Not Found
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 409
The idempotency key: it was used by a request that finished (12000), so use a new key for a new request; a request with this key is still running (12002): send the same request, key and body again after Retry-After seconds; or it was used for a different request (12001).
- `application/json`: `ErrorResponse`
### 422
Unprocessable Content
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
### 503
Idempotency state is temporarily unavailable; retry the same request and key.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# List item amendments (/docs/api-reference/order-items/get-amendments)
`GET /v1/order-items/{id}/amendments`
Lists every amendment of an order item.
Returns the whole list as an array, without paging. Each amendment has `id`, `orderItemId`,
`status`, `productType`, `createdAt`, `amountToPay` and `amountToRefund`. An item
of another partner, or an unknown id, returns `404` with code `10004`.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `id` | path | yes | `string` | Order item id (`items[].id` from the order response). |
## Responses
### 200
OK
- `text/plain`: `OrderItemAmendment[]`
- `application/json`: `OrderItemAmendment[]`
- `text/json`: `OrderItemAmendment[]`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 404
Not Found
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Get an amendment (/docs/api-reference/order-items/get-amendment-by-id)
`GET /v1/order-items/{id}/amendments/{amendmentId}`
Gets one amendment of an order item.
Returns the same fields as the amendment list. An unknown amendment, or one that belongs to another item
or partner, returns `404` with code `10004`.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `id` | path | yes | `string` | Order item id (`items[].id` from the order response). |
| `amendmentId` | path | yes | `string` | Amendment id (`amendmentId` from the confirm response, or `id` from the amendment list). |
## Responses
### 200
OK
- `text/plain`: `OrderItemAmendment`
- `application/json`: `OrderItemAmendment`
- `text/json`: `OrderItemAmendment`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 404
Not Found
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Cancel an item (/docs/api-reference/order-items/cancel)
`POST /v1/order-items/{id}/cancel`
Cancels an order item and refunds what was paid for it, less any cancellation penalty.
Available when the item's `actions.cancellation` is `available`; while a refund is running it shows
`inProgress`, and `manualReview` means support must handle it. A rejected item is refunded in full
automatically and reported by `order-item.refunded`; the `fulfillmentFailed` reason then returns
that refund. The `fulfillmentFailed` reason is accepted only for a rejected item; a
cancellation that is not valid for the item returns `400` with code `10001`. A delivered item of a
kind that cannot take back a delivery (airtime, utility, gift cards, eSIMs) can never be cancelled and
returns `422` with code `18000` (`CANCELLATION_NOT_SUPPORTED`). Otherwise a cancellation that
is not allowed now, for example while the item is still being delivered, returns `409` with code
`18001` (`CANCELLATION_NOT_AVAILABLE`), and `details[0].reason` repeats
`actions.cancellation.availability` (`IN_PROGRESS`, `MANUAL_REVIEW` or `NOT_AVAILABLE`).
The same `409` with `IN_PROGRESS` answers a cancel that meets a refund, a delivery or a change of
the same order still running; send it again shortly. The amount is recalculated at this point, so it can
differ from an earlier cancellation preview. A refund started by OpenRoam support returns the same
`409` with `MANUAL_REVIEW`. An item of another partner, or an unknown id, returns `404` with
code `10004`.
Returns the `orderItemId`, the refund `amount`, the `method` it is returned to and its
`status`. A balance payment is refunded to the wallet that paid it. Refund progress is also reported
by the `order-item.refunded` webhook.
Requires an `Idempotency-Key` header (a UUID). Repeating a completed request with the same key and body
returns `200` with the refund that request started, as it reads now, and refunds nothing again. One
still running returns `409` with code `12002` (`IDEMPOTENCY_KEY_IN_PROGRESS`) and a
`Retry-After` header, and a different body with the same key `409` with code `12001`. A
request that ended in an error can be sent again with the same key and body.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `id` | path | yes | `string` | Order item id (`items[].id` from the order response). |
| `Idempotency-Key` | header | yes | `string` | UUID idempotency key for safe retries of this operation. |
## Request body
- `application/json`: `OrderItemCancelRequest`
- `text/json`: `OrderItemCancelRequest`
- `application/*+json`: `OrderItemCancelRequest`
## Responses
### 200
OK
- `text/plain`: `OrderItemCancelResult`
- `application/json`: `OrderItemCancelResult`
- `text/json`: `OrderItemCancelResult`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 404
Not Found
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 409
The idempotency key: a request with this key is still running (12002): send the same request, key and body again after Retry-After seconds; or it was used for a different request (12001). A finished request sent again with the same key and body returns 200 with the result of the first call, rebuilt from the record that call created as it reads now: nothing runs again, and a status that has moved on since shows its current value.
- `application/json`: `ErrorResponse`
### 422
Unprocessable Content
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
### 503
Idempotency state is temporarily unavailable; retry the same request and key.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Update an item (/docs/api-reference/order-items/update)
`POST /v1/order-items/{id}/update`
Updates a delivered order item, without a charge.
Changes what the item's kind lets a partner change after the purchase, in one call. An update never charges
or refunds anything: a change with a price, such as a hotel or flight change, is an amendment
(`POST /order-items/{id}/amendments/quote`). At launch only gift cards can be updated: `inputs`
takes a new `recipientEmail` and `giftMessage`, and the gift email is sent again, to the new address
with the new message. A card bought without a recipient needs `recipientEmail`. Every other kind of item
returns `422` with code `18004` (`UPDATE_NOT_SUPPORTED`).
Available when the item's `actions.update` is `available`; otherwise the update returns `409`
with code `18005` (`UPDATE_NOT_AVAILABLE`), and `details[0].reason` repeats
`actions.update.availability` (`IN_PROGRESS` or `NOT_AVAILABLE`). The same `409` is
returned when the item stops being available during the call, for example after a cancel.
A member of `inputs` left out or sent as `null` keeps its current value, and at least one member
must be present. An invalid member returns `400` with code `10001` at `inputs.`,
with the same reasons as the order's `inputs`, and a member the item's kind does not define returns
`400` with code `10001` and reason `UNSUPPORTED_FIELD`. An item of another partner, or an
unknown id, returns `404` with code `10004`. A malformed body (not valid JSON, `inputs`
missing, `null` or not an object, or a top-level member other than `inputs`) returns `400`
with code `10001` before the item is read. The checks on the item then run in this order: `404`,
`422`, `409`, then `400` for the members of `inputs`.
Returns the item exactly as `GET /order-items/{id}` returns it. No webhook is sent for an update.
Requires an `Idempotency-Key` header (a UUID). Repeating a completed request with the same key and body
returns `200` with the item as `GET /order-items/{id}` returns it now, and changes nothing again
(no gift email is sent again). One still running returns `409` with code `12002`
(`IDEMPOTENCY_KEY_IN_PROGRESS`) and a `Retry-After` header, and a different body with the same
key `409` with code `12001`. A request that ended in an error can be sent again with the same key
and body. Updating the same item again needs a new key.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `id` | path | yes | `string` | Order item id (`items[].id` from the order response). |
| `Idempotency-Key` | header | yes | `string` | UUID idempotency key for safe retries of this operation. |
## Request body
- `application/json`: `OrderItemUpdateRequest`
- `text/json`: `OrderItemUpdateRequest`
- `application/*+json`: `OrderItemUpdateRequest`
## Responses
### 200
OK
- `text/plain`: `OrderItem`
- `application/json`: `OrderItem`
- `text/json`: `OrderItem`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 404
Not Found
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 409
The idempotency key: a request with this key is still running (12002): send the same request, key and body again after Retry-After seconds; or it was used for a different request (12001). A finished request sent again with the same key and body returns 200 with the result of the first call, rebuilt from the record that call created as it reads now: nothing runs again, and a status that has moved on since shows its current value.
- `application/json`: `ErrorResponse`
### 422
Unprocessable Content
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
### 503
Idempotency state is temporarily unavailable; retry the same request and key.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Confirm an amendment (/docs/api-reference/order-items/confirm-amendment)
`POST /v1/order-items/{id}/amendments/confirm`
Confirms a quoted amendment, paying any surcharge or receiving any refund.
Send the `amendmentRequestId` from the quote and, optionally, the `selectedOptionId` of one of
its options (the first option is used when it is omitted). The quote is checked again before anything is
charged: an expired or unknown quote, or one made before another amendment changed the item, returns
`400` with code `11004` (`OFFER_EXPIRED_OR_INVALID`) at `amendmentRequestId`, and an
option that is no longer offered returns `400` with code `10001`; request a new quote then. Where
the change is priced again before the charge (hotels), a price that changed since the quote returns
`409` with code `11002` (`OFFER_PRICE_CHANGED`) at `amendmentRequestId` without
`maxPrice`, and is charged when it is within `maxPrice`. A price above `maxPrice` returns
`409` with code `11002` at
`maxPrice`, with nothing charged; a `maxPrice` in another currency than the quoted amounts returns
`400` with code `10001` at `maxPrice.currency`. A change refused when it is sent (for example,
a flight whose price changed since the quote) gets its surcharge back and returns `400` with code
`10001`.
Confirming the same quote again with a new `Idempotency-Key` returns `200` with the amendment that
quote created, and nothing is charged twice. A confirm that was interrupted after its payment is finished
first: its change is sent, or its surcharge is returned. Two confirms of one quote sent at the same time make
one amendment: the other returns `200` with it, or `409` with code `18003` and
`IN_PROGRESS` while the first is still running; send it again shortly. A kind of item that can never be
amended returns `422` with code `18002` (`AMENDMENT_NOT_SUPPORTED`), and an amendment that is
not allowed now returns `409` with code `18003` (`AMENDMENT_NOT_AVAILABLE`), with
`details[0].reason` `IN_PROGRESS` while another amendment or a change to the order is running,
otherwise `MANUAL_REVIEW` or `NOT_AVAILABLE`. An item of another partner, or an unknown id,
returns `404` with code `10004`.
A surcharge is charged with `paymentMethod` `balance`, its only value: the wallet linked to the API
key. Any other value returns `400` with code `10001` at `paymentMethod`. A refund goes to that
wallet. Returns the
`amendmentRequestId`, the new `amendmentId`, its `status`, and the `payment` or
`refund` that was made (`null` when none). A wallet charge that fails returns `402` with code
`16000` (`PAYMENT_FAILED`) and, when the reason is known, `details[0]` naming `wallet`
with `INSUFFICIENT_BALANCE` or `WALLET_BLOCKED`; no amendment is kept, so the same quote can be
confirmed again after a top-up. Amendments do not change
`fulfillmentVersion`; read the order again for the changed item.
Requires an `Idempotency-Key` header (a UUID). Repeating a completed request with the same key and body
returns `200` with the amendment that request created, as it reads now, and charges nothing again. One
still running returns `409` with code `12002` (`IDEMPOTENCY_KEY_IN_PROGRESS`) and a
`Retry-After` header, and a different body with the same key `409` with code `12001`. A
request that ended in an error can be sent again with the same key and body.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `id` | path | yes | `string` | Order item id (`items[].id` from the order response). |
| `Idempotency-Key` | header | yes | `string` | UUID idempotency key for safe retries of this operation. |
## Request body
- `application/json`: `AmendmentConfirmRequest`
- `text/json`: `AmendmentConfirmRequest`
- `application/*+json`: `AmendmentConfirmRequest`
## Responses
### 200
OK
- `text/plain`: `AmendmentConfirmResult`
- `application/json`: `AmendmentConfirmResult`
- `text/json`: `AmendmentConfirmResult`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 402
Payment Required
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 404
Not Found
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 409
The idempotency key: a request with this key is still running (12002): send the same request, key and body again after Retry-After seconds; or it was used for a different request (12001). A finished request sent again with the same key and body returns 200 with the result of the first call, rebuilt from the record that call created as it reads now: nothing runs again, and a status that has moved on since shows its current value.
- `application/json`: `ErrorResponse`
### 422
Unprocessable Content
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
### 503
Idempotency state is temporarily unavailable; retry the same request and key.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# List orders (/docs/api-reference/orders/get-all)
`GET /v1/orders`
Lists the partner's orders, newest first, with optional filters.
Returns `{ orders, pagination }`. Each summary has `id`, `referenceId`, `origin`,
`status`, `total`, the latest `payment` and `itemCount`; read one order for its items
and timeline.
Orders created through the API, the dashboard and the partner's sites are all listed; `channel`
(`api`, `dashboard` or `site`, the values of `origin.channel`) keeps one of them. With a
site credential, only the orders of that site are listed. `orderStatuses` takes the
values of `status` and matches the status the order reads now. Filters combine with AND;
repeated `productTypes` or `orderStatuses` values combine with OR. A `productTypes` filter
selects orders containing at least one item of that type and still returns the whole order. Filters apply
before counting and paging, so send the same filters on every page.
Use flat `page` (default 1) and `limit` (default 10, 1 to 100) query parameters.
`cursor`, `skip`, `offset`, nested paging keys and repeated paging parameters return
`400` with code `10001` (`INVALID_REQUEST`).
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `page` | query | no | `integer` | One-based page number. Default 1. |
| `limit` | query | no | `integer` | Page size, 1 to 100. Default 10. |
| `startDate` | query | no | `string` | Only orders created at or after this time (UTC). ISO 8601 date-time. A value with Z or an offset is converted to UTC; a value without a zone is read as UTC, and a date alone means 00:00 UTC on that day. |
| `endDate` | query | no | `string` | Only orders created at or before this time (UTC). ISO 8601 date-time. A value with Z or an offset is converted to UTC; a value without a zone is read as UTC, and a date alone means 00:00 UTC on that day. |
| `minAmount` | query | no | `number` | Only orders whose `total.amount`, in the order's currency, is at least this value. |
| `maxAmount` | query | no | `number` | Only orders whose `total.amount`, in the order's currency, is at most this value. |
| `search` | query | no | `string` | An order id returns that order only; any other text matches part of the email or full name of the user who placed the order. |
| `referenceId` | query | no | `string` | Only the order with exactly this `referenceId`. |
| `channel` | query | no | `string` | Only orders created through this channel, the same values as `origin.channel`: `api`, `dashboard` or `site`. |
| `productTypes` | query | no | `string[]` | Only orders containing at least one item of one of these product types. Repeat the parameter for several types, for example `productTypes=esim&productTypes=giftCard`. |
| `orderStatuses` | query | no | `string[]` | Only orders currently in one of these statuses, the same values as `status`. Repeat the parameter for several statuses. |
## Responses
### 200
OK
- `text/plain`: `OrderList`
- `application/json`: `OrderList`
- `text/json`: `OrderList`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 401
Unauthorized
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
### 500
Internal Server Error
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Create an order (/docs/api-reference/orders/create-order)
`POST /v1/orders`
Places one order of one to five items, of one or several product types, and pays it from the wallet.
Each item names its `productType`, the `publicId` of the offer from search or quote, a
`quantity` and, where the product needs them, product-specific `inputs` (required for hotels and
flights). An order has at most five items and a total quantity of at most five; an item with quantity
`n` becomes `n` separate order items, each with its own `items[].id`. Every item is
validated before anything is charged; a rejected item is reported at `items[i]` in
`details`, for example `11004` (`OFFER_EXPIRED_OR_INVALID`) for an unknown, expired or
other-product `publicId`, `11003` (`OFFER_UNAVAILABLE`) or `11002`
(`OFFER_PRICE_CHANGED`).
The optional `maxTotal` `{ amount, currency }` caps the whole order: the sum of every item's
price times its quantity, in the order currency. Its currency must be the order currency (otherwise
`400`, `10001`, `CURRENCY_MISMATCH` at `maxTotal.currency`). A higher total returns
`409` with code `11002` (`OFFER_PRICE_CHANGED`) at `maxTotal`, after every item is
priced and before anything is charged; a total equal to it is accepted.
The order total is charged to the partner's selected wallet. On success the order is
`processing` and its items start as `pending`; delivery continues after the response, so follow
it with `GET orders/{id}`, `GET orders/{orderId}/fulfillment/status` or the
`order.fulfillment.updated` webhook. If the charge fails, no order is created and the call returns
`402` with code `16000` (`PAYMENT_FAILED`); when the reason is known,
`details[0]` names `wallet` with reason `INSUFFICIENT_BALANCE` or `WALLET_BLOCKED`.
Top up or unblock the wallet and send the same request again with the same `Idempotency-Key`.
Requires an `Idempotency-Key` header (a UUID) per purchase. Repeating the same request with the
same key never charges twice: once the order is accepted it returns `200` with that order's current
state; while the first request is still running it returns `409` with code `12002`
(`IDEMPOTENCY_KEY_IN_PROGRESS`) and a `Retry-After` header, after which you send the same
request again; a different body with the same key returns `409` with code `12001`
(`IDEMPOTENCY_KEY_REQUEST_MISMATCH`). After a timeout or `5xx`, retry with the same key and
body rather than a new key. A `referenceId` already used by another order of the partner returns
`409` with code `10005` (`CONFLICT`). An eSIM top-up whose `inputs.iccid` is not one
of your eSIMs returns `404` with code `10004` (`NOT_FOUND`) and charges nothing.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | yes | `string` | UUID idempotency key for safe retries of this operation. |
## Request body
- `application/json`: `MixedOrderRequest`
- `text/json`: `MixedOrderRequest`
- `application/*+json`: `MixedOrderRequest`
## Responses
### 200
OK
- `text/plain`: `Order`
- `application/json`: `Order`
- `text/json`: `Order`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 401
Unauthorized
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 402
Payment Required
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 403
Forbidden
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 404
Not Found
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 409
The offer changed since it was quoted: its price rose (11002, for products that check the quoted price) or it is no longer available (11003). Or the idempotency key: a request with this key is still running (12002): send the same request, key and body again after Retry-After seconds; it was used for a different request (12001); or its history is ambiguous.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
### 500
Internal Server Error
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 503
Idempotency state is temporarily unavailable; retry the same request and key.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Get an order (/docs/api-reference/orders/get-by-id)
`GET /v1/orders/{id}`
Gets the current state of one order.
Returns the same shape as order creation: `id`, `referenceId`, `origin`, `status`,
`total`, `payment`, `items`, `timeline`, `createdAt`, `updatedAt` and
`fulfillmentVersion`. This is the source of truth for the order: webhooks are snapshots of an event, so
read the order again after a missed or out-of-order delivery. `updatedAt` moves whenever anything in
the order changes: its status, an item's fulfillment, a refund or an amendment.
Order `status` is `processing` from the moment the wallet is charged until every item has an
outcome, then `completed` (every item fulfilled), `partiallyFulfilled` (some items fulfilled,
the rest rejected) or `fulfillmentFailed` (no item fulfilled). Cancelling delivered items makes it
`partiallyRefunded` (some delivered items cancelled and refunded) or `refunded` (every delivered
item cancelled and refunded). Every order's `timeline` starts with `paymentPending`. An order
reads `paymentPending` as its status while a dashboard order awaits its payment, and, rarely, when a
wallet charge was taken but could not be confirmed. Sending the order request again with the same
`Idempotency-Key` and body completes such an order from that charge, and OpenRoam also completes it
automatically, usually within two hours; the wallet is never charged twice. `cancelled` is
an unpaid order that expired. A rejected item is refunded automatically when
nothing is held for it; its `refund` shows the release. Each item reports its own
`fulfillment.status`: `pending`, `fulfilled` with a typed `result`, or
`rejected` with a safe `failure` (`11001`, `FULFILLMENT_REJECTED`).
`items[].actions` say whether amendment, cancellation and update are available now.
An order of another partner, or an unknown id, returns `404` with code `10004`.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `id` | path | yes | `string` | Order id (`id` from the order response). |
## Responses
### 200
OK
- `text/plain`: `Order`
- `application/json`: `Order`
- `text/json`: `Order`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 401
Unauthorized
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 404
Not Found
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
### 500
Internal Server Error
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Quote an order (/docs/api-reference/orders/quote-order)
`POST /v1/orders/quote`
Prices a mixed order body with current prices, without placing an order.
Takes the same body as order creation (one to five items of one or several product types, a total quantity
of at most five) and needs no `Idempotency-Key`. Nothing is charged, held or created; `referenceId`
is checked for its format and not for uniqueness. Returns `currency`, `items`, `total` and
`expiresAt`. Each item is the quote item that its product's own quote route returns, with
`productType`; its `publicId` can be a new one (gift cards, hotels and flights issue one), so order
with the `publicId` of the quote. `total` is the sum of each item's `price` times its
`quantity` in the quote currency. `expiresAt` is the earliest `details.expiresAt` of the items
that have one, and `null` when none has.
Items are checked as the order checks them: first the `inputs` of every item, then the offer of every
item, then each item is priced in request order. The first failing item ends the quote with the code and
path of its product's quote route, under `items[i]`, for example `409` / `11002` at
`items[i].inputs.maxPrice` when the current price is above the guard. An eSIM top-up whose
`inputs.iccid` is not one of your eSIMs returns `404` with code `10004` (`NOT_FOUND`).
A quote does not reserve a price: to hold the quoted price, send it as `inputs.maxPrice` in the order.
## Request body
- `application/json`: `MixedOrderRequest`
- `text/json`: `MixedOrderRequest`
- `application/*+json`: `MixedOrderRequest`
## Responses
### 200
OK
- `text/plain`: `MixedQuote`
- `application/json`: `MixedQuote`
- `text/json`: `MixedQuote`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 401
Unauthorized
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 403
Forbidden
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 404
Not Found
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 409
Conflict
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
### 503
Service Unavailable
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Get fulfillment status (/docs/api-reference/orders/get-fulfillment-status)
`GET /v1/orders/{orderId}/fulfillment/status`
Gets the current fulfillment state of every item in an order.
Returns the order `id`, its `items` (the same item shape as the order, with each item's
`fulfillment` status, typed `result` and `failure`) and `fulfillmentVersion`. The
version increases with every meaningful fulfillment change, including a later revision of an already
delivered result, the cancellation of a delivered item and the completed refund of a delivered item, which
changes the order's `status`, and matches `fulfillmentVersion` in the
`order.fulfillment.updated` webhook: keep the highest version you have seen and use this endpoint to
recover after a missed delivery. The refund of an item that was not delivered and an amendment do not
change the version; read the order for those. An order of another partner, or an unknown id, returns
`404` with code `10004`.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `orderId` | path | yes | `string` | Order id. |
## Responses
### 200
OK
- `text/plain`: `OrderFulfillmentStatus`
- `application/json`: `OrderFulfillmentStatus`
- `text/json`: `OrderFulfillmentStatus`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Preview an order cancellation (/docs/api-reference/orders/get-cancellation-preview)
`GET /v1/orders/{id}/cancellation-preview`
Previews cancelling every item of an order now, with the totals.
Requires the `read` order permission. Returns `{ orderId, currency, items, totals }`, every amount
in the order currency. Each item has `orderItemId`, `productType` and `status`.
`previewable` items carry `preview`, the same payload as
`GET order-items/{id}/cancellation-preview` (`isRefundable: false` included). An item whose
`actions.cancellation` is `available` is `previewable`, unless its refund failed; a rejected
one previews a full refund with no penalty. `notCancellable` items carry a `reason`:
`notFulfilled` (not delivered: unpaid, still being delivered, or rejected while its outcome is
confirmed), `refunded`, `refundInProgress` (a refund was started and has not finished, or it failed
and cancelling the item retries it), `amendmentInProgress`,
`manualReview` (contact support) or `notAllowed` (the product's rules do not allow cancelling it
now). `totals` sums `penaltyAmount`, `cancellationFee` and `refundAmount` over the
`previewable` items; `totals.isComplete` is `true` only when every item is
`previewable`.
The preview cancels nothing, changes no state and locks no amount: cancelling an item prices its
cancellation again. Only an item the item preview refuses is `notAllowed`: a booking system that cannot answer
right now fails this whole call, with `503` when it is unavailable, as it fails the item preview.
Retry later. An order of another partner, or an unknown id, returns `404` with code `10004`.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `id` | path | yes | `string` | Order id (`id` from the order response). |
## Responses
### 200
OK
- `text/plain`: `OrderCancellationPreview`
- `application/json`: `OrderCancellationPreview`
- `text/json`: `OrderCancellationPreview`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 401
Unauthorized
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 403
Forbidden
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 404
Not Found
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
### 503
Service Unavailable
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Resend a traveller email (/docs/api-reference/orders/resend-email)
`POST /v1/orders/{id}/emails/resend`
Sends an email of a hosted-site order to its traveller again.
For a traveller who did not receive an email. The body names the email: `{"type":"receipt"}`, the receipt
of what was charged to the traveller's card, or `{"type":"delivery","orderItemId":"..."}`, one item's
delivery email (its codes, eSIM installation, top-up or booking confirmation). The email is built as the order
reads now, in the site's brand and the traveller's language, and goes only to the address the traveller gave
at checkout; the body takes no address. Requires the `manage` order permission; a site credential can
send its own site's emails.
Returns `{ orderId, type, orderItemId, recipient }`, the address masked, once the email service took the
email. An order of another partner, or an item not in the order, is `404` / `10004`. An order with
no traveller email address (not placed on a hosted site, or the traveller's details were erased) is
`422` / `18006` (`EMAIL_NOT_SUPPORTED`), reason `NO_TRAVELLER_EMAIL`. An email that cannot
be sent now is `409` / `18007` (`EMAIL_NOT_AVAILABLE`) with `details[0].reason`:
`NOTHING_TO_SEND` (nothing was charged yet, or the item is not delivered yet), `NOT_ELIGIBLE` (the
item was rejected or refunded, its codes are withheld, or what it delivered has ended), `IN_PROGRESS` (a
refund or another change of the order is running; try again shortly), `EMAILS_OFF`, or
`UNSUBSCRIBED` (path `id`: the traveller unsubscribed from the site's emails; it stays so until they
resubscribe). An order's emails
can be sent again five times in any hour, across every credential; past that, `429` / `10006`
(`RATE_LIMITED`), reason `RATE_LIMITED`, with `Retry-After`. A refusal of the email service
is `503` / `10007` (with `Retry-After` when known) or `502` / `10008`; nothing was
sent, so send the same request again.
Requires an `Idempotency-Key` header (a UUID). The same key and body never send twice: a completed request
answers as it did, one still running is `409` / `12002`, and a different body `409` /
`12001`. Sending the email again later needs a new key.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `id` | path | yes | `string` | Order id (`id` from the order response). |
| `Idempotency-Key` | header | yes | `string` | UUID idempotency key for safe retries of this operation. |
## Request body
- `application/json`: `OrderEmailResendRequest`
- `text/json`: `OrderEmailResendRequest`
- `application/*+json`: `OrderEmailResendRequest`
## Responses
### 200
OK
- `text/plain`: `OrderEmailResendResult`
- `application/json`: `OrderEmailResendResult`
- `text/json`: `OrderEmailResendResult`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 401
Unauthorized
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 403
Forbidden
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 404
Not Found
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 409
The idempotency key: a request with this key is still running (12002): send the same request, key and body again after Retry-After seconds; or it was used for a different request (12001). A finished request sent again with the same key and body returns 200 with the result of the first call, rebuilt from the record that call created as it reads now: nothing runs again, and a status that has moved on since shows its current value.
- `application/json`: `ErrorResponse`
### 422
Unprocessable Content
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
### 502
Bad Gateway
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 503
Idempotency state is temporarily unavailable; retry the same request and key.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Search billers (/docs/api-reference/utility/search)
`GET /v1/utility/search`
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.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `countryCode` | query | yes | `string` | Required ISO 3166-1 alpha-2 country code of the billers, in either case. |
| `category` | query | no | `string` | Keep the billers of this category, for example `electricity`. |
| `serviceType` | query | no | `string` | Keep `prepaid` or `postpaid` billers. |
| `q` | query | no | `string` | Text in the biller name, case-insensitive; at most 100 characters, without control characters. |
| `currency` | query | no | `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` | query | no | `integer` | Page number, from 1; default 1. |
| `limit` | query | no | `integer` | Page size, 1 to 100; default 10. |
## Responses
### 200
OK
- `text/plain`: `UtilitySearchResult`
- `application/json`: `UtilitySearchResult`
- `text/json`: `UtilitySearchResult`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Get a biller (/docs/api-reference/utility/get-biller)
`GET /v1/utility/billers/{id}`
Returns one biller with its offers, in the item shape that search returns.
An unknown ID, an ID that does not start with `biller_` (an offer's `publicId` among them), or a
biller without an orderable offer gives 404 / 10004.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `id` | path | yes | `string` | The biller's opaque `id` from search or the catalog, for example `biller_3jx4…`. |
| `currency` | query | no | `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`. |
## Responses
### 200
OK
- `text/plain`: `Biller`
- `application/json`: `Biller`
- `text/json`: `Biller`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Utility catalog (/docs/api-reference/utility/get-catalog)
`GET /v1/utility/catalog`
Returns every biller with its offers, page by page, for partner inventory.
Returns `{ items, nextCursor }`, ordered by biller ID, with the search filters except `q`. Continue
with `nextCursor` as `cursor`, the same filters and the same `currency` until it is null; a page
can hold fewer billers than `limit`, even none, while `nextCursor` is not null. A cursor reused with
other filters or another currency gives 400 / 10001. The walk is not a frozen snapshot: update your copy by
biller `id`, and remove a biller only when a complete walk did not return it. On 429, wait for
`Retry-After` and request the same page again.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `countryCode` | query | no | `string` | Optional ISO 3166-1 alpha-2 country filter, in either case; every country when omitted. A blank value is rejected. |
| `category` | query | no | `string` | Keep the billers of this category, for example `electricity`. |
| `serviceType` | query | no | `string` | Keep `prepaid` or `postpaid` billers. |
| `currency` | query | no | `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`. |
| `cursor` | query | no | `string` | The `nextCursor` of the previous page; omit it for the first page. Reuse it only with the same filters and currency. |
| `limit` | query | no | `integer` | Page size, 1 to 100; default 100. |
## Responses
### 200
OK
- `text/plain`: `UtilityCatalogPage`
- `application/json`: `UtilityCatalogPage`
- `text/json`: `UtilityCatalogPage`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Pay utility bills (/docs/api-reference/utility/create-order)
`POST /v1/utility/order`
Places a utility bill payment 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.
Every price is recalculated: a current price above `inputs.maxPrice` gives 409 / 11002 at
`items[i].inputs.maxPrice` before anything is charged, and without `inputs.maxPrice` the current price
is charged. The item is fulfilled when the payment is confirmed and, for a `token` biller, the
token is returned; track it with 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.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | yes | `string` | UUID idempotency key for safe retries of this operation. |
## Request body
- `application/json`: `UtilityOrderRequest`
- `text/json`: `UtilityOrderRequest`
- `application/*+json`: `UtilityOrderRequest`
## Responses
### 200
OK
- `text/plain`: `UtilityOrder`
- `application/json`: `UtilityOrder`
- `text/json`: `UtilityOrder`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 402
Payment Required
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 409
The offer changed since it was quoted: its price rose (11002, for products that check the quoted price) or it is no longer available (11003). Or the idempotency key: a request with this key is still running (12002): send the same request, key and body again after Retry-After seconds; it was used for a different request (12001); or its history is ambiguous.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
### 503
Idempotency state is temporarily unavailable; retry the same request and key.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Quote utility payments (/docs/api-reference/utility/quote)
`POST /v1/utility/quote`
Prices the order body with current prices, without placing an order.
Takes the same body as order, with offer public IDs; a biller's own ID is not an offer (400 / 11004). Each
item is priced on its own, in request order; the first failing item aborts the quote and is named at
`items[i]`, for example 409 / 11002 at `items[i].inputs.maxPrice` when the current price is above it.
A quote reserves nothing, does not expire, submits no payment and does not check the customer's account with
the biller.
## Request body
- `application/json`: `UtilityOrderRequest`
- `text/json`: `UtilityOrderRequest`
- `application/*+json`: `UtilityOrderRequest`
## Responses
### 200
OK
- `text/plain`: `UtilityQuote`
- `application/json`: `UtilityQuote`
- `text/json`: `UtilityQuote`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 409
Conflict
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# List wallets (/docs/api-reference/wallets/get-all)
`GET /v1/wallets`
Lists all of the partner's wallets.
Returns the whole list as an array, without paging. Each wallet has its `id`, `label`,
`balance`, whether it `isSelected` (the wallet that pays for orders) and its `currency`.
## Responses
### 200
OK
- `text/plain`: `WalletSummary[]`
- `application/json`: `WalletSummary[]`
- `text/json`: `WalletSummary[]`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 401
Unauthorized
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Create a wallet (/docs/api-reference/wallets/create)
`POST /v1/wallets`
Creates an empty wallet in a currency the partner has no wallet in yet.
Take `currencyId` from `GET currencies`. The new wallet starts with a zero balance. Without a
`label` it is named after its currency, for example `USD wallet`. The partner's first wallet is
always selected; for a later one, `isSelected: true` makes it the selected wallet in place of the
current one. Returns `201` without a body; list the wallets to read it.
A second wallet in the same currency returns `400` with code `17000`
(`WALLET_CURRENCY_ALREADY_EXISTS`); a label already used by another of the partner's wallets,
ignoring case, returns `400` with code `17001` (`WALLET_LABEL_ALREADY_EXISTS`).
## Request body
- `application/json`: `WalletCreateRequest`
- `text/json`: `WalletCreateRequest`
- `application/*+json`: `WalletCreateRequest`
## Responses
### 201
Created
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 401
Unauthorized
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 403
Forbidden
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Get a wallet (/docs/api-reference/wallets/get-by-id)
`GET /v1/wallets/{id}`
Gets one wallet with its totals.
Adds `lowBalanceThreshold`, `createdAt`, `updatedAt` and totals of completed transactions to
the list fields. An unknown wallet, or one of another partner, returns `404` with code `10004`.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `id` | path | yes | `string` | Wallet id. |
## Responses
### 200
OK
- `text/plain`: `Wallet`
- `application/json`: `Wallet`
- `text/json`: `Wallet`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 401
Unauthorized
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 404
Not Found
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Update a wallet (/docs/api-reference/wallets/update)
`PATCH /v1/wallets/{id}`
Renames a wallet or changes its low-balance threshold.
Only the members in the body change; a member left out keeps its value. Send at least one member: an
empty body returns `400` with code `10001` and `REQUIRED` at `$`. `label` cannot
be `null` or blank (`INVALID_VALUE` at `label`); `lowBalanceThreshold: null` clears
the threshold. The wallet id comes from the route only: any other member, such as `walletId`, returns
`400` with code `10001` at its path. A label already used by another of the partner's wallets,
ignoring case, returns `400` with code `17001` (`WALLET_LABEL_ALREADY_EXISTS`); an unknown
wallet returns `404` with code `10004`.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `id` | path | yes | `string` | Wallet id. |
## Request body
- `application/json`: `WalletUpdateRequest`
- `text/json`: `WalletUpdateRequest`
- `application/*+json`: `WalletUpdateRequest`
## Responses
### 204
No Content
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 403
Forbidden
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Select a wallet (/docs/api-reference/wallets/select)
`PATCH /v1/wallets/select/{id}`
Makes a wallet the partner's selected wallet, which pays for new orders.
Exactly one wallet is selected at a time; the previously selected wallet is deselected. An unknown wallet
returns `404` with code `10004` and leaves the current selection unchanged.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `id` | path | yes | `string` | Wallet id to select. |
## Responses
### 204
No Content
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 401
Unauthorized
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 403
Forbidden
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 404
Not Found
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# Transfer between wallets (/docs/api-reference/wallets/transfer)
`POST /v1/wallets/transfer`
Moves funds from one of the partner's wallets to another, converting between their currencies.
`amount` is in the source wallet's currency and has at most that currency's ISO 4217 decimals (none
in `KRW` or `JPY`, three in `KWD`, two in most); more decimals return `400` with code
`10001` and `INVALID_VALUE` at `amount`, whose `message` names the decimals allowed,
such as `An amount in JPY cannot have decimals.` The destination receives the amount converted at
the current rate, rounded to its own currency's decimals. Returns the `transferId`, the sent
and received amounts and currencies, the `conversionRate` and the `transferDate`. Both wallets
record an `exchange` transaction.
The two wallets must differ, and the amount must be above zero; otherwise the call returns `400` with
code `10001`. An unknown wallet returns `404` with code `10004`. A source wallet that cannot
pay the amount now returns `409` with code `10005` (`CONFLICT`) and
`details[0] = { path: "fromWalletId", reason }`: `INSUFFICIENT_BALANCE` when its balance is too
low, `WALLET_BLOCKED` while its spending is blocked. The same request can succeed once that changes.
Requires an `Idempotency-Key` header (a UUID). Repeating a completed transfer with the same key and body
returns `200` with that transfer, the same `transferId` and amounts, and moves no money again. One
still running returns `409` with code `12002` (`IDEMPOTENCY_KEY_IN_PROGRESS`) and a
`Retry-After` header, and a different body with the same key `409` with code `12001`. A
request that ended in an error can be sent again with the same key and body.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | yes | `string` | UUID idempotency key for safe retries of this operation. |
## Request body
- `application/json`: `WalletTransferRequest`
- `text/json`: `WalletTransferRequest`
- `application/*+json`: `WalletTransferRequest`
## Responses
### 200
OK
- `text/plain`: `WalletTransfer`
- `application/json`: `WalletTransfer`
- `text/json`: `WalletTransfer`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 401
Unauthorized
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 403
Forbidden
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 404
Not Found
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 409
The idempotency key: a request with this key is still running (12002): send the same request, key and body again after Retry-After seconds; or it was used for a different request (12001). A finished request sent again with the same key and body returns 200 with the result of the first call, rebuilt from the record that call created as it reads now: nothing runs again, and a status that has moved on since shows its current value.
- `application/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
### 503
Idempotency state is temporarily unavailable; retry the same request and key.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# List wallet transactions (/docs/api-reference/wallets/get-transactions)
`GET /v1/wallets/{walletId}/transactions`
Lists a wallet's transactions, newest first, with optional filters.
Returns `{ transactions, pagination }`. In a transaction, `type` `debit` takes funds from the
wallet and `credit` adds funds to it; `source` says why (`topUp`, `payOut`,
`order`, `exchange` or `reversal`), and `orderId` names the order a payment or refund
belongs to. Filters combine with AND and apply before counting and paging.
Use flat `page` (default 1) and `limit` (default 10, 1 to 100) query parameters.
`cursor`, `skip`, `offset`, nested paging keys and repeated paging parameters return
`400` with code `10001` (`INVALID_REQUEST`). An unknown wallet returns `404` with code
`10004`.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `walletId` | path | yes | `string` | Wallet id. |
| `page` | query | no | `integer` | One-based page number. Default 1. |
| `limit` | query | no | `integer` | Page size, 1 to 100. Default 10. |
| `startDate` | query | no | `string` | Only transactions made at or after this time (UTC). ISO 8601 date-time. A value with Z or an offset is converted to UTC; a value without a zone is read as UTC, and a date alone means 00:00 UTC on that day. |
| `endDate` | query | no | `string` | Only transactions made at or before this time (UTC). ISO 8601 date-time. A value with Z or an offset is converted to UTC; a value without a zone is read as UTC, and a date alone means 00:00 UTC on that day. |
| `type` | query | no | `string` | Only this direction: `debit` takes funds from the wallet, `credit` adds funds to it. |
| `source` | query | no | `string` | Only transactions with this cause, such as `order` or `exchange`. |
## Responses
### 200
OK
- `text/plain`: `WalletTransactionList`
- `application/json`: `WalletTransactionList`
- `text/json`: `WalletTransactionList`
### 400
Invalid partner request or model validation failure.
- `application/json`: `ErrorResponse`
### 401
Unauthorized
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 404
Not Found
- `text/plain`: `ErrorResponse`
- `application/json`: `ErrorResponse`
- `text/json`: `ErrorResponse`
### 429
Too many requests from this IP address. Wait for Retry-After seconds, then send the same request again; an order keeps its Idempotency-Key and body.
- `application/json`: `ErrorResponse`
The full schemas are in the OpenAPI specification at /openapi.json.
# The delivery of an order's items changed: delivered, rejected, or a delivered result was revised. (/docs/api-reference/webhooks/order-fulfillment-updated)
Webhook `order.fulfillment.updated`: OpenRoam sends a `POST` to your endpoint.
Delivered at least once to your webhook URL. Acknowledge with any `2xx` response. A signed body with `isTest: true` contains synthetic data and should be handled as a connectivity check.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `X-OpenRoam-Webhook-Id` | header | yes | `string` | The id of the webhook subscription that delivers the event. |
| `X-OpenRoam-Timestamp` | header | yes | `string` | When this delivery attempt was signed, in Unix seconds. |
| `X-OpenRoam-Event-Id` | header | yes | `string` | The event's unique id, the same as `eventId` in the body. Deduplicate on it. |
| `X-OpenRoam-Signature` | header | yes | `string` | Lowercase hex HMAC-SHA256 of `{timestamp}.{eventId}.{raw body}`, keyed with your webhook secret. |
## Request body
- `application/json`: `OrderFulfillmentWebhook`
## Responses
### 200
The event was accepted.
The full schemas are in the OpenAPI specification at /openapi.json.
# The profile status of an eSIM changed. (/docs/api-reference/webhooks/esim-profile-status-updated)
Webhook `esim.profileStatus.updated`: OpenRoam sends a `POST` to your endpoint.
Delivered at least once to your webhook URL. Acknowledge with any `2xx` response. A signed body with `isTest: true` contains synthetic data and should be handled as a connectivity check.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `X-OpenRoam-Webhook-Id` | header | yes | `string` | The id of the webhook subscription that delivers the event. |
| `X-OpenRoam-Timestamp` | header | yes | `string` | When this delivery attempt was signed, in Unix seconds. |
| `X-OpenRoam-Event-Id` | header | yes | `string` | The event's unique id, the same as `eventId` in the body. Deduplicate on it. |
| `X-OpenRoam-Signature` | header | yes | `string` | Lowercase hex HMAC-SHA256 of `{timestamp}.{eventId}.{raw body}`, keyed with your webhook secret. |
## Request body
- `application/json`: `EsimProfileStatusWebhook`
## Responses
### 200
The event was accepted.
The full schemas are in the OpenAPI specification at /openapi.json.
# The data or expiry usage of an eSIM reached a new band. (/docs/api-reference/webhooks/esim-usage-updated)
Webhook `esim.usage.updated`: OpenRoam sends a `POST` to your endpoint.
Delivered at least once to your webhook URL. Acknowledge with any `2xx` response. A signed body with `isTest: true` contains synthetic data and should be handled as a connectivity check.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `X-OpenRoam-Webhook-Id` | header | yes | `string` | The id of the webhook subscription that delivers the event. |
| `X-OpenRoam-Timestamp` | header | yes | `string` | When this delivery attempt was signed, in Unix seconds. |
| `X-OpenRoam-Event-Id` | header | yes | `string` | The event's unique id, the same as `eventId` in the body. Deduplicate on it. |
| `X-OpenRoam-Signature` | header | yes | `string` | Lowercase hex HMAC-SHA256 of `{timestamp}.{eventId}.{raw body}`, keyed with your webhook secret. |
## Request body
- `application/json`: `EsimUsageWebhook`
## Responses
### 200
The event was accepted.
The full schemas are in the OpenAPI specification at /openapi.json.
# A wallet balance fell to a lower low-balance threshold band. (/docs/api-reference/webhooks/partner-balance-low)
Webhook `partner.balance.low`: OpenRoam sends a `POST` to your endpoint.
Delivered at least once to your webhook URL. Acknowledge with any `2xx` response. A signed body with `isTest: true` contains synthetic data and should be handled as a connectivity check.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `X-OpenRoam-Webhook-Id` | header | yes | `string` | The id of the webhook subscription that delivers the event. |
| `X-OpenRoam-Timestamp` | header | yes | `string` | When this delivery attempt was signed, in Unix seconds. |
| `X-OpenRoam-Event-Id` | header | yes | `string` | The event's unique id, the same as `eventId` in the body. Deduplicate on it. |
| `X-OpenRoam-Signature` | header | yes | `string` | Lowercase hex HMAC-SHA256 of `{timestamp}.{eventId}.{raw body}`, keyed with your webhook secret. |
## Request body
- `application/json`: `BalanceLowWebhook`
## Responses
### 200
The event was accepted.
The full schemas are in the OpenAPI specification at /openapi.json.
# A refund of an order item progressed or finished. (/docs/api-reference/webhooks/order-item-refunded)
Webhook `order-item.refunded`: OpenRoam sends a `POST` to your endpoint.
Delivered at least once to your webhook URL. Acknowledge with any `2xx` response. A signed body with `isTest: true` contains synthetic data and should be handled as a connectivity check.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `X-OpenRoam-Webhook-Id` | header | yes | `string` | The id of the webhook subscription that delivers the event. |
| `X-OpenRoam-Timestamp` | header | yes | `string` | When this delivery attempt was signed, in Unix seconds. |
| `X-OpenRoam-Event-Id` | header | yes | `string` | The event's unique id, the same as `eventId` in the body. Deduplicate on it. |
| `X-OpenRoam-Signature` | header | yes | `string` | Lowercase hex HMAC-SHA256 of `{timestamp}.{eventId}.{raw body}`, keyed with your webhook secret. |
## Request body
- `application/json`: `OrderItemRefundedWebhook`
## Responses
### 200
The event was accepted.
The full schemas are in the OpenAPI specification at /openapi.json.
# A manual amendment request progressed, or needs your action. (/docs/api-reference/webhooks/order-item-manual-amendment-status)
Webhook `order-item.manual-amendment.status`: OpenRoam sends a `POST` to your endpoint.
Delivered at least once to your webhook URL. Acknowledge with any `2xx` response. A signed body with `isTest: true` contains synthetic data and should be handled as a connectivity check.
## Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `X-OpenRoam-Webhook-Id` | header | yes | `string` | The id of the webhook subscription that delivers the event. |
| `X-OpenRoam-Timestamp` | header | yes | `string` | When this delivery attempt was signed, in Unix seconds. |
| `X-OpenRoam-Event-Id` | header | yes | `string` | The event's unique id, the same as `eventId` in the body. Deduplicate on it. |
| `X-OpenRoam-Signature` | header | yes | `string` | Lowercase hex HMAC-SHA256 of `{timestamp}.{eventId}.{raw body}`, keyed with your webhook secret. |
## Request body
- `application/json`: `ManualAmendmentStatusWebhook`
## Responses
### 200
The event was accepted.
The full schemas are in the OpenAPI specification at /openapi.json.