Skip to Content
OpenRoam Docs
Orders

List orders

Lists the partner's orders, newest first, with optional filters.

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).

Authorization

PartnerApiKey
headerX-Partner-Key<token>

Partner API Key (X-Partner-Key)

Query Parameters

page?integer

One-based page number. Default 1.

Formatint32
limit?integer

Page size, 1 to 100. Default 10.

Formatint32
startDate?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.

Formatdate-time
endDate?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.

Formatdate-time
minAmount?number

Only orders whose total.amount, in the order's currency, is at least this value.

Formatdecimal
maxAmount?number

Only orders whose total.amount, in the order's currency, is at most this value.

Formatdecimal
search?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?string

Only the order with exactly this referenceId.

channel?string

Only orders created through this channel, the same values as origin.channel: api, dashboard or site.

Value in"api""dashboard""site"
productTypes?array<>

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?array<>

Only orders currently in one of these statuses, the same values as status. Repeat the parameter for several statuses.

Response Body

OK

  1. response

A page of orders, newest first.

orders*array<>

The orders on this page.

pagination*

Paging of the list.

Example Request
curl -X GET 'https://api.sandbox.openroam.com/v1/orders?page=1&limit=10&startDate=2026-10-01T00%3A00%3A00Z&endDate=2026-10-31T23%3A59%3A59Z&referenceId=partner-order-42'
Example Response
{  "orders": [    {      "id": "01a14340-7a10-7c55-a1f2-9b3d5e7f0a11",      "referenceId": "trip-42",      "origin": {        "channel": "api"      },      "status": "processing",      "total": {        "amount": 50,        "currency": "USD"      },      "refunded": {        "amount": 0,        "currency": "USD"      },      "payment": {        "status": "completed",        "method": "balance",        "amount": {          "amount": 50,          "currency": "USD"        },        "wallet": {          "label": "Main wallet",          "debited": {            "amount": 50,            "currency": "USD"          }        },        "failure": null      },      "itemCount": 2,      "createdAt": "2026-10-16T05:27:59.521962Z",      "updatedAt": "2026-10-16T05:27:59.521962Z"    },    {      "id": "01a1432e-7121-7b0e-a0a0-c35454d3b883",      "referenceId": "partner-order-42",      "origin": {        "channel": "api"      },      "status": "completed",      "total": {        "amount": 56.25,        "currency": "USD"      },      "refunded": {        "amount": 0,        "currency": "USD"      },      "payment": {        "status": "completed",        "method": "balance",        "amount": {          "amount": 56.25,          "currency": "USD"        },        "wallet": {          "label": "Main wallet",          "debited": {            "amount": 56.25,            "currency": "USD"          }        },        "failure": null      },      "itemCount": 2,      "createdAt": "2026-10-16T05:27:59.521962Z",      "updatedAt": "2026-10-16T05:28:03.118204Z"    }  ],  "pagination": {    "currentCount": 2,    "totalCount": 2,    "skip": 0,    "limit": 10,    "hasMore": false,    "page": 1,    "totalPages": 1  }}

Create an order POST

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.

Get an order GET

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`.