The Hotel-X Booking Flow Explained: Search, Quote & Book

Overview

Travelgate's Hotel-X API exposes hotel inventory through a structured three-step flow: Search, Quote, and Book. Each step serves a distinct purpose, and skipping or conflating them is the most common source of integration defects.

This guide walks through each step, explains the design decisions behind the sequence, and provides patterns for the edge cases that trip up most integrators: ON_REQUEST options, DeltaPrice discrepancies, and Book operation timeouts.

Step 1 — Search (HotelSearchRS)

The Search step accepts check-in/check-out dates, occupancy, destination (hotel codes, destination codes, or coordinates), and market/currency parameters. It returns a list of available options with indicative pricing.

Crucially, Search prices are not guaranteed. They reflect the supplier's cached availability and are subject to change between Search and Quote. Never present Search prices as bookable rates without a subsequent Quote call.

Step 2 — Quote (HotelBookingQuoteRS)

The Quote step accepts the optionRefId returned by Search and retrieves a live, confirmed rate from the supplier. The response includes the exact price, cancellation policies, and a quoteToken valid for a short window (typically 15–30 minutes).

If the price returned by Quote differs from the Search price, you will receive a DeltaPrice flag. Your integration must handle this: present the updated price to the user and obtain fresh consent before proceeding to Book.

Step 3 — Book (HotelBookRS)

The Book step accepts the quoteToken, passenger details, and payment information. On success it returns a booking reference from the supplier, which you should store immediately in your database before returning a response to the user.

Book is not idempotent. If you receive a timeout, do not retry without first executing a BookingsList query using your clientReference to check whether the booking was created on the supplier side. Silent duplicate bookings are the most expensive failure mode in hotel distribution.

Handling ON_REQUEST Options

Some supplier options return with status ON_REQUEST, meaning the property must confirm availability before the booking is finalised. Your UX should clearly communicate this: 'Subject to availability confirmation — you will be notified within 4 hours.'

Set a webhook or polling job to check booking status at 30-minute intervals. If the booking transitions to CONFIRMED, issue the confirmation to the user. If it transitions to CANCELLED, trigger a full refund and offer an alternative.

DeltaPrice Logic

DeltaPrice is returned when the Quote price differs from the Search price. The field contains the absolute difference and a percentage. Your integration should define a threshold — typically 2–5% — below which the difference is auto-accepted and the user is notified post-booking.

Above the threshold, pause the flow, present the updated price to the user with a clear explanation, and require explicit re-confirmation before proceeding to Book.

Timeout & Recovery Patterns

Book operations can take 10–30 seconds for some suppliers. Set a client-side timeout of 45 seconds with a spinner and progress message. If you receive a timeout response, immediately query BookingsList with your clientReference — which you should have generated and stored before calling Book.

If BookingsList returns a booking with your reference, treat the operation as successful. If it returns empty, it is safe to retry once. After a second timeout on retry, present an error and queue a background reconciliation task for 10 minutes later.

Try It Yourself