Hotels
Search hotel stays, quote a rate, book it for named guests, and manage cancellations and amendments.
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, Authentication, Environments, Idempotency, Errors, Webhooks and Orders.
The flow
| Step | Route |
|---|---|
| Find a place by name (optional) | GET /v1/hotels/destinations |
| Search hotels and their offers | POST /v1/hotels/search |
| Read one hotel's content (optional) | GET /v1/hotels/properties/{id} |
| Quote a rate | POST /v1/hotels/quote |
| Book it | POST /v1/hotels/order |
Reference data routes:
GET /v1/hotels/amenities/cataloglists every amenity code and group with a label, to labeldetails.amenityGroupsand to fill theamenityCodesfilter. Labels follow theAccept-Languageheader.GET /v1/hotels/catalog/fileslinks 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 untildetails.expiresAt, at most 30 minutes after the search. - Quote returns a new
publicId. It prices the rate again and returns a freshpublicIdat the quoted price. A quote reserves nothing and charges nothing. - A price cap protects the order. See 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
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= 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:
boardTypestakesroomOnly,breakfast,halfBoard,fullBoardorallInclusive.cancellationTypestakesfullyRefundable,partiallyRefundableornonRefundable, matched against the offer'sdetails.terms.cancellation.type. It is judged on the terms stated now: a free window that has already closed does not count.amenityCodestakes codes from the amenity catalog. A hotel must have all of them.
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
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
{
"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: payment, cancellation and changes. |
details.taxes | Taxes already included in price. |
details.surcharges | Fees outside the room rate. See 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 take the same body. A quote may leave inputs out; an order needs them.
{
"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" }
}
}
]
}itemsholds 1 to 5 items.quantitymust be 1: an item books one rate, which covers every searched room. Book another rate as another item.publicIdis an offer's id from search, or the newer one a quote returned. A hotel's ownidis not an offer.- The stay dates, rooms and child ages come from the offer, so you do not send them.
currencydefaults to your API key's currency. An order must be in the currency the offer was priced in.referenceIdis your own reference, unique per partner, at most 128 characters.
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
{
"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" }
}publicIdis a new offer id for the rate at the quotedprice. It is accepted untildetails.expiresAt, at most 30 minutes after the quote. The id you quoted keeps the price it was returned with.details.availabilityisconfirmedwhen the rate can be booked now, oronRequestwhen it can only be held on request. An order refuses anonRequestrate with409 / 11003.details.termsare the terms you are buying, stated at the time of the quote on the quotedprice.details.rateholds the rate in detail. Itssurchargeslist is the binding one.- If the rate is no longer sold, the quote answers
409 / 11003.
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
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
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.jsonThe booking completes after payment. Follow it with GET /v1/orders/{id} or
the order.fulfillment.updated webhook.
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.typeispayNowfor every hotel rate sold today:dueNowis the price, anddueLateranddueLaterAtare null. - Cancellation.
cancellation.typeisfullyRefundable(a full refund untilfreeUntil),partiallyRefundable(a share is always kept, for example because a fee applies) ornonRefundable.schedulelists steps, each{ from, fromLocalTime, refund, penalty }: cancelling at or afterfrom, and before the next step, gives backrefundand keepspenalty.feeis OpenRoam's cancellation fee, or null; it is already included in every penalty and turns a free window into apartiallyRefundableone. - Changes.
changes.allowedsays whether the booking can be amended, andchanges.feeis OpenRoam's fee per change, or null. - The offer's
namefollows the cancellation type:Free cancellationonly forfullyRefundable,Non-refundablefornonRefundable, and no terms part forpartiallyRefundable. - 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
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
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. WithincludedInTotal: falsethe fee is not money OpenRoam charges, and withtrueit is already in the price. Most are paid by the guest at the hotel (payableAt: property). priceis in the property's currency and is never converted.approxPriceis an estimate in your currency, and is null when it could not be converted: showpricethen, and labelapproxPriceas 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
Read it with GET /v1/order-items/{id} or in items of
GET /v1/orders/{id}.
{
"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.
inputsechoes the holder,roomGuestsandspecialRequests. Names, titles, ages, nationalities and countries of residence are returned as sent, so you can service the booking. The holder'semailandphoneare masked (for examplea***@example.comand+34***3456): show them as returned and do not use them as contact details. ThemaxPricecap is not echoed.detailsholds the stay dates,requestedRooms, thehotelcontent as stored with the purchase, thetermsyou bought and therate(rooms, board, taxes, nightly prices, surcharges and so on).rate.surcharges[].approxPriceis 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
These calls are shared by every product; see Orders.
Cancel
GET /v1/order-items/{id}/cancellation-previewshows what cancelling now costs. It changes nothing and returnspenaltyAmount,cancellationFee,refundAmount,isRefundable,appliedPenalties,effectiveCancellationDateandcheckInDate. Amounts are measured on what was paid for the item (amendments included), in the order currency.isRefundable: falsemeans the penalty alone keeps everything that was paid.POST /v1/order-items/{id}/cancelcancels the booking and refunds what the penalty and any cancellation fee leave. The body is{ "reason": "requestedByCustomer" }(orduplicateorfraudulent), and it needs themanagepermission and anIdempotency-Key. The money goes back to the wallet that paid, and theorder-item.refundedwebhook 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. 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
Where a booking can be amended by API (actions.amendment.availability is available):
POST /v1/order-items/{id}/amendments/quotetakes{ "attributes": { ... } }with the changes you want and returnsamendmentRequestId,expiresAtandoptions, each{ id, amountToPay, amountToRefund, amendmentFee }. Nothing is charged yet.POST /v1/order-items/{id}/amendments/confirmtakes{ "amendmentRequestId": "...", "paymentMethod": "balance", "selectedOptionId": "...", "maxPrice": { ... } }.maxPriceis 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, or across
items with GET /v1/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
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 with { "attributes": { ... } }. Returns { amendmentId }. Needs an Idempotency-Key. |
| Approve the quote | POST /v1/order-items/{id}/manual-amendments/{amendmentId}/approve. 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. Nothing is charged. |
| Cancel an unquoted request | POST /v1/order-items/{id}/manual-amendments/{amendmentId}/cancel. 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
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
GET /v1/hotels/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
Sandbox supports hotels. It uses the same routes, validation, pricing and webhooks as production with a synthetic catalog and test wallet funds; see 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
cityCodeor 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) andDPS(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.maxPriceone minor unit below the quoted price to get409 / 11002. - Reuse an offer after its
details.expiresAtto 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 returns409 / 11003before 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
Shared error handling is in 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.