Skip to Content
OpenRoam Docs
Hotels

Quote hotel rates

Prices up to 5 searched or quoted rates again with the hotel system and issues a new offer for each.

POST
/v1/hotels/quote

Prices up to 5 searched or quoted rates again with the hotel system and issues a new offer for each.

Takes the same body as order, { currency, referenceId, items }, and checks it the same way: the whole body first, so a body error gives 400 / 10001 also when it is in a later item, then each item completely (its inputs, its publicId, then a fresh price from the hotel system) before the next, in request order. inputs may be left out; when sent, they are checked as the order checks them. The body and every object in it reject an unknown member (400 / 10001). Stay dates and rooms come from the offer and are returned in each item's details. Nothing is charged or reserved.

Each item returns a new publicId for its rate at the current price (the whole stay, all rooms and nights): order with it before details.expiresAt, which is at most 30 minutes away and never past an expiry the hotel system states. A price that rose since the search is returned with 200; only inputs.maxPrice stops a quote, with 409 / 11002 at items[i].inputs.maxPrice. details.availability is onRequest for a rate that is held only on request, which an order refuses with 409 / 11003.

Errors name the failing item: a rate that is no longer sold is 409 / 11003, and an unknown, expired or another partner's publicId, another product's offer, a hotel's own id or an expired search session (search again) is 400 / 11004, each at items[i]; input errors (400 / 10001) are at items[i].inputs…. Offer and hotel-system failures return their hotel codes without a path: 503 / 21003 when offers are temporarily unavailable, 21007–21009, and 400 / 21010 when the hotel's room layout no longer matches the searched occupancy (search again).

Authorization

PartnerApiKey
headerX-Partner-Key<token>

Partner API Key (X-Partner-Key)

Request Body

  1. body

The body of a B2B hotel quote and order: the currency, an optional reference and the rates to price or book.

currency?|

Quote and order currency, three letters in either case; the API key's currency when omitted. An order must be in the currency the offers were priced in; a quote prices them in it. An unsupported code gives 400 / 10001 at currency, reason NOT_SUPPORTED, before any item is checked.

referenceId?|

Your own order reference, up to 128 characters without leading or trailing spaces, unique per partner. Reusing it for a different order returns 409. A quote checks it and ignores it.

items*array<>

1 to 5 items; each prices or books one rate.

Response Body

OK

  1. response

Current prices for the requested items, in request order. Each item carries a new publicId for its rate at that price: order with it before the item's details.expiresAt.

currency*string

The quote currency: the body currency, or the API key's currency when it is omitted.

items*array<>

One quoted item per request item, in request order.

total*

The sum of each item's price times its quantity, in the quote currency.

Example Request
curl -X POST 'https://api.sandbox.openroam.com/v1/hotels/quote' \  -H 'Content-Type: application/json' \  -d '{  "currency": "USD",  "items": [    {      "publicId": "rate_x5z2b4d6f3h5jn2pq7m2k4t6v3"    }  ]}'
Example Response
{  "currency": "USD",  "items": [    {      "publicId": "rate_b4d6f3h5jn2pq7m2k4t6v3x5z2",      "quantity": 1,      "name": "Hotel Arts Barcelona · Deluxe King, Breakfast, Free cancellation",      "price": {        "amount": 648.9,        "currency": "USD"      },      "details": {        "expiresAt": "2026-12-01T10:42:00Z",        "availability": "confirmed",        "checkInDate": "2026-12-10",        "checkOutDate": "2026-12-13",        "requestedRooms": [          {            "adults": 2,            "children": 1,            "childrenAges": [              7            ]          }        ],        "terms": {          "payment": {            "type": "payNow",            "dueNow": {              "amount": 648.9,              "currency": "USD"            },            "dueLater": null,            "dueLaterAt": null          },          "cancellation": {            "type": "fullyRefundable",            "freeUntil": "2026-12-08T23:59:00Z",            "freeUntilLocalTime": "2026-12-09T00:59:00",            "timezone": "Europe/Madrid",            "schedule": [              {                "from": "2026-12-08T23:59:00Z",                "fromLocalTime": "2026-12-09T00:59:00",                "refund": {                  "amount": 432.6,                  "currency": "USD"                },                "penalty": {                  "amount": 216.3,                  "currency": "USD"                }              }            ],            "fee": null          },          "changes": {            "allowed": true,            "fee": null          }        },        "rate": {          "rooms": [            {              "roomGroupKey": "4c8e3ae1d379f759bc372243",              "name": "Deluxe King",              "description": null,              "beds": [],              "maxOccupancy": 3,              "sizeSquareMeters": null,              "amenities": [],              "imageUrls": [],              "roomIndex": 1,              "adultsCount": 2,              "childrenCount": 1,              "childrenAges": [                7              ]            }          ],          "board": {            "code": "BB",            "name": "Bed and breakfast",            "boardType": "breakfast"          },          "taxes": {            "included": true,            "totalTaxAmount": 41.64,            "items": []          },          "priceIsBinding": true,          "nightlyPrices": [            {              "date": "2026-12-10",              "amount": 216.3,              "currency": "USD"            },            {              "date": "2026-12-11",              "amount": 216.3,              "currency": "USD"            },            {              "date": "2026-12-12",              "amount": 216.3,              "currency": "USD"            }          ],          "rateTags": [],          "remarks": [],          "rateConditions": [],          "withTransfers": false,          "rateRules": [],          "amendabilityStatus": "yes",          "surcharges": [            {              "type": "AtProperty",              "description": "City Tax",              "price": {                "amount": 12.45,                "currency": "EUR"              },              "approxPrice": {                "amount": 13.5,                "currency": "USD"              },              "includedInTotal": false,              "payableAt": "property"            }          ]        }      }    }  ],  "total": {    "amount": 648.9,    "currency": "USD"  }}

