Cancel an item
Cancels an order item and refunds what was paid for it, less any cancellation penalty.
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.
PartnerApiKeyX-Partner-Key<token>Partner API Key (X-Partner-Key)
id*stringOrder item id (items[].id from the order response).
uuidIdempotency-Key*stringUUID idempotency key for safe retries of this operation.
uuidThe cancellation reason.
- body
The reason for refunding an order item.
reason*stringRequired. Why the item is refunded: requestedByCustomer, duplicate, fraudulent, or
fulfillmentFailed, which is accepted only for an item whose fulfillment was rejected.
"requestedByCustomer""duplicate""fraudulent""fulfillmentFailed"OK
- response
The refund of an order item.
orderItemId*stringThe refunded order item.
uuidamount*The amount refunded, in the order's currency.
method*stringHow the amount is returned; balance returns it to the wallet that paid.
"balance""card"status*stringRefund status: refunded when complete; pending or processing while it
settles; failed when it did not complete.
"pending""refunded""failed""processing"wallet?|The wallet the refund was returned to and the amount it received, in the wallet's currency;
null until money is back in a wallet, and for a refund to a card.
curl -X POST 'https://api.sandbox.openroam.com/v1/order-items/01a1432e-7121-7b0e-a0a0-c35454d3b883/cancel' \ -H 'Idempotency-Key: 0b8f7f3e-6b7a-4a52-9a5e-3d2f1a9c7e10' \ -H 'Content-Type: application/json' \ -d '{ "reason": "requestedByCustomer"}'{ "orderItemId": "33207bce-c741-4896-a76b-8afcf6e4179a", "amount": { "amount": 0, "currency": "string" }, "method": "balance", "status": "pending", "wallet": { "label": "string", "credited": { "amount": 0, "currency": "string" } }}Resend a traveller email POST
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.
Confirm an amendment POST
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.