Calendar Block Types
How to read and understand calendar blocks.
Overview
There are many events and actions that can lead to a calendar date when a property becomes unavailable. This guide explains each type of block and the closed-to arrival/departure restrictions.
Available Endpoints
Types of Blocks
When a date is unavailable or booked or reserved, the relevant block type value will change to true. Here is what it looks like when a date has a reservation. Note that block type r is true.
| Block Type | Description |
|---|---|
m | Manual block. |
r | Reserved date. |
b | Booked by a reservation. |
bd | The calendar date is blocked by default. |
sr | Smart calendar rule block. |
abl | Blocked as a result of the listing having reached its annual booking limit. |
a | An allotment block (this appears on a multi-unit and its units only). |
bw | Blocked by the booking window (i.e. no booking window for that calendar date). |
o | Blocked by an owner's reservation. |
pt | Preparation time block. |
ic | An iCal imported event from an external calendar |
an | Advance notice. |
Blocks are also included in the listing.calendar.updated webhook payload.
Example
Request
curl 'https://open-api.guesty.com/v1/availability-pricing/api/calendar/listings/62e17bddae108b003b1f87d7?startDate=2023-06-14&endDate=2023-06-15&includeAllotment=true' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {accessToken}'
const myHeaders = new Headers();
myHeaders.append("accept", "application/json");
myHeaders.append("Authorization", "Bearer {accessToken}");
const requestOptions = {
method: "GET",
headers: myHeaders,
redirect: "manual"
};
fetch("https://open-api.guesty.com/v1/availability-pricing/api/calendar/listings/62e17bddae108b003b1f87d7?startDate=2023-06-14&endDate=2023-06-15&includeAllotment=true", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
const myHeaders = new Headers();
myHeaders.append("accept", "application/json");
myHeaders.append("Authorization", "Bearer {accessToken}");
const requestOptions = {
method: "GET",
headers: myHeaders,
redirect: "manual"
};
fetch("https://open-api.guesty.com/v1/availability-pricing/api/calendar/listings/62e17bddae108b003b1f87d7?startDate=2023-06-14&endDate=2023-06-15&includeAllotment=true", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
import http.client
conn = http.client.HTTPSConnection("open-api.guesty.com")
payload = ''
headers = {
'accept': 'application/json',
'Authorization': 'Bearer {accessToken}'
}
conn.request("GET", "/v1/availability-pricing/api/calendar/listings/62e17bddae108b003b1f87d7?startDate=2023-06-14&endDate=2023-06-15&includeAllotment=true", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
Response
Every response returned for calendar date data includes a blocks object. Nested inside the object is a list of possible block types. You can see that June 14 has no blocks, whereas June 15 shows a booked date with a reservation block and an advanced notice block applied. The blockRefs array provides additional details on the object or event blocking the date.
{
"status": 200,
"data": {
"days": [
{
"date": "2023-06-14",
"listingId": "62e17bddae108b003b1f87d7",
"currency": "USD",
"price": 50,
"isBasePrice": true,
"minNights": 1,
"isBaseMinNights": true,
"status": "available",
"blocks": {
"m": false,
"r": false,
"b": false,
"bd": false,
"sr": false,
"abl": false,
"a": false,
"bw": false,
"o": false,
"pt": false
},
"blockRefs": [],
"cta": false,
"ctd": false,
"requestToBook": false
},
{
"date": "2023-06-15",
"listingId": "62e17bddae108b003b1f87d7",
"currency": "USD",
"price": 70,
"isBasePrice": false,
"minNights": 1,
"isBaseMinNights": true,
"status": "booked",
"blocks": {
"m": false,
"r": false,
"b": true,
"bd": false,
"sr": false,
"abl": false,
"a": false,
"bw": false,
"o": false,
"pt": false
},
"blockRefs": [
{
"_id": "6489795c0f574e002ac0fa80",
"reservation": {
"listing": {
"timezone": "America/Los_Angeles",
"defaultCheckInTime": "15:00",
"nickname": "Lemon"
},
"money": {
"currency": "USD",
"hostPayout": 288.32,
"totalPaid": 0,
"balanceDue": 288.32
},
"guest": {
"fullName": "Diana Walker"
},
"integration": {
"platform": "direct"
},
"numberOfGuests": {
"numberOfChildren": 0,
"numberOfInfants": 0,
"numberOfAdults": 1
},
"_id": "648979033a415440ce05e704",
"createdAt": "2023-06-14T08:23:31.324Z",
"createdBy": "[email protected]",
"inquiryId": "648978e969e307eb7906883e",
"accountId": "62a8a2be2e53190032102a6e",
"checkInDateLocalized": "2023-06-15",
"checkOutDateLocalized": "2023-06-16",
"status": "confirmed",
"confirmationCode": "GY-F8CPkZZg",
"guestsCount": 1,
"nightsCount": 1,
"reservedExpiresAt": null,
"source": "manual",
"listingId": "62e17bddae108b003b1f87d7",
"checkIn": "2023-06-15T15:00:00+00:00",
"checkOut": "2023-06-16T10:00:00+00:00"
},
"listingId": "62e17bddae108b003b1f87d7",
"startDate": "2023-06-15T00:00:00.000Z",
"endDate": "2023-06-15T00:00:00.000Z",
"type": "b",
"createdBy": "[email protected]",
"reservationId": "648979033a415440ce05e704",
"createdAt": "2023-06-14T08:25:00.779Z"
}
],
"reservationId": "648979033a415440ce05e704",
"reservation": {
"listing": {
"timezone": "America/Los_Angeles",
"defaultCheckInTime": "15:00",
"nickname": "Lemon"
},
"money": {
"currency": "USD",
"hostPayout": 288.32,
"totalPaid": 0,
"balanceDue": 288.32
},
"guest": {
"fullName": "Diana Walker"
},
"integration": {
"platform": "direct"
},
"numberOfGuests": {
"numberOfChildren": 0,
"numberOfInfants": 0,
"numberOfAdults": 1
},
"_id": "648979033a415440ce05e704",
"createdAt": "2023-06-14T08:23:31.324Z",
"createdBy": "[email protected]",
"inquiryId": "648978e969e307eb7906883e",
"accountId": "62a8a2be2e53190032102a6e",
"checkInDateLocalized": "2023-06-15",
"checkOutDateLocalized": "2023-06-16",
"status": "confirmed",
"confirmationCode": "GY-F8CPkZZg",
"guestsCount": 1,
"nightsCount": 1,
"reservedExpiresAt": null,
"source": "manual",
"listingId": "62e17bddae108b003b1f87d7",
"checkIn": "2023-06-15T15:00:00+00:00",
"checkOut": "2023-06-16T10:00:00+00:00"
},
"cta": false,
"ctd": false,
"requestToBook": false,
"notDefaultAvailability": true
}
]
},
"message": "OK"
}
Closed to Arrival (CTA)/Closed to Departure(CTD)
CTA is a rate strategy rule that, when enabled, prevents reservations from being booked starting on that day. Likewise, CTD is the rate strategy rule that, when enabled, prevents a booking's checkout date from being set on a specific day.
When these rules are in effect, the relevant calendar dates will remain bookable but not as check-in or check-out dates. This will sync with and be honored by the booking channels.
Note
A date can be unavailable for multiple reasons that can be identified by the
blocksandblockRefsarray and bycta/ctd.statusandallotmentwill generally correlate with theblocks.
Payload Example
The payload displays that 29 March 2023 is closed for departures ("ctd": true) and specifies the rate strategy rule being enforced in the rulesApplied array. While this date can still be booked, it cannot be selected as the check-out date.
{
"status": 200,
"data": {
"days": [
{
"date": "2024-03-29",
"listingId": "64f03f9094d741004fda977d",
"currency": "USD",
"price": 300,
"isBasePrice": true,
"minNights": 2,
"isBaseMinNights": true,
"status": "available",
"blocks": {
"m": false,
"r": false,
"b": false,
"bd": false,
"sr": false,
"abl": false,
"a": false,
"bw": false,
"o": false,
"pt": false
},
"blockRefs": [],
"cta": false,
"ctd": true,
"requestToBook": false,
"rulesApplied": [
{
"rule": "repeated days (friday)",
"cta": false,
"ctd": true
}
]
}
]
},
"message": "OK"
}
Updated about 1 year ago