Skip to Content
OpenRoam Docs
Orders

Get an order

Gets the current state of one order.

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.

Authorization

PartnerApiKey
headerX-Partner-Key<token>

Partner API Key (X-Partner-Key)

Path Parameters

id*string

Order id (id from the order response).

Formatuuid

Response Body

OK

  1. response

The current state of an order.

id*string

Order id.

Formatuuid
origin*

Where the order was created.

status*string

Current order status: paymentPending, processing, completed, partiallyFulfilled, fulfillmentFailed, partiallyRefunded, refunded or cancelled.

Value in"paymentPending""processing""completed""partiallyFulfilled""fulfillmentFailed""partiallyRefunded""refunded""cancelled"
total*

What was charged for the order, in the order's currency, before refunds: the item prices plus completed amendment charges, less completed amendment credits.

refunded*

What completed item refunds returned, in the order's currency; zero when nothing was returned. You paid total minus refunded, the sum of the items' effectivePaidAmount.

payment?|

The latest payment attempt; null when none was made.

items*array<|||||>

The order items, one per unit bought.

timeline*array<>

Every status the order has had, oldest first, each once per stretch.

createdAt*string

When the order was created (UTC).

Formatdate-time
updatedAt*string

When anything in the order last changed (UTC): its status, an item's fulfillment, a refund or an amendment.

Formatdate-time
fulfillmentVersion*integer

Increases with every fulfillment change; matches the order.fulfillment.updated webhook.

Formatint64
referenceId?|

Your own order reference, when one was sent.

customer?|

The traveller who paid on your hosted site, masked; null unless the origin is site, and once the traveller's details are deleted at the end of their retention period.

Example Request
curl -X GET 'https://api.sandbox.openroam.com/v1/orders/01a1432e-7121-7b0e-a0a0-c35454d3b883'
Example Response
{  "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  },  "items": [    {      "id": "01a1432e-7121-70bc-800a-3f896e23b7c8",      "orderId": "01a1432e-7121-7b0e-a0a0-c35454d3b883",      "productType": "airtime",      "price": {        "amount": 25,        "currency": "USD"      },      "purchasedProduct": {        "name": "Test operator 40 AZN",        "countryCode": "AZ",        "logoUrl": "https://cdn.openroam.test/airtime/test-operator.png",        "value": {          "amount": 40,          "currency": "AZN"        },        "inputs": {          "phoneNumber": "+994***4567",          "minDeliveredValue": null        },        "details": {          "redemptionType": "directTopUp",          "estimatedDeliveredValue": {            "amount": 40,            "currency": "AZN"          },          "readMore": "Credit arrives within minutes."        }      },      "fulfillment": {        "status": "fulfilled",        "result": {          "deliveredValue": {            "amount": 40,            "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": 25,        "currency": "USD"      }    },    {      "id": "01a1432e-7121-7829-a554-d8e2b22270c6",      "orderId": "01a1432e-7121-7b0e-a0a0-c35454d3b883",      "productType": "airtime",      "price": {        "amount": 31.25,        "currency": "USD"      },      "purchasedProduct": {        "name": "Test operator 50 AZN",        "countryCode": "AZ",        "logoUrl": "https://cdn.openroam.test/airtime/test-operator.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"      }    }  ],  "timeline": [    {      "status": "paymentPending",      "occurredAt": "2026-10-16T05:27:59.521962Z"    },    {      "status": "processing",      "occurredAt": "2026-10-16T05:27:59.521962Z"    },    {      "status": "completed",      "occurredAt": "2026-10-16T05:28:03.118204Z"    }  ],  "createdAt": "2026-10-16T05:27:59.521962Z",  "updatedAt": "2026-10-16T05:28:03.118204Z",  "fulfillmentVersion": 2}

List orders GET

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

Preview an order cancellation GET

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