Skip to Content
OpenRoam Docs
Order items

Cancel an item

Cancels an order item and refunds what was paid for it, less any cancellation penalty.

POST
/v1/order-items/{id}/cancel

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.

Authorization

PartnerApiKey
headerX-Partner-Key<token>

Partner API Key (X-Partner-Key)

Path Parameters

id*string

Order item id (items[].id from the order response).

Formatuuid

Header Parameters

Idempotency-Key*string

UUID idempotency key for safe retries of this operation.

Formatuuid

Request Body

The cancellation reason.

  1. body

The reason for refunding an order item.

reason*string

Required. Why the item is refunded: requestedByCustomer, duplicate, fraudulent, or fulfillmentFailed, which is accepted only for an item whose fulfillment was rejected.

Value in"requestedByCustomer""duplicate""fraudulent""fulfillmentFailed"

Response Body

OK

  1. response

The refund of an order item.

orderItemId*string

The refunded order item.

Formatuuid
amount*

The amount refunded, in the order's currency.

method*string

How the amount is returned; balance returns it to the wallet that paid.

Value in"balance""card"
status*string

Refund status: refunded when complete; pending or processing while it settles; failed when it did not complete.

Value in"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.

Example Request
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"}'
Example Response
{  "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.