Hotel Booking Flow

This guide ties the endpoint pages together into one guest journey. It tells you what to call, what to show the guest, what to save, and what to do when something expires or fails. For a hands-on run of the same flow, see the Quickstart. For every ID and token, see the IDs and Tokens Cheat Sheet.

Sandbox only has hotels in 12 test cities, such as Dubai, Paris, Tokyo and Bangkok. Start every test from Sandbox autocomplete for one of those cities, and use IDs from the same environment.

The flow at a glance

Step by step

For each step: what to call, what to show the guest, what to persist, and what can expire.

1. Destination and nationality


Call	Destination Autocomplete while the guest types (3 or more characters, debounced). Nationalities once, for the guest form. Optionally Hotel Filters for a filter drawer.
Show	A balanced list of places and hotels with `display_name`, `subtext` and an icon from `category`. A nationality dropdown.
Persist	The selected result’s `type` plus `place_id` or `hotel_id`; the nationality `iso_code`.
Expires	Nothing. These are cacheable. See Caching Strategy.

2. Search


Call	Search Hotels with `pricing_mode: "instant"`.
Show	Hotel cards immediately, each with a price state (see price states).
Persist	`data.search_id`, the cursor (`next_cursor`) for paging, and the exact search inputs (dates, rooms, `child_ages`, nationality). You must repeat them unchanged for rooms.
Expires	`search_id` is valid for about 5 minutes. After that the price endpoint returns `404`: search again.

3. Live prices


Call	Get Search Price Updates every 2 seconds while the result page is visible and `data.refresh_status` was `PENDING`. Pass `refresh_ids` (up to 50) for the hotels on screen.
Show	Replace each card’s `price` and `supplier_prices` by `hotel_id`. Keep the server’s order.
Persist	Nothing beyond the card state.
Expires	Stop on `COMPLETE` or `EXPIRED`, or when the guest leaves. Polling with `refresh_ids` extends the `search_id` by 5 minutes.

4. Property detail and rooms


Call	Hotel Content for the property page (cacheable). Get Hotel Rooms, then open the returned `sse_stream_url` (Stream Room Updates) straight away.
Show	Room cards built from families and variants (see room cards), filled in as `provider_options` events arrive, with a “still searching” state until `done`.
Persist	Offers in memory for this page. Keep the chosen offer’s `booking_token` only until prebook.
Expires	The whole room search is capped at 45 seconds (each supplier about 20 seconds). The stream sends a heartbeat every 15 seconds. A finished stream stays readable for about 2 minutes, then returns `404`. Each `booking_token` is valid for at most 15 minutes (`lifecycle.expires_at`).

5. Prebook


Call	Prebook a Room with the same `hotel_id` and the chosen `booking_token`, when the guest starts checkout (not earlier).
Show	The refreshed, final price and cancellation terms from `data.offer`; any `RECONFIRMATION_REQUIRED` change; every notice with `must_display: true`. Build the guest form from `booking_requirements`.
Persist	`prebooking_id`, `offer.offer_id`, each `room_allocation_id` with its `occupancy`, and a copy of the cancellation policy shown.
Expires	The `prebooking_id` and offer are valid until `offer.lifecycle.expires_at`: the supplier’s own deadline when it gives one, otherwise 15 minutes after the prebook call. The `prebooking_id` is single use. Show a countdown.

6. Create the booking


Call	Create Booking with a fresh `Idempotency-Key` that you have already saved, the `prebooking_id`, `accepted_offer_id`, and every room’s guests and answers. Use `booking_mode: "HOLD"` only when the prebook offer lists `HOLD` in `lifecycle.available_booking_modes` (Confirm Hold).
Show	”We are booking your room.” Never “Confirmed”. Non-refundable offers and free cancellation ending within 2 days start as `PROCESSING` too, unless your organization requires approval for them. If the status is `AWAITING_REVIEW`, show “Awaiting verification: room and price are not reserved”.
Persist	`data.booking_id` immediately, with your order number and the `Idempotency-Key`.
Expires	Create Booking has to happen before the prebooking expires. A validation error does not consume the `prebooking_id`; fix the body and resend.

7. Track the result


Call	Receive webhooks and use Get Booking Status as the fallback poll (wait `next_poll_after_ms`, or about 5 seconds). Read Get Booking Details for the itinerary and voucher data.
Show	See booking status screens.
Persist	The status, `provider.booking_id` and `booking_code`, and `hotel_confirmation_number` once present (it can arrive after `CONFIRMED`).
Expires	A booking that is `AWAITING_REVIEW` waits for approval in the portal. Do not cancel or refund because `review_expires_at` passed. If it waits too long (quote expired over 24 hours ago, check-in reached, or a later booking replaced it) it fails with `BOOKING_REVIEW_EXPIRED` and a `booking.failed` webhook. An `ON_HOLD` booking must be confirmed before `hold_deadline_at`.

