Skip to main content
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

1

Choose a destination

Use Destination Autocomplete to power the destination picker. Save the selected type and the matching city_id, hotel_id, or place_id.
2

Choose the guest nationality

Load Nationalities and send the selected iso_code as nationality in shopping requests.
3

Search hotels

Call Search Hotels. For a responsive customer result page, use pricing_mode: "instant" and retain the returned search_id.
4

Refresh live prices

While the customer is looking at results, call Get Search Price Updates every two seconds. Merge updated prices by hotel_id.
5

Show property and room choices

Fetch optional static detail with Get Hotel Content, then use Get Room Options for the customer’s selected hotel, dates, room occupancy, and nationality.
6

Verify before checkout

Send the selected room’s booking_token to Prebook a Room. Show any availability or price change before the customer confirms.
7

Create one protected booking attempt

Send the prebooking ID, room references, and guest details to Create Booking with one unique Idempotency-Key.
8

Track the booking

Poll Get Booking Status until the booking reaches its final state. Use Get Booking Details for itineraries and use Cancel Booking when needed.

​
Values to Keep During the Flow

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.

​
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