# Hotels (/docs/products/hotels)

## What you can sell [#what-you-can-sell]

Hotel stays, booked and paid in advance. You search a place (or a list of hotels) for dates, rooms and a guest market,
pick a rate, quote it, and book it in the name of a lead guest. Every price you see is for the whole stay: all rooms
and all nights.

This page covers what is specific to hotels. Authentication, environments, idempotency, errors, webhooks and the
order envelope are shared by every product:
[Quickstart](/docs/quickstart), [Authentication](/docs/authentication), [Environments](/docs/environments),
[Idempotency](/docs/idempotency), [Errors](/docs/errors), [Webhooks](/docs/webhooks) and [Orders](/docs/orders).

## The flow [#the-flow]

| Step | Route |
|---|---|
| Find a place by name (optional) | [`GET /v1/hotels/destinations`](/docs/api-reference/hotels/get-destinations) |
| Search hotels and their offers | [`POST /v1/hotels/search`](/docs/api-reference/hotels/search) |
| Read one hotel's content (optional) | [`GET /v1/hotels/properties/{id}`](/docs/api-reference/hotels/get-property) |
| Quote a rate | [`POST /v1/hotels/quote`](/docs/api-reference/hotels/quote) |
| Book it | [`POST /v1/hotels/order`](/docs/api-reference/hotels/create-order) |

Reference data routes:

- [`GET /v1/hotels/amenities/catalog`](/docs/api-reference/hotels/get-amenity-catalog) lists every amenity code and
  group with a label, to label `details.amenityGroups` and to fill the `amenityCodes` filter. Labels follow the
  `Accept-Language` header.
- [`GET /v1/hotels/catalog/files`](/docs/api-reference/hotels/get-catalog-files) links downloadable files of the whole
  hotel catalog, so you can build hotel pages up front. The files hold content only, never prices.

Four things work differently from the other products:

- **Search is a POST with a JSON body.** Rooms with child ages do not fit a query string. It is the one route that
  does not browse with GET.
- **Offers expire.** An offer's `publicId` (`rate_...`) is accepted until `details.expiresAt`, at most 30 minutes after
  the search.
- **Quote returns a new `publicId`.** It prices the rate again and returns a fresh `publicId` at the quoted price. A
  quote reserves nothing and charges nothing.