8. Cancel


Call	Only if `available_actions` contains `CANCEL`: Quote Cancellation, show the penalty, then Cancel Booking with the `quote_id` and a new `Idempotency-Key`.
Show	`NO_CHARGE`, a known amount, or “charge not known” for `UNKNOWN` (never as zero). Say “cancelled” only at `CANCELLED`.
Persist	The cancellation `Idempotency-Key` and the final charge from booking details.
Expires	A quote lasts 5 minutes (or less if the penalty is about to change) and works once. If it is rejected as invalid, request a new quote.

Time limits

What	Limit	Source
Autocomplete cache	Up to 48 hours	Destination Autocomplete
Nationalities cache	Up to 30 days	Nationalities
`search_id`	About 5 minutes; `refresh_ids` polling extends it by 5	Search Price Updates
`recent` search price	A stored quote for the same search, at most about 3 hours old	Search Hotels
Price polling	Every 2 seconds, only while visible	Search Price Updates
Room search	Capped at 45 seconds; about 20 seconds per supplier; heartbeat every 15 seconds	Stream Room Updates
Finished room stream	Readable about 2 minutes; the latest 250 events are kept for reconnects	Stream Room Updates
`booking_token`	At most 15 minutes (`lifecycle.expires_at`)	Stream Room Updates
Repeated prebook of one token	Returns the stored result without asking the supplier again; use a fresh token for a fresh check	Prebook a Room
`prebooking_id` and prebook offer	Until `offer.lifecycle.expires_at` (supplier deadline, else 15 minutes). Single use	Prebook a Room
Manual approval threshold	Free-cancellation window ending within 2 days, or non-refundable: `AWAITING_REVIEW` only when the organization requires approval, otherwise `PROCESSING`	Create Booking
Cancellation quote	5 minutes, single use	Quote Cancellation
Webhook receiver	Must answer `2xx` within 10 seconds; 8 attempts over about 3.5 days	Webhooks

Error recovery

Work from the guest’s point of view: tell them what happened, then return them to the earliest step that can fix it. Full code list: Errors & Retries.

Situation	What it looks like	Recover
Create Booking timed out or you lost the response	No usable response; no `booking_id` saved	Call Find Booking by Idempotency-Key with the same key. `200`: continue with that booking. `404`: nothing was created, so resend Create Booking with the same key and the same body. Never use a new key for an uncertain result.
Booking is slow	`PROCESSING`, possibly `processing_reason: "RECONCILIATION_REQUIRED"`	Keep polling or wait for the webhook. Do not book again. If `available_actions` has `CONTACT_SUPPORT`, contact support with the `booking_id` and `X-Request-Id`.
Price changed at prebook	`revalidation.decision` is `RECONFIRMATION_REQUIRED`	Show the refreshed offer and what changed (`revalidation.changes[]`, `money_change`). If the guest accepts, book with the same `prebooking_id` and `offer_id`. If not, return to rooms.
Room no longer bookable	`decision` is `NOT_BOOKABLE` (HTTP 200, `prebooking_id` null), or error `OFFER_UNAVAILABLE`	Send the guest back to room selection and run a new rooms search.
Token or prebooking expired	`BOOKING_TOKEN_EXPIRED`, `PREBOOKING_ID_EXPIRED`	Start a new rooms search, pick again, prebook again. Do not retry with the old value.
Prebooking already used	`PREBOOKING_ID_ALREADY_USED`	The booking may already exist. Look it up by idempotency key before prebooking again.
Prebook already running	`409 PREBOOK_IN_PROGRESS` with `Retry-After`	Wait the seconds given and repeat the identical request. Never run parallel prebooks for one token.
Wrong rooms or guests in the booking	`BOOKING_ROOM_COUNT_MISMATCH`, `BOOKING_ROOM_ALLOCATION_MISMATCH`, `BOOKING_ROOM_OCCUPANCY_MISMATCH`, `VALIDATION_ERROR`	Rebuild `rooms[]` from every prebook allocation; match guest types to `occupancy`; answer every applicable requirement. Nothing was consumed, so resend.
One supplier failed or is slow during rooms	`provider_error` or `provider_skipped` event; `done.status` is `PARTIAL`	Show the offers you have. Offer “search again” only on `FAILED`.
Stream dropped	Connection closes before `done`	Reconnect with `Last-Event-ID`. `409 ROOM_STREAM_REPLAY_GAP` or `404 ROOM_STREAM_NOT_FOUND`: start a new rooms search.
Supplier error at prebook or book	`PROVIDER_REQUEST_FAILED`, `PROVIDER_RATE_LIMITED`, `503`	Retry with backoff only when `details.retryable` is `true`; otherwise offer another room.
Supplier listing could not be verified	`HOTEL_MAPPING_UNVERIFIED`, `HOTEL_MAPPING_CHECK_PENDING`	Offer another room option. For `PENDING`, retry after a few seconds.
Booking `FAILED`	`status: FAILED`, `success: false`	Read `failure.code` in booking details, tell the guest, and restart from rooms. A new attempt needs a new `Idempotency-Key`.
Search expired	`404` on the price endpoint	Run the search again.

