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 TypeDescription
mManual block.
rReserved date.
bBooked by a reservation.
bdThe calendar date is blocked by default.
srSmart calendar rule block.
ablBlocked as a result of the listing having reached its annual booking limit.
aAn allotment block (this appears on a multi-unit and its units only).
bwBlocked by the booking window (i.e. no booking window for that calendar date).
oBlocked by an owner's reservation.
ptPreparation time block.
icAn iCal imported event from an external calendar
anAdvance 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 blocks and blockRefsarray and by cta/ctd. status and allotment will generally correlate with the blocks.

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"
}