Skip to Content
OpenRoam Docs
Order items

Preview an item cancellation

Previews the cancellation penalty and expected refund for an order item.

GET
/v1/order-items/{id}/cancellation-preview

Previews the cancellation penalty and expected refund for an order item.

Requires the read order permission. Returns penaltyAmount, the cancellationFee kept in addition to it (null when none applies) and the expected refundAmount, all in the order currency, isRefundable, the cancellation band in effect, priced at the penalty (appliedPenalties: at most one { from, penaltyAmount }), effectiveCancellationDate and checkInDate, calculated with the same rules as the partner portal. The fee comes out of what the penalty leaves, so the refund is never negative. isRefundable: false means the penalty alone keeps the whole price, so the item cannot be cancelled; it is not an error. A fee that takes what the penalty leaves does not make it false: the item can still be cancelled, with a refund of 0. The preview does not cancel the item or change its state, and it does not lock the penalty: the cancel call recalculates it, so a later cancellation band may apply.

The preview refuses what the cancel refuses. 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, when the item's actions.cancellation is not available, it returns 409 with code 18001 (CANCELLATION_NOT_AVAILABLE), and details[0].reason repeats actions.cancellation.availability. A refund started by OpenRoam support returns the same 409 with MANUAL_REVIEW. A delivered item is priced with its product's cancellation rules. An item that was not delivered has no cancellation to price: a rejected item whose automatic refund has not started previews a full refund of what was paid (after a failed refund, the amounts that refund is retried with), with a penaltyAmount of 0 and no cancellationFee or appliedPenalties. A cancellation the product refuses, for example after check-out, returns 400 with code 10001. An item 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 item id (items[].id from the order response).

Formatuuid

Response Body

OK

  1. response

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

penaltyAmount*

The penalty that would be kept, in the order currency.

cancellationFee?|

A cancellation fee taken in addition to the penalty, in the order currency; null when none applies. It comes out of what the penalty leaves, so it never makes the refund negative.

refundAmount*

The amount that would be refunded, in the order currency: what was paid less the penalty and the cancellation fee.

isRefundable*boolean

Whether anything would be refunded; false is not an error.

appliedPenalties?array<>|

The cancellation band in effect now, priced at penaltyAmount: at most one entry. Empty when the item's bands have not started yet; null when it states none.

effectiveCancellationDate*string

The cancellation time the preview is calculated for (UTC).

Formatdate-time
checkInDate?|

The check-in date of the booked stay; null for an item that has no stay, such as a flight.

Formatdate
Example Request
curl -X GET 'https://api.sandbox.openroam.com/v1/order-items/01a1432e-7121-7b0e-a0a0-c35454d3b883/cancellation-preview'
Example Response
{  "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"}

Get an order item GET

Gets an order item: what was bought, its delivery, its refund and what you can do next. Requires the `read` order permission. Returns the item exactly as it appears in `items[]` of the order response, including `orderId`, the order it belongs to. `fulfillment.status` and `refund.status` give its state; `actions.cancellation` says whether it can be cancelled now, `actions.amendment` whether it can be amended and `actions.update` whether it can be updated. An item of another partner, or an unknown id, returns `404` with code `10004`; a malformed id or an unknown query parameter returns `400` with code `10001`.

List partner amendments GET

Lists amendments across the authenticated partner's orders. Requires the read order permission. Includes manual and automatic amendments in all statuses. Optional repeated statuses, productType, amendmentMode, orderId, orderItemId and inclusive UTC from/to timestamps filter the result. Use flat page (default 1) and limit (default 10, maximum 100) query parameters. Nested paging keys return 400 with code 10001. Amounts retain their original currency; a quote does not imply settlement. Example response: ```{"items":[{"id":"b7428a30-f760-46e8-b504-a670bf9bed19","orderId":"a46ee792-287e-44ef-a641-48de1a0f72fd","orderItemId":"cf4a49ac-b785-43d4-912a-4be3443e48bd","productType":"hotel","amendmentMode":"manual","status":"quoted","createdAt":"2026-11-03T09:00:00Z","amountToPay":{"amount":25,"currency":"USD"},"amountToRefund":{"amount":0,"currency":"USD"}}],"pagination":{"currentCount":1,"totalCount":1,"skip":0,"limit":10,"hasMore":false,"page":1,"totalPages":1}}```