Calendar Data Guide for Price Recommendations
The Calendar Prices calendar input supplies evidence about bookings and availability. It does not choose which dates the API returns. Missing dates mean unknown, not available.
Map your inventory explicitly
| Status | Meaning to the pricing engine | Important consequence |
|---|---|---|
| available | Known sellable night | Eligible for calendar-dependent rules if their other conditions hold |
| reserved | Known booked night | Counts toward occupancy and can anchor an adjacent-day search |
| blocked | Known unavailable night outside sellable inventory | Excluded from the occupancy denominator; can bound a gap but interrupts adjacent searches |
| Omitted date | Unknown | Does not become vacant inventory; may prevent a rule from being evaluated |
Map statuses from your property-management or booking system deliberately. Do not turn every missing record into an available night.
A complete calendar fragment
Illustrative calendar: June 12–17, 2026. Calculation date June 13; $200 per night after model effects.
Use the diagram to distinguish unknown dates from known available inventory. The “Missing boundary” scenario has the same visible available nights, but does not provide enough evidence to price the two-night gap with a gap rule.
Gap-day, adjacent-day, and occupancy-pacing rules need calendar.
Each row requires a unique date and a status: available, reserved, or
blocked. For this historical illustration, assume today is June 13, 2026:
{
"calendar": [
{"date": "2026-06-12", "status": "reserved", "reservation_id": "booking-a"},
{"date": "2026-06-13", "status": "available", "price": 240, "min_stay": 1,
"check_in_allowed": true, "check_out_allowed": true},
{"date": "2026-06-14", "status": "reserved", "reservation_id": "booking-b"},
{"date": "2026-06-15", "status": "available"},
{"date": "2026-06-16", "status": "available"},
{"date": "2026-06-17", "status": "reserved", "reservation_id": "booking-c"}
]
}
This creates a one-night gap on June 13 and a two-night gap on June 15–16. Use your current dates in a real request. Send up to 1,000 rows; order does not matter. Missing dates mean unknown, not available.
Optional min_stay (1–365), check_in_allowed, and check_out_allowed
help test whether a gap is bookable when no corresponding custom stay rule
is set; defaults are one night and both permissions true. price must be
positive in the request currency but does not affect calculations.
reservation_id must be nonblank and is allowed only on reserved or blocked
rows; it is not currently used by pricing rules.
Send enough surrounding dates
A gap needs known boundaries on both sides. An adjacent-day search needs continuous known evidence along the direction it checks. A reservation just before today can help establish the boundary for an available night starting today, as in this historical example.
Only send facts you know. Turning an unknown night into “available” to eliminate a warning changes the meaning of the request.
Separate input and output horizons
Calendar Prices calculates from the property's current local date. Omitted or null start_date and end_date return the full one- to two-year calendar; explicit inclusive boundaries select a window of that output. The availability calendar does not select output dates, and the output window does not limit which calendar rows are used. A six-row input can still leave calendar-dependent rules unevaluable on many dates.
start_date and after end_date when needed by gap, adjacent-day or occupancy rules: the night before your window decides whether its first night is a gap. The output boundaries do not trim evidence or change calculations. coverage identifies the calculation date, the returned range and the available end date; warnings describe the full calculated horizon. See the date-boundary rules.The response includes recommended prices for reserved and blocked nights too. Filter and recheck current availability in your own publishing workflow; do not publish every returned row simply because it has a price.
Restrictions are inputs, not an echo contract
Calendar-row stay restrictions help gap eligibility when corresponding custom stay rules are absent. They are not automatically copied into output rows. Custom stay rules take precedence for their respective restriction and cause the configured fields to appear in recommendations.
The optional calendar price is validated but does not currently affect pricing. A reservation ID is accepted on reserved or blocked rows but is not currently used by pricing rules. Do not depend on either field to create a pricing effect.