Calendar Block Types

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

Method	Endpoint
GET	/availability-pricing/api/calendar/listings/{id}
GET	/availability-pricing/api/calendar/listings

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