- **A price cap protects the order.** See [Price cap at order](#price-cap-at-order).

Every route needs your partner key and hotels enabled for your account. Only `order` also needs the `manage`
permission and an `Idempotency-Key` header.

## Search [#search]

```bash
curl -X POST https://api.sandbox.openroam.com/v1/hotels/search \
  -H "X-Partner-Key: $OPENROAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "searchCriteria": { "location": { "cityCode": "DXB" } },
    "checkIn": "2027-03-10",
    "checkOut": "2027-03-13",
    "rooms": [ { "adults": 2, "children": 1, "childrenAges": [7] } ],
    "guestNationality": "GB",
    "currency": "USD",
    "filters": { "minStarRating": 4, "boardTypes": ["breakfast"], "maxPrice": 900 },
    "limit": 20
  }'
```

| Field | Required | Rules |
|---|---|---|
| `searchCriteria` | yes | `location` or `hotelIds`. A non-empty `hotelIds` wins and `location` is then ignored. |
| `searchCriteria.location` | one of the two | An area by `geoNodeId` (an id from the destinations route), `cityCode` (three characters) or `coordinates` with `radiusKm`. When several are sent, `geoNodeId` wins over `cityCode`, and `cityCode` over `coordinates`. |
| `searchCriteria.hotelIds` | one of the two | Up to 50 hotel ids (`hotel_...`) from an earlier search. Returns every rate of those hotels with the full detail, as one page. |
| `checkIn`, `checkOut` | yes | Dates (`yyyy-MM-dd`). `checkIn` is today or later in the hotel's time zone, and `checkOut` is after it and at most 30 nights later. |
| `rooms` | yes | 1 to 9 rooms. Each has `adults` (1 to 9, default 2), `children` (0 to 9) and, when `children` is above 0, exactly one age (0 to 17) per child in `childrenAges`. A room is matched by its 1-based position when you order. |
| `guestNationality` | yes | ISO 3166-1 alpha-2, for example `GB`. Rates are priced for this market. |
| `guestCountryOfResidence` | no | ISO 3166-1 alpha-2. Defaults to `guestNationality`. |
| `currency` | no | Three letters. Defaults to your API key's currency. |
| `filters` | no | `minStarRating`, `maxStarRating`, `minPrice`, `maxPrice` (for the whole stay), `boardTypes`, `amenityCodes` and `cancellationTypes`. No other member is accepted. |
| `cursor`, `limit` | no | Location searches only. `limit` is 1 to 50 (default 20). |

Coordinates search uses `radiusKm` from 1 to 150 km. There is no free-text name search on this route: use
[`GET /v1/hotels/destinations?q=`](/docs/api-reference/hotels/get-destinations) to turn a name into a `geoNodeId`.
Place ids are stable, so resolve one once and keep it. Every object of the body rejects an unknown member with
`400 / 10001` at its JSON path.

Filter details:

- `boardTypes` takes `roomOnly`, `breakfast`, `halfBoard`, `fullBoard` or `allInclusive`.
- `cancellationTypes` takes `fullyRefundable`, `partiallyRefundable` or `nonRefundable`, matched against the offer's
  `details.terms.cancellation.type`. It is judged on the terms stated now: a free window that has already closed does
  not count.
- `amenityCodes` takes codes from the amenity catalog. A hotel must have all of them.

### Paging [#paging]

A location search returns hotels with a cursor. Send the response's `nextCursor` back as `cursor`, with the same body,
until it is null. A page can hold fewer hotels than `limit`, even none, while `nextCursor` is still set, because hotels
without an orderable offer are left out: keep paging until `nextCursor` is null. A search with `hotelIds` is one
complete page.

### Location search and `hotelIds` search [#location-search-and-hotelids-search]

A location search keeps pages small: each hotel has one offer (its cheapest rate that matches), offers have empty
`nightlyPrices` and `surcharges`, and a hotel has no `description` and at most one image. To see every rate of a hotel
with the full detail, search again with that hotel's `id` in `searchCriteria.hotelIds`, using the same stay, rooms,
market and currency.

A hotel `id` from the OpenRoam catalog is stable. A hotel outside the catalog gets a temporary id that stops working
after 30 minutes, so do not store it.

### Response [#response]

```json
{
  "items": [
    {
      "id": "hotel_example1234567890abcdefgh",
      "name": "Hotel Example",
      "countryCode": "AE",
      "category": null,
      "logoUrl": "https://cdn.example.com/hotel.jpg",
      "description": "<p>A hotel near the water.</p>",
      "offers": [
        {
          "publicId": "rate_example1234567890abcdefgh",
          "name": "Deluxe King, Breakfast, Free cancellation",
          "description": null,
          "price": { "amount": 642.10, "currency": "USD" },
          "details": {
            "expiresAt": "2027-02-01T10:30:00Z",
            "rooms": [
              {
                "roomIndex": 1, "roomGroupKey": "4c8e3ae1d379f759bc372243", "name": "Deluxe King",
                "description": null, "beds": [], "maxOccupancy": 3, "sizeSquareMeters": null,
                "amenities": [], "imageUrls": [],
                "adultsCount": 2, "childrenCount": 1, "childrenAges": [7]
              }
            ],
            "board": { "code": "BB", "name": "Bed and breakfast", "boardType": "breakfast" },
            "terms": {
              "payment": { "type": "payNow", "dueNow": { "amount": 642.10, "currency": "USD" }, "dueLater": null, "dueLaterAt": null },
              "cancellation": {
                "type": "fullyRefundable",
                "freeUntil": "2027-03-08T20:00:00Z",
                "freeUntilLocalTime": "2027-03-09T00:00:00",
                "timezone": "Asia/Dubai",
                "schedule": [
                  {
                    "from": "2027-03-08T20:00:00Z", "fromLocalTime": "2027-03-09T00:00:00",
                    "refund": { "amount": 0.00, "currency": "USD" }, "penalty": { "amount": 642.10, "currency": "USD" }
                  }
                ],
                "fee": null
              },
              "changes": { "allowed": true, "fee": null }
            },
            "taxes": { "included": true, "totalTaxAmount": 41.20, "items": [] },
            "priceIsBinding": true,
            "nightlyPrices": [],
            "surcharges": [],
            "rateTags": [],
            "remarks": [],
            "withTransfers": false,
            "rateRules": [],
            "amendabilityStatus": "yes",
            "guestNameRules": { "minLength": 2, "maxLength": 50, "pattern": "^[A-Za-z' -]+$", "allowedCharacters": "Letters, spaces, apostrophes and hyphens", "distinctFullNames": false }
          }
        }
      ],
      "details": {
        "starRating": 5,
        "address": { "line1": "1 Example Street", "line2": null, "city": "Dubai", "stateProvince": null, "postalCode": null, "countryCode": "AE", "countryName": null },
        "coordinates": { "latitude": 25.2, "longitude": 55.3 },
        "imageUrls": ["https://cdn.example.com/hotel-1.jpg"],
        "amenityGroups": [ { "key": "PropertyAmenities", "codes": ["FreeWifi", "Pool"] } ],
        "contact": null,
        "displayGroup": null
      }
    }
  ],
  "pagination": { "currentCount": 1, "limit": 20, "hasMore": false },
  "nextCursor": null,
  "details": { "availableFilters": null }
}
```

The offer fields partners use most:

| Field | Meaning |
|---|---|
| `publicId` | The offer id you quote and order with, until `details.expiresAt`. It names the rate, not the hotel. |
| `price` | The price of the whole stay in the search currency, with your pricing rules applied. It is indicative: quote and order price the rate again. |
| `details.rooms` | One room per searched room, with `roomGroupKey`, which is equal for every rate of the same physical room. |
| `details.board` | `code` (`RO`, `BB`, `HB`, `FB`, `AI` or `OTHER`) and `boardType` (`roomOnly`, `breakfast`, `halfBoard`, `fullBoard`, `allInclusive` or `unknown`). |
| `details.terms` | The [booking terms](#booking-terms): payment, cancellation and changes. |
| `details.taxes` | Taxes already included in `price`. |
| `details.surcharges` | Fees outside the room rate. See [Surcharges](#surcharges). |
| `details.minimumSellingPrice` | When present, the lowest price at which you may resell the stay. See below. |
| `details.amendabilityStatus` | `yes`, `no` or `unknown`: whether the booking can be amended. |
| `details.guestNameRules` | What the booking accepts as a first and last name, so your form can validate before ordering. |
| `details.allowsSpecialRequests`, `details.specialRequestOptions` | When stated, whether requests are accepted and the `{ code, name }` options to send as `specialRequestCodes`. |

A rate that OpenRoam does not sell to you is not listed. Rates that are paid at the property or that need a deposit
are not sold at the moment: they are left out of search and refused at quote and order with `409 / 11003`.

**Minimum selling price.** When `details.minimumSellingPrice` is set, you must not sell the stay to the traveller below
that amount. It covers the whole stay and is separate from `price`. A null value means no minimum can be stated, not
that you may ignore a retail restriction. The quote returns the refreshed amount at
`items[].details.rate.minimumSellingPrice`, so check it again before you sell.

## Quote and order [#quote-and-order]

Quote and order take the same body. A quote may leave `inputs` out; an order needs them.

```json
{
  "currency": "USD",
  "referenceId": "partner-booking-42",
  "items": [
    {
      "publicId": "rate_example1234567890abcdefgh",
      "quantity": 1,
      "inputs": {
        "holder": { "title": "Ms", "firstName": "Ana", "lastName": "Garcia", "email": "ana@example.com", "phone": "+34600123456" },
        "roomGuests": [
          {
            "roomIndex": 1,
            "guests": [
              { "title": "Ms", "firstName": "Ana", "lastName": "Garcia", "age": 34 },
              { "title": "Mr", "firstName": "Luis", "lastName": "Garcia", "age": 36 },
              { "title": "Miss", "firstName": "Sofia", "lastName": "Garcia", "age": 7 }
            ]
          }
        ],
        "specialRequests": "Late arrival",
        "maxPrice": { "amount": 650.00, "currency": "USD" }
      }
    }
  ]
}
```

- `items` holds 1 to 5 items. `quantity` must be 1: an item books one rate, which covers every searched room. Book
  another rate as another item.
- `publicId` is an offer's id from search, or the newer one a quote returned. A hotel's own `id` is not an offer.
- The stay dates, rooms and child ages come from the offer, so you do not send them.
- `currency` defaults to your API key's currency. An order must be in the currency the offer was priced in.
- `referenceId` is your own reference, unique per partner, at most 128 characters.

### Inputs [#inputs]

Every hotel offer takes the same inputs, so offers do not list `requiredInputs`.

| Input | Required | Meaning |
|---|---|---|
| `holder` | yes | The lead guest. The booking is made in this name and the hotel contacts this person: `title` (optional), `firstName`, `lastName`, `email` (up to 100 characters) and `phone` (international format with a leading `+`, for example `+14155552671`). |
| `roomGuests` | yes | One entry per searched room: `roomIndex` (1-based, each room once) and `guests`, every adult and child in the room. |
| `specialRequests` | no | Free text, at most 500 characters, for rates without a code list. The hotel may not honour it. |
| `specialRequestCodes` | no | Up to 32 distinct codes from the rate's `specialRequestOptions`, applied to every room. |
| `maxPrice` | no | The price cap. See below. |

A guest has `title` (`Mr`, `Mrs`, `Ms`, `Miss` or `Dr`), `firstName`, `lastName`, optional `middleName`, `age`,
`nationality` and `countryOfResidence`. A guest aged 18 or more, or sent without an age, is an adult; a guest aged 0 to
17 is a child. Each room's guests must match its searched adults and children with the same child ages, in any order.
Names must follow the offer's `details.guestNameRules`. Some rates require `nationality` and `countryOfResidence` to
match the market the rate was priced for.

Hotel stays have no monetary value, so `inputs.value` is not accepted.

### The quote response [#the-quote-response]

```json
{
  "currency": "USD",
  "items": [
    {
      "publicId": "rate_example2234567890abcdefgh",
      "quantity": 1,
      "name": "Hotel Example · Deluxe King, Breakfast, Free cancellation",
      "price": { "amount": 648.90, "currency": "USD" },
      "details": {
        "expiresAt": "2027-02-01T10:42:00Z",
        "availability": "confirmed",
        "checkInDate": "2027-03-10",
        "checkOutDate": "2027-03-13",
        "requestedRooms": [ { "adults": 2, "children": 1, "childrenAges": [7] } ],
        "terms": { "payment": { "...": "..." }, "cancellation": { "...": "..." }, "changes": { "...": "..." } },
        "rate": { "rooms": [], "board": {}, "taxes": {}, "surcharges": [], "rateConditions": [], "...": "..." }
      }
    }
  ],
  "total": { "amount": 648.90, "currency": "USD" }
}
```

- `publicId` is a new offer id for the rate at the quoted `price`. It is accepted until `details.expiresAt`, at most 30
  minutes after the quote. The id you quoted keeps the price it was returned with.
- `details.availability` is `confirmed` when the rate can be booked now, or `onRequest` when it can only be held on
  request. An order refuses an `onRequest` rate with `409 / 11003`.
- `details.terms` are the terms you are buying, stated at the time of the quote on the quoted `price`.
- `details.rate` holds the rate in detail. Its `surcharges` list is the binding one.
- If the rate is no longer sold, the quote answers `409 / 11003`.

### Price cap at order [#price-cap-at-order]

Before any money moves, the order prices each rate again and caps the fresh price:

| Item | Quote | Order |
|---|---|---|
| With `inputs.maxPrice` | A fresh price above `maxPrice` gives `409 / 11002` and no `publicId`. | The same. At or below `maxPrice`, the rate is charged at its fresh price. |
| Without `inputs.maxPrice` | `200` with the fresh price and a new `publicId`. | A fresh price above the one returned with the `publicId` gives `409 / 11002` at `items[i]`. |

`maxPrice` is `{ amount, currency }` in the order currency. A `maxPrice` above the price you were shown accepts a rise
up to it, and one below it refuses even that price. After a refusal, quote again and order the new `publicId`, or order
again with a `maxPrice` you accept. A refused order creates and charges nothing.

### Held rate [#held-rate]

Where a rate can be held, the order holds it before charging. If you order a `publicId` that a quote returned and the
cancellation terms on the hold are stricter than the quote's (a larger share kept, or kept from an earlier instant),
the order fails with `409 / 11006` and the reason `TERMS_CHANGED` at `items[i]` before any money moves. Quote the rate
again, check its terms, and order the new `publicId`. Terms that only moved on with the clock, such as a `freeUntil` that
has passed, are not a change.

### Place the order [#place-the-order]

```bash
curl -X POST https://api.sandbox.openroam.com/v1/hotels/order \
  -H "X-Partner-Key: $OPENROAM_API_KEY" \
  -H "Idempotency-Key: 8c3f6a1e-2b7d-4e55-9b0a-1d2c3e4f5a60" \
  -H "Content-Type: application/json" \
  -d @order.json
```

The booking completes after payment. Follow it with [`GET /v1/orders/{id}`](/docs/api-reference/orders/get-by-id) or
the [`order.fulfillment.updated`](/docs/api-reference/webhooks/order-fulfillment-updated) webhook.

## Booking terms [#booking-terms]

Every offer, quote item and purchased booking states its terms in `details.terms`, with the same shape for hotels and
flights: `{ payment, cancellation, changes }`. Money is `{ amount, currency }` in the response currency, with
OpenRoam's fees already included.

- **Payment.** `payment.type` is `payNow` for every hotel rate sold today: `dueNow` is the price, and `dueLater` and
  `dueLaterAt` are null.
- **Cancellation.** `cancellation.type` is `fullyRefundable` (a full refund until `freeUntil`), `partiallyRefundable`
  (a share is always kept, for example because a fee applies) or `nonRefundable`. `schedule` lists steps, each
  `{ from, fromLocalTime, refund, penalty }`: cancelling at or after `from`, and before the next step, gives back
  `refund` and keeps `penalty`. `fee` is OpenRoam's cancellation fee, or null; it is already included in every penalty
  and turns a free window into a `partiallyRefundable` one.
- **Changes.** `changes.allowed` says whether the booking can be amended, and `changes.fee` is OpenRoam's fee per
  change, or null.
- The offer's `name` follows the cancellation type: `Free cancellation` only for `fullyRefundable`, `Non-refundable`
  for `nonRefundable`, and no terms part for `partiallyRefundable`.
- The terms on a booked item never change afterwards, not even when the free window closes. Ask the cancellation
  preview what cancelling costs now.

### Times and time zones [#times-and-time-zones]

Every instant (`freeUntil`, each step's `from`, `expiresAt`) is a UTC instant ending in `Z`. A hotel states its
deadlines on its own clock, and OpenRoam converts them with the hotel's time zone. For display, `cancellation.timezone`
is the hotel's IANA time zone (for example `Europe/Madrid`), and `freeUntilLocalTime` and each step's `fromLocalTime`
are the same instants on the hotel's clock, written `yyyy-MM-ddTHH:mm:ss` with no zone. Those clocks are for display
only: compute and compare with the UTC instants. When the time zone is not known, `timezone` and every clock are null,
and the UTC deadlines are chosen so a free window never ends later than the hotel's own deadline. A charge that applies
whatever the date has `from` set to `0001-01-01T00:00:00Z` and a null clock.

### Surcharges [#surcharges]

`details.surcharges` lists fees outside the room rate, such as a city tax, a resort fee or a deposit. Each entry is
`{ type, description, price, approxPrice, includedInTotal, payableAt }`.

- Never add a surcharge to the offer's `price`. With `includedInTotal: false` the fee is not money OpenRoam charges, and
  with `true` it is already in the price. Most are paid by the guest at the hotel (`payableAt: property`).
- `price` is in the property's currency and is never converted. `approxPrice` is an estimate in your currency, and is
  null when it could not be converted: show `price` then, and label `approxPrice` as approximate.
- Show one line per entry. Two rooms with the same deposit mean the guest owes it twice.
- An empty list does not mean the hotel charges nothing: a location search leaves it empty, and the quote returns the
  binding list. Nothing says whether a fee is refundable, so do not promise money back.

## What the order item contains [#what-the-order-item-contains]

Read it with [`GET /v1/order-items/{id}`](/docs/api-reference/order-items/get-by-id) or in `items` of
`GET /v1/orders/{id}`.

```json
{
  "id": "019a2b5c-4d7e-7f10-8a2b-3c4d5e6f7081",
  "orderId": "019a2b5c-4d6a-7c33-9e15-7f2a8b4c6d10",
  "productType": "hotel",
  "price": { "amount": 642.10, "currency": "USD" },
  "purchasedProduct": {
    "name": "Hotel Example · Deluxe King, Breakfast, Free cancellation",
    "countryCode": "AE",
    "logoUrl": "https://cdn.example.com/hotel.jpg",
    "inputs": {
      "holder": { "title": "Ms", "firstName": "Ana", "lastName": "Garcia", "email": "a***@example.com", "phone": "+34***3456" },
      "roomGuests": [ { "roomIndex": 1, "guests": [ { "title": "Ms", "firstName": "Ana", "lastName": "Garcia", "middleName": null, "age": 34, "nationality": null, "countryOfResidence": null } ] } ],
      "specialRequests": "Late arrival"
    },
    "details": {
      "checkInDate": "2027-03-10",
      "checkOutDate": "2027-03-13",
      "requestedRooms": [ { "adults": 2, "children": 1, "childrenAges": [7] } ],
      "hotel": { "name": "Hotel Example", "starRating": 5, "address": { "...": "..." }, "coordinates": { "...": "..." }, "description": "<p>...</p>", "imageUrls": [], "amenityGroups": [], "contact": null },
      "terms": { "payment": { "...": "..." }, "cancellation": { "...": "..." }, "changes": { "...": "..." } },
      "rate": { "rooms": [], "board": {}, "taxes": {}, "nightlyPrices": [], "surcharges": [], "amendabilityStatus": "yes", "...": "..." }
    }
  },
  "fulfillment": {
    "status": "fulfilled",
    "result": {
      "details": {
        "bookingStatus": "confirmed",
        "hotelConfirmationNumber": "1234-ABC",
        "amendmentComposition": {
          "guests": { "addMore": false, "remove": false, "guestType": false, "names": true, "ages": true },
          "rooms": { "addMore": false, "remove": false },
          "dates": { "change": true },
          "holder": { "change": true }
        },
        "booking": {
          "checkInDate": "2027-03-10",
          "checkOutDate": "2027-03-13",
          "holder": { "title": "Ms", "firstName": "Ana", "lastName": "Garcia", "email": "a***@example.com", "phone": "+34***3456" },
          "roomGuests": [ { "roomIndex": 1, "guests": [ "..." ] } ]
        }
      }
    },
    "failure": null
  },
  "actions": {
    "amendment": { "availability": "available", "reason": null },
    "cancellation": { "availability": "available", "reason": null },
    "update": { "availability": "notAvailable", "reason": null }
  },
  "createdAt": "2027-02-01T10:31:07.214Z",
  "effectivePaidAmount": { "amount": 642.10, "currency": "USD" }
}
```

`purchasedProduct` is the stay as bought and never changes after purchase.

- `inputs` echoes the holder, `roomGuests` and `specialRequests`. Names, titles, ages, nationalities and countries of
  residence are returned as sent, so you can service the booking. The holder's `email` and `phone` are masked (for
  example `a***@example.com` and `+34***3456`): show them as returned and do not use them as contact details. The
  `maxPrice` cap is not echoed.
- `details` holds the stay dates, `requestedRooms`, the `hotel` content as stored with the purchase, the `terms` you
  bought and the `rate` (rooms, board, taxes, nightly prices, surcharges and so on). `rate.surcharges[].approxPrice`
  is derived again on every read in the order currency, so it moves with exchange rates.

`fulfillment.result.details` is the booking's facts:

| Field | Meaning |
|---|---|
| `bookingStatus` | `confirmed`, `pending`, `onRequest`, `cancelled` or `failed`. |
| `hotelConfirmationNumber` | The hotel's own confirmation number, the one the guest gives at the front desk. Null until the hotel issues one, and it can arrive after the item is `fulfilled`. |
| `amendmentComposition` | What an amendment may change about the booking: guests, rooms, dates and holder. It is decided per booking. When OpenRoam cannot tell, every value is `false`. |
| `booking` | The stay as booked now, always filled: `checkInDate`, `checkOutDate`, `holder` and `roomGuests`. It reads as the stay bought until an amendment changes it. Show the stay from `booking`. |

A hotel confirmation number that arrives after fulfillment creates a new `fulfillmentVersion`, and an
`order.fulfillment.updated` webhook carries the number, once per new number. An amendment changes what a read returns
without sending that webhook, so read the order again after an amendment.

## After purchase [#after-purchase]

These calls are shared by every product; see [Orders](/docs/orders).

### Cancel [#cancel]

1. [`GET /v1/order-items/{id}/cancellation-preview`](/docs/api-reference/order-items/get-cancellation-preview) shows what
   cancelling now costs. It changes nothing and returns `penaltyAmount`, `cancellationFee`, `refundAmount`,
   `isRefundable`, `appliedPenalties`, `effectiveCancellationDate` and `checkInDate`. Amounts are measured on what was
   paid for the item (amendments included), in the order currency. `isRefundable: false` means the penalty alone keeps
   everything that was paid.
2. [`POST /v1/order-items/{id}/cancel`](/docs/api-reference/order-items/cancel) cancels the booking and refunds what the
   penalty and any cancellation fee leave. The body is `{ "reason": "requestedByCustomer" }` (or `duplicate` or
   `fraudulent`), and it needs the `manage` permission and an `Idempotency-Key`. The money goes back to the wallet that
   paid, and the [`order-item.refunded`](/docs/api-reference/webhooks/order-item-refunded) webhook reports it.

A booking whose penalty keeps everything that was paid is not cancelled: cancel answers `400 / 10001`, and
`actions.cancellation.availability` is `notAvailable`. The preview and the refund price the cancellation again with the
band in effect at that moment, so the amount can differ from an earlier preview.

To preview a whole trip, such as a hotel and a flight in one order, use
[`GET /v1/orders/{id}/cancellation-preview`](/docs/api-reference/orders/get-cancellation-preview). Each item reads
`previewable` with its preview, or `notCancellable` with a reason, and `totals.isComplete` is `true` only when every
item can be previewed.

### Amend by API [#amend-by-api]

Where a booking can be amended by API (`actions.amendment.availability` is `available`):

1. [`POST /v1/order-items/{id}/amendments/quote`](/docs/api-reference/order-items/quote-amendment) takes
   `{ "attributes": { ... } }` with the changes you want and returns `amendmentRequestId`, `expiresAt` and `options`,
   each `{ id, amountToPay, amountToRefund, amendmentFee }`. Nothing is charged yet.
2. [`POST /v1/order-items/{id}/amendments/confirm`](/docs/api-reference/order-items/confirm-amendment) takes
   `{ "amendmentRequestId": "...", "paymentMethod": "balance", "selectedOptionId": "...", "maxPrice": { ... } }`.
   `maxPrice` is optional and caps what you accept to pay for this amendment.

An amendment is priced on the terms the booking was bought on. By default it adds to the price, or refunds part of it,
in the same proportion as it changes the stay. Your account's booking terms can add a change fee, which is already
included in `amountToPay` and `amountToRefund`. A change never refunds more than your share of what you paid for the
part it removes. Only one amendment runs at a time: a confirm answers `409` while another is in progress. List
amendments with [`GET /v1/order-items/{id}/amendments`](/docs/api-reference/order-items/get-amendments), or across
items with [`GET /v1/amendments`](/docs/api-reference/order-items/list-partner-amendments).

`amendmentComposition` on the booking says what can change: guests, rooms, dates and holder. Some bookings of two
or more rooms can lose a room: send `attributes.roomGuests` listing the rooms to keep, as booked. The last room cannot be
removed; cancel the booking instead. A change the booking does not allow returns `400 / 21114` (rooms and guests) or
`400 / 21115` (dates and holder).

### Manual amendments [#manual-amendments]

When a booking cannot be changed by API, `actions.amendment.availability` reads `manualReview` and the quote answers
`409 / 18003` with the reason `MANUAL_REVIEW`. Changes then go through a manual amendment, which OpenRoam quotes.

| Step | Route |
|---|---|
| Request one | [`POST /v1/order-items/{id}/manual-amendments`](/docs/api-reference/hotel-manual-amendments/create-manual-amendment) with `{ "attributes": { ... } }`. Returns `{ amendmentId }`. Needs an `Idempotency-Key`. |
| Approve the quote | [`POST /v1/order-items/{id}/manual-amendments/{amendmentId}/approve`](/docs/api-reference/hotel-manual-amendments/approve-manual-amendment). Charges your wallet. Needs an `Idempotency-Key`. The body can carry an optional `walletId` to settle from another of your wallets. |
| Decline the quote | [`POST /v1/order-items/{id}/manual-amendments/{amendmentId}/decline`](/docs/api-reference/hotel-manual-amendments/decline-manual-amendment). Nothing is charged. |
| Cancel an unquoted request | [`POST /v1/order-items/{id}/manual-amendments/{amendmentId}/cancel`](/docs/api-reference/hotel-manual-amendments/cancel-manual-amendment). Any other status returns `400 / 21103`. |

Read an amendment and its quoted amounts with `GET /v1/order-items/{id}/amendments` and
`GET /v1/order-items/{id}/amendments/{amendmentId}`. The `attributes` object can hold `checkInDate` and
`checkOutDate`, a `holder`, and `roomGuests` with a 1-based `roomIndex` and its `guests`. Anything you leave out keeps
its booked value. The holder's `email` and `phone` are masked on reads: send one back as returned, or empty, to keep
the booked one. Any other masked value is refused with `400 / 10001`.

Progress is sent by the [`order-item.manual-amendment.status`](/docs/api-reference/webhooks/order-item-manual-amendment-status)
webhook. Its `data` carries `orderId`, `orderItemId`, `amendmentId`, `status`, `actionRequired`, `amountToPay`,
`amountToRefund` and `currencyCode`. `status` is `quoted` (with `actionRequired: true`, so you can approve or decline),
`completed`, `failed` or `cancelled`. Read the order again after each event.

Manual amendments, like any amendment, need hotels to be enabled for your account. Approving a quote with a wallet
balance that is too low returns `400 / 21107`: fund the wallet and approve again.

## Hotel catalog files [#hotel-catalog-files]

[`GET /v1/hotels/catalog/files`](/docs/api-reference/hotels/get-catalog-files) returns `generatedAt`, `hotelCount` and
links to downloadable zips: `withoutImages` (the main image only) and `withImages` (every gallery image). It also
returns a `replacements` file that maps replaced hotel ids to current ones. Each zip holds `hotels.jsonl`, one hotel per
line, in the shape `GET /v1/hotels/properties/{id}` returns, without offers and prices. Price a catalog hotel with a
`hotelIds` search. The files are rebuilt about twice a month and are empty until the first build. Download from the link
directly, and keep your last import until new files are listed. Use the same `generatedAt` for the hotel file and the
replacement map, and replace your previous map instead of appending to it.

## Testing in Sandbox [#testing-in-sandbox]

Sandbox supports hotels. It uses the same routes, validation, pricing and webhooks as production with a synthetic
catalog and test wallet funds; see [Environments](/docs/environments). Search issues fresh, stay-specific offers each
time, and availability does not run out.

- **Destinations.** There are 103 synthetic hotels in 16 destinations. Search by `cityCode` or coordinates:
  `GYD` (Baku), `DXB` (Dubai), `AUH` (Abu Dhabi), `TYO` (Tokyo), `PAR` (Paris), `KUL` (Kuala Lumpur), `BKK` (Bangkok),
  `HKT` (Phuket), `CNX` (Chiang Mai), `KBV` (Krabi), `LON` (London), `IST` (Istanbul), `SIN` (Singapore),
  `NYC` (New York), `ROM` (Rome) and `DPS` (Bali). The destination lookup and the catalog files are not populated in
  Sandbox.
- **Stays.** Normal validation applies: 1 to 9 rooms and 1 to 30 nights. Every hotel has a standard room-only rate paid
  now, and a standard cancellation: free until check-in at 00:00 UTC, the full price from then.
- **Amendments.** Amendments are not available in Sandbox. Cancel and book a new stay.

Baku walkthrough: search `GYD` with `guestNationality` `AZ`, `currency` `USD`, future dates and `rooms` of
`[{"adults":2}]`. Find Sandbox Baku City Hotel and copy its `id`, then search again with
`searchCriteria.hotelIds` and the same stay to see all its rates. Choose by `details.board.boardType`:

| `boardType` | Room | Cancellation |
|---|---|---|
| `roomOnly` | Standard room | Standard cancellation |
| `breakfast` | Standard room | Standard cancellation |
| `unknown` (Brunch package) | Deluxe room | Standard cancellation |
| `halfBoard` | Deluxe room | Free until 00:00 UTC two days before check-in, 25% kept from then, 100% at check-in midnight |
| `fullBoard` | Deluxe room | Non-refundable from purchase |
| `allInclusive` | Suite | Free until 00:00 UTC one day before check-in, 100% kept from then |

Ways to exercise the edge cases:

- Book the half-board rate with check-in two UTC days away to enter the 25% band right away, then check
  `GET /v1/order-items/{id}/cancellation-preview`.
- Send an `inputs.maxPrice` one minor unit below the quoted price to get `409 / 11002`.
- Reuse an offer after its `details.expiresAt` to see an expired offer, then search again for a fresh one.
- Sandbox Baku Guesthouse has a half-board Family room whose quote returns `availability: "onRequest"`; ordering it
  returns `409 / 11003` before any charge.

On `POST /v1/hotels/order` (and the shared `POST /v1/orders`), the `OpenRoam-Sandbox-Scenario` header selects the
outcome:

| Header value | Result |
|---|---|
| `success` (or no header) | A confirmed reservation and a readable result. |
| `fulfillment.rejected` | A terminal failed reservation after payment, with no fulfilled result. The item is refunded automatically. |
| `fulfillment.pending` | Returns pending at once. The item becomes eligible for success after 15 minutes. |
| `fulfillment.late_success` | Returns pending at once and becomes eligible for success after 2 minutes. |
| `fulfillment.late_rejected` | Returns pending at once and confirms the rejection after 2 minutes. |

The scenario is saved with the order and is part of idempotency: the same key, body and scenario replay the same order,
and changing the scenario with that key returns `409`. Search, quote and cancel requests do not accept the header; it
returns `400 / 10001` with `NOT_ALLOWED`. Pending results carry no hotel confirmation. A hotel item can end `fulfilled`
before a progress message appears, and completion is seen on the next reconciliation pass, so the durations are not a
guaranteed delay. Even with `success`, a booking takes from about 20 to 60 seconds to confirm, so read the order again
or wait for the webhook.

A rejected booking is refunded automatically, and cancelling with the reason `fulfillmentFailed` returns that refund.
Use the same cancel route to cancel a refundable confirmed booking.

## Errors to handle [#errors-to-handle]

Shared error handling is in [Errors](/docs/errors). Branch on `code`, not on the message, and keep `requestId` for
support.

| Status / code | Name or reason | When and what to do |
|---|---|---|
| `400 / 10001` | `INVALID_VALUE` | An invalid body field, including guests that do not fit the searched rooms, names the booking refuses, or an unknown member. The `details[].path` names it, for example `inputs.roomGuests` or `inputs.holder.email`. |
| `400 / 10001` | `MAX_STAY_EXCEEDED` | The stay is longer than 30 nights, at `checkOut`. |
| `400 / 10001` | `REQUIRED` | An order item without `inputs`, at `items[i].inputs`. |
| `400 / 10001` | `NOT_SUPPORTED` | A currency OpenRoam does not support, at `currency`. |
| `400 / 11004` | `EXPIRED_OR_INVALID` | An unknown, expired or foreign offer id, a hotel's own `id`, or another product's offer. Search again for a fresh offer. |
| `409 / 11003` | `UNAVAILABLE` | The rate is no longer sold, or it can only be held on request. Pick another offer. |
| `409 / 11002` | `PRICE_CHANGED` | The fresh price is above your cap or above the price returned with the `publicId`. Nothing is charged. Quote again. |
| `409 / 11006` | `TERMS_CHANGED` | The cancellation terms got stricter than the quote's. Quote again and check the terms. |
| `400 / 11005` | `CURRENCY_MISMATCH` | The offer was priced in another currency than the order. Search or quote in the order currency. |
| `403 / 10003` | `SERVICE_NOT_ENABLED` | Hotels are not enabled for your account. |
| `404 / 10004` | none | `GET /v1/hotels/properties/{id}` with an id of no catalog hotel. |
| `400 / 21000` | `HOTEL_ID_INVALID` | A `hotelIds` entry that is not a hotel id. |
| `400 / 21010` | `HOTEL_OCCUPANCY_MISMATCH` | The rate's room layout no longer matches the searched rooms. Search again. |
| `503 / 21003` | `HOTEL_RATE_CONTEXT_UNAVAILABLE` | Hotel offers are temporarily unavailable. Retry a search or quote later. After an order, check the existing order before retrying. |
| `502 / 21007`, `504 / 21008`, `503 / 21009` | `HOTEL_REQUEST_FAILED`, `HOTEL_RESPONSE_TIMEOUT`, `HOTEL_TEMPORARILY_UNAVAILABLE` | The hotel request failed, timed out or is unavailable. Retry read-only calls later. For writes, check the order state before retrying. |
| `503 / 10007` | none | The destination lookup is unavailable. Retry. |
| `400 / 21004` | `HOTEL_BOOKING_UNAVAILABLE` | The item has no valid booking to cancel or amend. Reload the order. |
| `400 / 21005` | `HOTEL_AMENDMENT_UNSUPPORTED` | This booking does not support the amendment mode you tried. |
| `400 / 21102` | `HOTEL_AMENDMENT_TICKET_ALREADY_OPEN` | A manual amendment is already open for this booking. Use the existing one. |
| `400 / 21103` | `HOTEL_AMENDMENT_INVALID_STATE` | The action is not allowed in the amendment's current state. Reload it first. |
| `400 / 21107` | `HOTEL_AMENDMENT_INSUFFICIENT_BALANCE` | The wallet cannot cover the amendment. Fund it, then approve again. |
| `409 / 21111` | `HOTEL_AMENDMENT_ORDER_BUSY` | The booking is being processed. Try again shortly. |
| `409 / 21112` | `HOTEL_AMENDMENT_CONCURRENT_CHANGE` | Another request updated the amendment. Reload and retry. |
| `400 / 21113` | `HOTEL_AMENDMENT_INVALID_GUEST_COMPOSITION` | The requested rooms, guests, names or ages are invalid. |
| `400 / 21114`, `400 / 21115` | `HOTEL_AMENDMENT_GUEST_COMPOSITION_CHANGE_UNSUPPORTED`, `HOTEL_AMENDMENT_CHANGE_UNSUPPORTED` | The room or guest change (21114), or the date or holder change (21115), is not supported for this booking. Check `amendmentComposition`. |
| `400 / 21108`, `409 / 21109` | `HOTEL_AMENDMENT_SETTLEMENT_FAILED`, `HOTEL_AMENDMENT_SETTLEMENT_CONFLICT` | The settlement could not be completed. Do not retry automatically: reload the amendment and contact support. |
| `409 / 18003` | `MANUAL_REVIEW`, `IN_PROGRESS` or `NOT_AVAILABLE` | An amendment cannot be quoted or confirmed now. `MANUAL_REVIEW` points to manual amendments. |
| `422 / 18004` | none | `update` is not supported for hotel bookings. Use amendments. |

Browse routes reject any unknown query parameter with `400 / 10001` and the reason `UNSUPPORTED_FIELD`. A failing quote
or order creates and charges nothing.