Calendar¶
| Endpoint | Method | Scope | Description |
|---|---|---|---|
/api/v1/listings/<id>/calendar/ |
GET | reservations:read |
Get calendar data for a listing |
Try it out
Explore parameters, schemas, and live requests in the Swagger UI.
Get Listing Calendar¶
Returns daily calendar data for a listing, including pricing, availability, and pricing factors. Filter by date range using filter[start-date] and filter[end-date] (defaults to today through today + 365 days).
Calendar price fields are returned in the currency configured for the user who owns the listing.
Availability Values¶
| Value | Description |
|---|---|
available |
The date is available to be booked |
booked |
The date has a corresponding reservation |
blocked |
The date is blocked off for a hold |
unavailable |
The date cannot be booked for an unknown reason |
Price Fields¶
| Field | Description |
|---|---|
price |
Beyond Pricing suggested price (shown in the BP dashboard) |
price-posted |
Last price posted to the channel/PMS |
effective-min-price |
Effective minimum price floor; the modeled price will not go below this |
effective-max-price |
Effective maximum price ceiling; the modeled price will not exceed this (null when unset) |
Tip
Use price-posted when you need the price that will actually be quoted if a booking is made. Fall back to price if price-posted is null.
Pricing Factors¶
Each calendar entry includes a factors array describing the individual components that shaped the modeled price (e.g. seasonality, day-of-week, events).
| Field | Description |
|---|---|
key |
Factor identifier (e.g. seasonality, dow, event) |
order |
Display/application order of the factor |
ratio |
Factor's contribution as a ratio (e.g. -0.19 means -19%) |
amount |
Factor's contribution to the modeled price, in the same currency units as price (e.g. -19 lowered the price by 19) |
reason |
Human-readable reason for the factor (e.g. event name), when available |
event-impact |
Event impact level (low, medium, high); only present for event factors |
Note
amount values do not necessarily sum to (price − base price). Minimum/maximum price limits and final rounding are applied between factors and are not attributed to any single factor, and factors whose effect rounds to less than 1 report 0.