Build the guest experience

Price states

Search prices are shopping data. Decide what to show from price.status, never from amount alone.

`price.status`	Show
`live`	The price.
`recent`	The price (optionally “as of” `fetched_at`).
`checking`	A spinner or “checking prices”. Keep polling.
`no_price`	”Sold out for these dates”. Badge, move down or hide as you prefer.
`unpriced`	”Unavailable”, with a retry (search again) unless `reason` is `not_mapped`.

price.amount is the whole-stay total in cents of price.currency. It is null unless the status is live or recent, so never show 0. It can go down while you poll when a cheaper supplier answers. Show the indicative nature of the price (“from”) until the guest reaches prebook, where the price is confirmed.

Room cards

Rooms arrive as family objects (a room type) with variants (one bed configuration each). Offers from several suppliers sit on the same family or variant. Draw one card per family:

Header: the family name and details (photos, size, description, amenities), labelled with details.source.
Variants: show beds, bedrooms, max_guests and smoking only from the variant object. null means unknown.
Offer rows: one per offer, with the price from pricing.native_ledger.totals[0].total, meal plan label, cancellation badge from cancellation.refundability and the free-cancellation deadline. Offers listed under bed_assignment.suppliers go under “Bed type assigned by the hotel”.
Always show each row’s own provider_room beds and maximum guests.
Show must_display notices before the guest books, and payable_at_property as “pay at hotel”.
A later event can replace a family: store families by unifystays_room_id and overwrite.

Grouping only decides where an offer is drawn. You always book the supplier’s own offer with booking_token and room_allocation_id. Never use a room or family ID as a booking key. See Get Hotel Rooms for the client logic and card keys for multi-room searches.

Checkout

Build the form from the prebook booking_requirements: label, control from value_type, allowed_values, constraints, and who answers from scope and room_allocation_ids. Ask once, after prebook.
For each room create one ADULT per adult and one minor per child age (age 0 or 1 is INFANT, 2 and over is CHILD). Exactly one guest in the booking is the lead guest.
Show a countdown to offer.lifecycle.expires_at, and the full cancellation policy and notices before the guest pays.
Unifystays does not collect payment from the guest. payment.payer and payment.collection_timing tell you who is charged and when.

Booking status screens

`status`	Show	Do
`AWAITING_REVIEW`	”Awaiting verification: room and price are not reserved.”	Never issue a voucher. Wait for the webhook.
`PROCESSING`	”Booking in progress.”	Wait for webhooks; poll every few seconds as a fallback.
`CONFIRMED`	Confirmation and voucher.	Show `hotel_confirmation_number` when present; if it is `null`, show “hotel number to follow” and read again later.
`ON_HOLD`	”Reserved, not final.”	Confirm before `hold_deadline_at` (Confirm Hold), or cancel.
`FAILED`	A friendly failure message of your own.	Offer to search again.
`CANCELLATION_PENDING`	”Cancellation requested.”	Poll until `CANCELLED`.
`CANCELLED`	Cancellation outcome and any charge.	Final.

Multi-room bookings

A rooms request holds one occupancy object per room. The chosen offer, its prebook and the booking all contain one allocation per requested room. Keep two rooms with the same name as two entries: their room_allocation_id values differ. Never mix rooms from different offers. In Create Booking, send every prebook allocation exactly once; array order does not matter.

A search price or a room option is not a booking guarantee. Prebook right before booking, and book with the prebooking_id and offer_id of that same prebook response.

Read Caching Strategy, Errors & Retries and the Launch Checklist.

Get started

Build your integration

Operate

The flow at a glance

Step by step

1. Destination and nationality

2. Search

3. Live prices

4. Property detail and rooms

5. Prebook

6. Create the booking

7. Track the result

8. Cancel

Time limits

Error recovery

Build the guest experience

Price states

Room cards

Checkout

Booking status screens

Multi-room bookings

Next

​The flow at a glance

​Step by step

​1. Destination and nationality

​2. Search

​3. Live prices

​4. Property detail and rooms

​5. Prebook

​6. Create the booking

​7. Track the result

​8. Cancel

​Time limits

​Error recovery

​Build the guest experience

​Price states

​Room cards

​Checkout

​Booking status screens

​Multi-room bookings

​Next

The flow at a glance

Step by step

1. Destination and nationality

2. Search

3. Live prices

4. Property detail and rooms

5. Prebook

6. Create the booking

7. Track the result

8. Cancel

Time limits

Error recovery

Build the guest experience

Price states

Room cards

Checkout

Booking status screens

Multi-room bookings

Next