Skip to Content
OpenRoam Docs
Orders

Preview an order cancellation

Previews cancelling every item of an order now, with the totals.

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.

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

A preview of cancelling every item of an order now. It changes nothing and does not lock the amounts.

orderId*string

Order id.

Formatuuid
currency*string

The order's currency; every amount is in it.

items*array<>

One entry per order item.

totals*

The sums over the previewable items.

Example Request
curl -X GET 'https://api.sandbox.openroam.com/v1/orders/01a1432e-7121-7b0e-a0a0-c35454d3b883/cancellation-preview'
Example Response
{  "orderId": "b3e1eced-f2bd-4d8c-9765-fbc9d1d222d5",  "currency": "string",  "items": [    {      "orderItemId": "33207bce-c741-4896-a76b-8afcf6e4179a",      "productType": "esim",      "status": "previewable",      "reason": "notFulfilled",      "preview": {        "penaltyAmount": {          "amount": 0,          "currency": "string"        },        "cancellationFee": {          "amount": 0,          "currency": "string"        },        "refundAmount": {          "amount": 0,          "currency": "string"        },        "isRefundable": true,        "appliedPenalties": [          {            "from": "2019-08-24T14:15:22Z",            "fromLocalTime": "2026-12-01T08:30:00",            "timezone": "string",            "penaltyAmount": {              "amount": 0,              "currency": "string"            }          }        ],        "effectiveCancellationDate": "2019-08-24T14:15:22Z",        "checkInDate": "2019-08-24"      }    }  ],  "totals": {    "penaltyAmount": {      "amount": 0,      "currency": "string"    },    "cancellationFee": {      "amount": 0,      "currency": "string"    },    "refundAmount": {      "amount": 0,      "currency": "string"    },    "isComplete": true  }}

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

Get fulfillment status GET

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