> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unifystays.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hotel Booking Flow

> Build a complete search-to-booking experience with the unified Unifystays API.

This guide explains how the endpoint-level API reference fits into one
customer-facing hotel booking flow. Your integration stores the selections and
booking identifiers needed for its own customer experience; Unifystays handles
supplier-specific inventory, mappings, and API differences behind the unified
contract.

## End-to-End Flow

<Steps>
  <Step title="Choose a destination">
    Use [Destination Autocomplete](/api-reference/destination-autocomplete) to
    power the destination picker. Save the selected `type` and the matching
    `city_id`, `hotel_id`, or `place_id`.
  </Step>

  <Step title="Choose the guest nationality">
    Load [Nationalities](/api-reference/nationalities) and send the selected
    `iso_code` as `nationality` in shopping requests.
  </Step>

  <Step title="Search hotels">
    Call [Search Hotels](/api-reference/search-hotels). For a responsive
    customer result page, use `pricing_mode: "instant"` and retain the returned
    `search_id`.
  </Step>

  <Step title="Refresh live prices">
    While the customer is looking at results, call
    [Get Search Price Updates](/api-reference/search-price-updates) every two
    seconds. Merge updated prices by `hotel_id`.
  </Step>

  <Step title="Show property and room choices">
    Fetch optional static detail with
    [Get Hotel Content](/api-reference/hotel-content), then use
    [Get Room Options](/api-reference/hotel-rooms) for the customer's selected
    hotel, dates, room occupancy, and nationality.
  </Step>

  <Step title="Verify before checkout">
    Send the selected room's `booking_token` to
    [Prebook a Room](/api-reference/prebook). Show any availability or price
    change before the customer confirms.
  </Step>

  <Step title="Create one protected booking attempt">
    Send the prebooking ID, room references, and guest details to
    [Create Booking](/api-reference/create-booking) with one unique
    `Idempotency-Key`.
  </Step>

  <Step title="Track the booking">
    Poll [Get Booking Status](/api-reference/get-booking-status) until the
    booking reaches its final state. Use
    [Get Booking Details](/api-reference/get-booking-details) for itineraries
    and use [Cancel Booking](/api-reference/cancel-booking) when needed.
  </Step>
</Steps>

## Values to Keep During the Flow

| Value                                                 | Source                   | Use                                                    |
| ----------------------------------------------------- | ------------------------ | ------------------------------------------------------ |
| Destination type and ID                               | Destination autocomplete | Hotel search scope.                                    |
| Nationality `iso_code`                                | Nationalities            | Hotel search and room options.                         |
| `search_id`                                           | Hotel search             | Live price refreshes.                                  |
| `booking_token`                                       | Room options             | Prebook the selected option.                           |
| `unifystays_prebooking_id` and room `room_ref` values | Prebook                  | Create the booking with matching guest details.        |
| `booking_id`                                          | Create booking           | Status polling, itinerary retrieval, and cancellation. |

<Warning>
  Do not treat a search price or room option as a booking guarantee. A room must
  be prebooked immediately before booking, and supplier availability can change
  between steps.
</Warning>

## Suggested Customer Experience

Use cached destination and nationality data to make forms responsive. Treat
hotel search as a shopping state, room options as live availability, prebook as
the final price check, and the booking status as the source of truth after
checkout. This keeps supplier behavior behind the Unifystays API rather than in
your own frontend or supplier-specific data jobs.

[Review caching guidance](/guides/caching-strategy)