Preview an order cancellation
Previews cancelling every item of an order now, with the totals.
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.
PartnerApiKeyX-Partner-Key<token>Partner API Key (X-Partner-Key)
id*stringOrder id (id from the order response).
uuidOK
- response
A preview of cancelling every item of an order now. It changes nothing and does not lock the amounts.
orderId*stringOrder id.
uuidcurrency*stringThe order's currency; every amount is in it.
items*array<>One entry per order item.
totals*The sums over the previewable items.
curl -X GET 'https://api.sandbox.openroam.com/v1/orders/01a1432e-7121-7b0e-a0a0-c35454d3b883/cancellation-preview'{ "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`.