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.
The current non-production staging/sandbox catalogue intentionally contains only a limited set of places and hotels. It is suitable for validating the complete integration flow, but it is not a copy of the production dataset. Always begin with destination autocomplete and test with an ID returned by that environment.

​
Approval for bookings outside free cancellation

The search, room selection, prebook and booking request bodies are unchanged. Offers with an active, verified free-cancellation window start in PROCESSING and queue supplier booking immediately. Non-refundable offers, expired free windows and unclear cancellation terms create an AWAITING_REVIEW request. For these requests, an organization owner/admin must verify the property, every room allocation, guests and terms in the portal and approve before the original prebooking deadline. If free cancellation ends before supplier submission, an automatically queued booking also moves to review. Never issue a confirmed voucher for an awaiting-review request. Rejection/expiry fails the request without a supplier reservation. There is no price-refresh or deferred-purchase workflow in this phase.

​
End-to-End Flow

1

Choose a destination

Use Destination Autocomplete to power the destination picker. Save the selected type and the matching 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. Connect to the returned room stream and collect complete options from provider_options events until done.
6

Verify before checkout

Send the selected option’s booking_token together with its hotel_id to Prebook a Room. Show any availability or price change before the customer confirms. Build room guest assignments from the room allocations returned by prebook.
7

Create one protected booking attempt

Send the prebooking ID, room allocation IDs, and guest details to Create Booking with one unique Idempotency-Key. Use HOLD only when the prebook offer explicitly allows it. Currently only TripJack provides this mode; confirm it before the returned deadline.
8

Track the booking

Poll Get Booking Status until the booking reaches its final state. Use Get Booking Details for itineraries. Before cancellation, obtain a Cancellation Quote, display the consequence, and then call Cancel Booking.

​
Values to Keep During the Flow

​
Identifier Lifecycle

Use each identifier only for the job it was designed to do: All tokens and allocation IDs are opaque. Copy them unchanged; do not generate, decode, concatenate, or infer meaning from their format.

​
Render Mapped and Unmapped Rooms

Supplier rooms do not always map to a static Unifystays room record. This is expected and does not block booking. Every streamed room includes a provider_room object, even when no Unifystays room ID exists: For every streamed room, render its nested unifystays_room when present; otherwise render provider_room. Never remove an option from the customer experience only because its Unifystays room mapping is missing.
Use mapping_details for diagnostics only. Use booking_token to select the complete option and room_allocation_id to assign guests and identify booking room instances. Neither unifystays_room.room_id nor provider_room.id is a booking identifier.

​
Multi-Room Rule

The request to Get Room Options contains one occupancy object per required room. A selected option and its prebook response therefore contain one allocation per requested room. Even if two rooms have the same supplier name, keep both entries because their allocation IDs are different. During Create Booking, send every prebook allocation exactly once and attach the guest list matching that allocation’s occupancy. Array order is not significant.
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