Get a hotel GET

Returns one hotel's content: the item that search returns, without `offers`. Use it to show a hotel's information: name, description, star rating, address, images, amenities and contact. A hotel has no price without a stay, so the response has no `offers` key; send the `id` in a search's `searchCriteria.hotelIds` for its rates. The route serves the hotels of the OpenRoam catalog, as the catalog files list them. An ID that is unknown, not a hotel ID, or not in the catalog (such as a temporary ID a search gave a hotel outside the catalog) gives 404 / 10004. The route takes no query parameters.

Search hotels POST

Searches hotels by location or hotel IDs and returns their bookable rates for the stay. Send `searchCriteria.location` or `searchCriteria.hotelIds`; a non-empty `hotelIds` wins and `location` is then ignored. `checkIn`, `checkOut`, `rooms` and `guestNationality` are required: rates are priced for the occupancy, child ages and guest market sent here. A stay longer than 30 nights returns 400 / 10001 with reason `MAX_STAY_EXCEEDED` at `checkOut`. The body rejects an unknown member at every level, `filters`, `searchCriteria.location` and `rooms[]` included, and the route takes no query parameters: either gives 400 / 10001. Returns `{ items, pagination, nextCursor, details }`. Each item is a hotel: `id`, `name`, `countryCode`, `category` (always null), `logoUrl` (the main image), `description`, its `offers`, and `details` with the star rating, address, coordinates, images, amenity groups and contact. Each offer is one rate: an opaque `publicId`, a `name` such as "Deluxe King, Breakfast, Free cancellation", a `price` for the whole stay (all rooms and nights), and the rate terms in `details`, including `expiresAt`. Pass an offer's `publicId` to quote or order before it expires. The hotel's `id` is not an offer; send it in `searchCriteria.hotelIds` to search that hotel again. A hotel without an orderable offer is not listed. `details.availableFilters` holds the amenity filter values of a `cityCode` search. Location searches are paged: `limit` is 1–50 (default 20) and the next page is requested by sending the response's `nextCursor` back as `cursor` with the same body; a null `nextCursor` is the last page. A page can hold fewer hotels than `limit`, even none, while `nextCursor` is not null: keep paging until it is null. `pagination` is `{ currentCount, limit, hasMore }`: the walk states no page number and no total. To keep pages small, each hotel on a page has one offer, its cheapest rate, with empty `nightlyPrices` and `surcharges`, and no description and one image. A `hotelIds` search returns every rate of those hotels with the full detail, as one complete page; an empty `items` there means none of those hotels has an orderable offer. Errors: an ID that is not a hotel ID returns 400 / 21000; an unknown or expired hotel ID 400 / 11004; 503 / 21003 when offers are temporarily unavailable (retry the search); 502, 504 or 503 with 21007–21009 when the hotel system fails, times out or is unavailable.