Skip to Content
OpenRoam Docs

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

StepRoute
Find a place by name (optional)GET /v1/hotels/destinations
Search hotels and their offersPOST /v1/hotels/search
Read one hotel's content (optional)GET /v1/hotels/properties/{id}
Quote a ratePOST /v1/hotels/quote
Book itPOST /v1/hotels/order

Reference data routes:

  • GET /v1/hotels/amenities/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 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.

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

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
  }'
FieldRequiredRules
searchCriteriayeslocation or hotelIds. A non-empty hotelIds wins and location is then ignored.
searchCriteria.locationone of the twoAn 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.hotelIdsone of the twoUp to 50 hotel ids (hotel_...) from an earlier search. Returns every rate of those hotels with the full detail, as one page.
checkIn, checkOutyesDates (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.
roomsyes1 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.
guestNationalityyesISO 3166-1 alpha-2, for example GB. Rates are priced for this market.
guestCountryOfResidencenoISO 3166-1 alpha-2. Defaults to guestNationality.
currencynoThree letters. Defaults to your API key's currency.
filtersnominStarRating, maxStarRating, minPrice, maxPrice (for the whole stay), boardTypes, amenityCodes and cancellationTypes. No other member is accepted.
cursor, limitnoLocation 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:

  • 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

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.

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:

FieldMeaning
publicIdThe offer id you quote and order with, until details.expiresAt. It names the rate, not the hotel.
priceThe 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.roomsOne room per searched room, with roomGroupKey, which is equal for every rate of the same physical room.
details.boardcode (RO, BB, HB, FB, AI or OTHER) and boardType (roomOnly, breakfast, halfBoard, fullBoard, allInclusive or unknown).
details.termsThe booking terms: payment, cancellation and changes.
details.taxesTaxes already included in price.
details.surchargesFees outside the room rate. See Surcharges.
details.minimumSellingPriceWhen present, the lowest price at which you may resell the stay. See below.
details.amendabilityStatusyes, no or unknown: whether the booking can be amended.
details.guestNameRulesWhat the booking accepts as a first and last name, so your form can validate before ordering.
details.allowsSpecialRequests, details.specialRequestOptionsWhen 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" }
      }
    }
  ]
}
  • 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

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

InputRequiredMeaning
holderyesThe 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).
roomGuestsyesOne entry per searched room: roomIndex (1-based, each room once) and guests, every adult and child in the room.
specialRequestsnoFree text, at most 500 characters, for rates without a code list. The hotel may not honour it.
specialRequestCodesnoUp to 32 distinct codes from the rate's specialRequestOptions, applied to every room.
maxPricenoThe 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" }
}
  • 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

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

ItemQuoteOrder
With inputs.maxPriceA 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.maxPrice200 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.json

The 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.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

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. 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

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.

  • 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:

FieldMeaning
bookingStatusconfirmed, pending, onRequest, cancelled or failed.
hotelConfirmationNumberThe 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.
amendmentCompositionWhat 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.
bookingThe 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

  1. GET /v1/order-items/{id}/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 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 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. 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):

  1. POST /v1/order-items/{id}/amendments/quote 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 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, 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.

StepRoute
Request onePOST /v1/order-items/{id}/manual-amendments with { "attributes": { ... } }. Returns { amendmentId }. Needs an Idempotency-Key.
Approve the quotePOST /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 quotePOST /v1/order-items/{id}/manual-amendments/{amendmentId}/decline. Nothing is charged.
Cancel an unquoted requestPOST /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 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:

