How booking works
The four calls behind every booking, and what each one does and does not guarantee.
A booking takes up to four calls. Each one is closer to the PMS than the one before, and each one is more expensive.
Search finds candidates
Search reads OnSeason's synchronized copy of each property's calendar and rates. It is fast enough for result pages and ranking. Its prices are indicative: they include your channel's pricing, but the PMS can change a rate after the last sync. Search never holds inventory and never returns a token.
Availability fills a calendar
Availability returns one row per date for a single property, with the price and the minimum and maximum stay for a booking that starts on that date. It reads the same synchronized data as search. Use it to draw a date picker or to rule out a stay before you quote it.
Quote fixes the price and the terms
A quote asks the PMS for the current price of one stay. The response has the full breakdown of nightly rates, fees, taxes, and discounts. It also carries the cancellation terms for the stay and a signed quoteToken. The token binds the listing, unit, dates, guest count, prices, and terms, and it expires after 15 minutes.
A quote is not a hold. Another channel can book the same dates between your quote and your reservation.
Reservation confirms the booking
A reservation sends the token with the guest's details. OnSeason checks the token, asks the PMS for availability one more time, and books the stay at the signed price and under the signed terms. A 201 response with status CONFIRMED is the booking confirmation.
After a booking, store the OnSeason reservation id and the PMS's providerReservationID. You use id to read and cancel the reservation. The PMS reference helps when you talk to OnSeason support or to the host.
When to call what
| Moment in your product | Call |
|---|---|
| Building or refreshing your catalogue | List listings, Get a listing, List units |
| Results page | Search or Search by IDs |
| Property page with a date picker | Get availability |
| Guest opens checkout | Create a quote |
| Guest confirms and pays you | Create a reservation |
| Booking management | Get a reservation, Cancel a reservation |