Bookings
A published holiday home (listing_type holiday_home, priced per night) can be booked from the website in three calls, when the company has bookings switched on. Otherwise these operations answer 404.
1. Availability and rules
GET /api/v1/listings/{slug}/availability?from=YYYY-MM-DD&to=YYYY-MM-DD returns the blocked ranges in the window (start inclusive, end exclusive, never who booked) and the property’s rules:
min_nights,max_nights;closed_arrival_days(0 = Monday to 6 = Sunday);advance_days,notice_hours;available_from,available_to;check_in_time,check_out_time.
Up to 400 days per call; the default window is the year ahead. The answer is cached briefly.
2. A quote
GET /api/v1/listings/{slug}/quote?check_in=…&check_out=…&guests=N gives the price of a stay before the visitor asks for it: each night’s price, every fee line (such as a tourism fee), the deposit and the total, as decimal strings in the company’s currency.
Dates the property cannot take answer 400 with a problem code (min_nights, arrival_day, notice, advance, unavailable, …) so the form can say why.
3. The booking request
POST /api/v1/bookings is the request itself, from the visitor’s browser like an enquiry: the same publishable key, origin, consent, challenge and hidden website rules as lead forms.
Fields: listing, check_in, check_out, guests, name, email, phone, message, language, consent, consent_version.
Dates another stay holds no longer refuse the request: it is accepted (201) with dates_taken: true, holds nothing, and the company answers it with other properties or a refusal. Every other rule (guests, minimum nights, notice, season) still answers 400 with its message, so the form can show it.
The answer gives the booking reference, dates_taken and the stay address: the guest’s own page on the company’s host, where the status, the quote and later the payment live.
What happens next
- The dates are held for the company’s hold period while staff confirm (a request for taken dates holds nothing until they are free).
- Nothing is charged at request. The guest pays after the company confirms, within the property’s payment window, from the stay page and the confirmation email.
- The website never collects payment details and never asks for identity documents: those are refused as in lead forms.
Keeping a calendar in step
Webhooks booking.requested, booking.confirmed, booking.paid and booking.cancelled carry the booking id, reference and listing id only, so a website can refresh its calendar without ever holding guest data. See Webhooks.
The guest space
Guests who want to see their stays, pay, or come back later sign in to the company’s guest space, which can be embedded in the website.