boardTypeRoomCancellation
roomOnlyStandard roomStandard cancellation
breakfastStandard roomStandard cancellation
unknown (Brunch package)Deluxe roomStandard cancellation
halfBoardDeluxe roomFree until 00:00 UTC two days before check-in, 25% kept from then, 100% at check-in midnight
fullBoardDeluxe roomNon-refundable from purchase
allInclusiveSuiteFree 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 valueResult
success (or no header)A confirmed reservation and a readable result.
fulfillment.rejectedA terminal failed reservation after payment, with no fulfilled result. The item is refunded automatically.
fulfillment.pendingReturns pending at once. The item becomes eligible for success after 15 minutes.
fulfillment.late_successReturns pending at once and becomes eligible for success after 2 minutes.
fulfillment.late_rejectedReturns 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 / codeName or reasonWhen and what to do
400 / 10001INVALID_VALUEAn 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 / 10001MAX_STAY_EXCEEDEDThe stay is longer than 30 nights, at checkOut.
400 / 10001REQUIREDAn order item without inputs, at items[i].inputs.
400 / 10001NOT_SUPPORTEDA currency OpenRoam does not support, at currency.
400 / 11004EXPIRED_OR_INVALIDAn unknown, expired or foreign offer id, a hotel's own id, or another product's offer. Search again for a fresh offer.
409 / 11003UNAVAILABLEThe rate is no longer sold, or it can only be held on request. Pick another offer.
409 / 11002PRICE_CHANGEDThe fresh price is above your cap or above the price returned with the publicId. Nothing is charged. Quote again.
409 / 11006TERMS_CHANGEDThe cancellation terms got stricter than the quote's. Quote again and check the terms.
400 / 11005CURRENCY_MISMATCHThe offer was priced in another currency than the order. Search or quote in the order currency.
403 / 10003SERVICE_NOT_ENABLEDHotels are not enabled for your account.
404 / 10004noneGET /v1/hotels/properties/{id} with an id of no catalog hotel.
400 / 21000HOTEL_ID_INVALIDA hotelIds entry that is not a hotel id.
400 / 21010HOTEL_OCCUPANCY_MISMATCHThe rate's room layout no longer matches the searched rooms. Search again.
503 / 21003HOTEL_RATE_CONTEXT_UNAVAILABLEHotel offers are temporarily unavailable. Retry a search or quote later. After an order, check the existing order before retrying.
502 / 21007, 504 / 21008, 503 / 21009HOTEL_REQUEST_FAILED, HOTEL_RESPONSE_TIMEOUT, HOTEL_TEMPORARILY_UNAVAILABLEThe hotel request failed, timed out or is unavailable. Retry read-only calls later. For writes, check the order state before retrying.
503 / 10007noneThe destination lookup is unavailable. Retry.
400 / 21004HOTEL_BOOKING_UNAVAILABLEThe item has no valid booking to cancel or amend. Reload the order.
400 / 21005HOTEL_AMENDMENT_UNSUPPORTEDThis booking does not support the amendment mode you tried.
400 / 21102HOTEL_AMENDMENT_TICKET_ALREADY_OPENA manual amendment is already open for this booking. Use the existing one.
400 / 21103HOTEL_AMENDMENT_INVALID_STATEThe action is not allowed in the amendment's current state. Reload it first.
400 / 21107HOTEL_AMENDMENT_INSUFFICIENT_BALANCEThe wallet cannot cover the amendment. Fund it, then approve again.
409 / 21111HOTEL_AMENDMENT_ORDER_BUSYThe booking is being processed. Try again shortly.
409 / 21112HOTEL_AMENDMENT_CONCURRENT_CHANGEAnother request updated the amendment. Reload and retry.
400 / 21113HOTEL_AMENDMENT_INVALID_GUEST_COMPOSITIONThe requested rooms, guests, names or ages are invalid.
400 / 21114, 400 / 21115HOTEL_AMENDMENT_GUEST_COMPOSITION_CHANGE_UNSUPPORTED, HOTEL_AMENDMENT_CHANGE_UNSUPPORTEDThe room or guest change (21114), or the date or holder change (21115), is not supported for this booking. Check amendmentComposition.
400 / 21108, 409 / 21109HOTEL_AMENDMENT_SETTLEMENT_FAILED, HOTEL_AMENDMENT_SETTLEMENT_CONFLICTThe settlement could not be completed. Do not retry automatically: reload the amendment and contact support.
409 / 18003MANUAL_REVIEW, IN_PROGRESS or NOT_AVAILABLEAn amendment cannot be quoted or confirmed now. MANUAL_REVIEW points to manual amendments.
422 / 18004noneupdate 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.

On this page