Availability extension (<ns>.lodging.availability)
UCP's charter lists availability and rate fetching as future work. This extension returns provisional offers: what a booking session would cost right now. The authoritative price is always the one a UCP booking session returns, and it may differ (UCP's totals_changed warning).
Request (availability-request.json)
{ property_id, stay_dates, occupancy, rooms? }. property_id is the producer-scoped id from the manifest.
Response (availability-response.json)
{ property_id, offers[], source, fetched_at, expires_at }.
Offer
| Field | Meaning |
|---|---|
offer_id | Opaque id |
accommodation_type, rate_plan | { id, title, description? }; their ids are what UCP Create Booking Session takes |
ucp_stay_id | Optional pre-composed UCP stay.id |
stay_dates, occupancy, rooms, currency | As requested |
totals[] | subtotal, tax, fee, discount, total, each with display_text, amount and optional collected (prepaid / at_property) and lines[] (per night). Exactly one subtotal and one total; at least one tax or fee entry; non-total entries sum to the total |
payment_schedule[] | immediate, deferred (with due_at) or at_property amounts summing to the total |
cancellation | Machine-readable schedule (below) |
provisional | Always true |
source, fetched_at, expires_at | Provenance and freshness |
Cancellation schedule
{ refundability, rules[{ before, penalty_amount }], final_penalty_amount, description }. Cancelling at time *t* costs the penalty_amount of the first rule whose before is later than *t*, otherwise final_penalty_amount. Amounts are absolute, in the offer currency, so an agent never interprets "one night" or "50 %". Penalties never decrease as arrival approaches. refundable means free to cancel now; non_refundable means the full total is always due.
This is the field UCP's draft leaves as free text (see spec/upstream/ucp-proposal-search-availability.md).