check_property_availability

com.bluepillow/hotels · Verify this server

Live availability and per-operator quote for a specific property over a specific stay window. Performs a live date-aware lookup against the BluePillow search layer, returns date-specific prices, rooms-left scarcity signals, breakfast-included and refundable flags, and a per-operator deep link to complete the booking. Useful when the user has specific dates in mind for a property they already identified — typically via `search_stays` or `get_property_details`. The complementary `get_property_details` tool answers "what is this property like" with static facts; this tool answers "can I book it for these dates at what price" with live, date-specific data. Required input: `property_id` (the `id` from a `search_stays` result, opaque string starting with `prop_`), `dates` (check_in + check_out, ISO 8601), and `guests` (adults / children / infants composition). Without these the live lookup cannot proceed. Natural-language date references — "tonight", "this weekend", "next weekend", "the weekend of July 4", "Memorial Day weekend", "long weekend in May" — translate to concrete check_in / check_out values at the call site; concrete ISO dates also work. check_in is a date in the real-time calendar that is today or later; past values are rejected at the API boundary. `user_country`, `currency`, and `language` carry the **user's** locale, not the property's. Prices are returned in `currency` if set, else derived from `user_country`, else **USD** — pass `user_country` and/or `currency` whenever you know the user's location/currency so the quote matches what they'll pay; don't rely on the USD default. `user_country` and `language` also localize the `web_url` booking link. Response shape: - `availability_status` — `available`, `unavailable`, or `unknown`. Available means rooms confirmed at the operator level for the requested window; quote freely. Unavailable means no rooms for these dates — surface that explicitly to the user with a suggestion of alternate dates (there is no price for these dates). - `offers[]` — per-operator quotes. Each carries `amount` (total stay), `amount_per_night` (per-night), `currency`, `breakfast_included`, `refundable`, `rooms_left`, and `deeplink_url`. `offers[0]` is the best value for money as Blue Pillow ranks it: price weighed against what is included (breakfast, free cancellation) and the operator's historical reliability, with a small commercial component. It is not necessarily the cheapest — the full per-operator list is always in `offers[]`, and `sort=price_asc` gives pure price order. Each `deeplink_url` is a **BluePillow tracked-redirect URL** (bluepillow.com/…) that records the click and forwards the user to the operator's booking page — pass it verbatim, never reconstruct it or replace it with a raw OTA link. - `price` — mirror of `offers[0]` for callers that just want the curated headline. `null` when unavailable (no price for these dates). Per-night vs total — `amount_per_night` is **per-night**; `amount` on each offer is the **total** for the requested stay. Phrasings like *"€X/night via Booking, breakfast included, €Y total"* are unambiguous; bare numbers without a unit ("€192") get misread. Scarcity signals: low `rooms_left` values (1-3) are useful cues — "1 room left at €X on Booking" reads naturally. Free cancellation (`refundable=true`) and breakfast-included are decision factors worth surfacing proactively when present on some offers but not others. When all results across operators are `unavailable`, that's the signal to say so explicitly to the user and offer to widen the dates or look at alternatives. For final booking confirmation, hand the user the corresponding `deeplink_url` (or the property's `web_url`) — booking URLs are not reconstructed by hand.