Why Three Steps?
Hotel inventory is volatile. A rate returned by a search query can change — or the room can sell out entirely — within seconds of the search completing. The three-step flow exists to protect both the buyer and the supplier from transacting on stale data.
Search is a broad availability sweep — fast but not a contract. Quote is a point-in-time revalidation that confirms the current price and cancellation policy for a specific option. Only then should Book be called — and only with the optionRefId returned by the most recent Quote, not the one from Search.
Skipping Quote and booking directly from a Search result is the most common integration mistake. It results in price mismatches, unexpected cancellation terms, and failed bookings — all of which are avoidable.
Step 1 — Search
The Search query accepts a destination (hotel codes, geolocation or destination code), check-in and check-out dates, occupancy (rooms, adults, children), and optional filters (board type, max price, rating). It returns a list of options, each with its own optionRefId.
Apply the CheapestPrice plugin at this step to deduplicate: one option per hotel/room/board combination. Without it, a single hotel can return hundreds of near-identical options from multiple suppliers, creating an overwhelming and misleading result set.
Apply the Preference plugin to rank results according to your commercial priorities before transmitting them to the client — preferred suppliers first, minimum margin enforced.
"Never persist a Search optionRefId in a database or share it between users. It is a short-lived reference token, not a stable identifier. Its only valid use is as input to a Quote call made in the same session."
Speed — Travelgate's dynamic caching layer — operates at the Search level. In Standard mode, up to 80% of Search requests are served from cache, reducing supplier load and improving response times dramatically for high-volume deployments.
Step 2 — Quote
Quote accepts the optionRefId from Search and calls the supplier to revalidate the current price and cancellation policy. It always returns a new optionRefId — this is the one that must be used in Book.
Quote is where DeltaPrice is enforced. If the revalidated price exceeds the Search price by more than the configured tolerance (typically 1–2%), the Quote is rejected and the buyer must be notified before proceeding. Never silently absorb a price increase between Quote and Book.
Quote also returns the definitive cancellation policy — deadlines, penalty amounts, and whether the booking is refundable, non-refundable, or conditional. This must be presented to the user explicitly and confirmed before Book is called.
Step 3 — Book
Book accepts the optionRefId from Quote, passenger details (lead guest name, email, and any supplier-required fields), payment type, and — where required — card details. It returns a booking reference from the supplier plus Travelgate's internal reference, and a status.
The status field is critical. A successful Book returns OK, but some suppliers return ON_REQUEST — meaning the booking has been received but is pending supplier confirmation. This is not an error. The booking must be held in a pending state and the user notified that confirmation is incoming.
Never retry a Book call that timed out without first checking BookingQuery to confirm whether the booking was created. Double-booking is a serious operational and financial problem that is entirely avoidable with this check.
Session State & optionRefId
The optionRefId chain — Search → Quote → Book — must be maintained in server-side session state. Never pass it through the browser or store it in localStorage. It is a transaction token, not a display identifier.
Edge Cases
ON_REQUEST status
Hold the booking, notify the user, poll BookingQuery periodically or configure a webhook to receive the supplier's confirmation. Do not show success UI until status changes to OK.
DeltaPrice rejection
Surface the price change to the user with the original and new price displayed. Give them the choice to accept and proceed or abandon and restart search. Never absorb the increase silently.
Book timeout
Call BookingQuery with the Travelgate reference before retrying. A timeout does not mean the booking failed — the supplier may have confirmed it after your connection dropped.
NO_RESULTS on Search
Widen the search: try adjacent dates, remove board-type filters, expand the destination radius, or try a Multi Search across additional supplier accesses.
Cancellation Flow
Cancellation uses BookingCancel with the booking reference. Before executing, always call BookingQuery to retrieve the current cancellation policy and calculate the live penalty — policies can change and the penalty shown at booking time may differ from today's.
Present the penalty to the user explicitly and require confirmation before calling BookingCancel. Log both the query response and the cancellation confirmation in your audit trail.
Summary
The three-step flow is not bureaucracy — it is the mechanism that makes reliable, accurate hotel booking possible across hundreds of suppliers with volatile inventory. Respect the sequence, maintain the optionRefId chain in server-side session state, handle ON_REQUEST and DeltaPrice explicitly, and always check BookingQuery before retrying a failed Book.
Every edge case in the Hotel-X integration is predictable and documented. The integration challenges arise not from the API being complex, but from shortcuts taken against its design intent.
See it in action
Tanya runs the full Search-Quote-Book flow in every conversation. Ask her to find a hotel and watch each step happen live.