Overview

The Retrieve Unit Calendars endpoint returns day-level availability data and stay-rule logic for one or more units over a defined date range. This includes overall availability status, arrival and departure restrictions, minimum and maximum stay requirements, booking fences, gap rules, and allocation-on-arrival behavior where applicable.

This endpoint represents the authoritative source for determining whether a unit can be booked for a given set of dates and under what conditions.

Calendar results reflect a composite evaluation of multiple supplier-defined rule layers and operational inputs, including availability rules, active reservation activity (including external calendar syncs), and channel-specific constraints when a channel context is supplied.

This endpoint is commonly used to:

Power availability searches and date-picker logic
Render availability calendars in partner-facing UIs
Validate arrival and departure dates prior to quoting
Enforce stay-length rules before reservation creation
Re-evaluate availability during reservation modifications or re-quotes

By design, this endpoint should be treated as validation logic, not just display data. Correct interpretation at this stage is critical to preventing invalid quotes, rejected reservations, and downstream booking failures.

Related Supplier Configuration (Optional Context)

Availability and calendar behavior returned by this endpoint is influenced by reservation and calendar configuration within the CiiRUS system, including supplier-defined restrictions and reservation activity.

Default arrival and departure behavior
- Setting default check-in/out times
Reservation rules and behavior
- Configuring general reservation settings
- Add a blackout date
Reservation activity impacting availability
- Add a new reservation
- Cancel a reservation

Endpoints Available

Method	Endpoint	Description
GET	v2024.07.31/unit_calendars	Returns availability calendar and configuration for units in the inventory.
GET	v2024.07.31/unit_calendars/{unit_id}	Returns the availability calendar and configuration for a specific unit.

Path Parameters

Path Parameter	Required / Optional	Description
{unit_id}	Required	Unique identifier for the unit.

Query String Parameters

Parameter	Required / Optional	Description	Data Type
page	Optional	The page number to display (default: 1).	int
page_size	Optional	Limits the number of returned results (default: 25).	int
last_unit_update_date	Optional	Returns units modified after the specified date.	date-time
last_reservation_update_date	Optional	Returns units that have received a booking or calendar sync after the specified date.	date-time
last_agent_module_property_update_date	Optional	Returns units with modified agent module property configuration after the specified date.	date-time
last_agent_module_agent_update_date	Optional	Returns units with modified agent module agent configuration after the specified date.	date-time
unit_id	Optional	Filter results to a specific unit ID.	int
unit_ids	Optional	Filter results to multiple unit IDs.	array[int]
management_company_user_id	Optional	Filter results to a specific supplier.	int
management_company_user_ids	Optional	Filter results to multiple suppliers.	array[int]
enabled	Optional	Return only enabled or disabled units.	boolean
deleted	Optional	Return only deleted or non-deleted units.	boolean
display_on_website	Optional	Return only units enabled for the website.	boolean
allocation_on_arrival	Optional	Include allocation-on-arrival availability data where applicable.	boolean
allocation_on_arrival_unit	Optional	Return only representative units within allocation-on-arrival groups.	boolean
fallback_rates	Optional	Determines fallback behavior when nightly rates are missing. Defaults to `fallback_max_value_rate_plus_guards`.	string (enum)
start	Required	Start date for retrieving calendar availability.	date
end	Required	End date for retrieving calendar availability.	date
reservation_id	Optional	Reservation ID used to evaluate availability in the context of a modification.	int
allocated_reservations	Optional	List of unallocated reservation IDs to virtually allocate for availability checks.	array[int]
category_to_ignore	Optional	Booking category to ignore when calculating availability.	boolean
channel	Optional	Restrict results to a specific channel’s configuration context. Leave empty for the default/general data.	string (enum)
listing_id	Optional	Lookup a unit by its channel-specific listing ID.	string

Allowed values for fallback_rates:
- explicitly_in_date_range_only – Only return rates explicitly configured in the requested range (missing days may effectively result in gaps or downstream inability to quote).
- fallback_max_value_rate – Will fill any missing rates in the selected date range with the highest configured rate value.
- fallback_max_value_rate_plus_guards – Will also fill any missing rates using the highest configured rate value in the selected date range while also applying any configured rate guards (e.g., min/max constraints).
Allowed values for channel:
- all
- bdc
- vrbo
- airbnb

📘
Note
While fallback_rates is primarily used during pricing evaluation, it may influence availability calculations when nightly rate data is required to determine valid stay combinations across the requested date range.

Response Definition

Response Item	Description	Data Type
`"unit_calendars"`	The primary result set. Each array element represents a single unit’s evaluated calendar for the requested date range, including day-by-day availability and the rules that control when and how it can be booked.	array
`"paging"`	Paging metadata used to navigate through large result sets when multiple units are returned.	object

`"unit_calendars"` Object

Response Item	Description	Data Type
`"unit_id"`	The unique unit identifier the calendar data belongs to. This is the same `unit_id` used across the platform (`/units`, `/unit_details`, `/unit_images`, `/unit_amenities`, `/unit_quotes`, etc.). You should treat this as the canonical key for joining calendar data with other unit resources.	int
`"management_company_user_id"`	The supplier (property manager) identifier that owns or manages this unit. This is especially important in multi-supplier inventories because units are not globally “owned” by the partner—access is scoped by supplier relationships and enabled connections.	int
`"start_date"`	The effective start boundary (date + time) of the returned calendar window for this unit. This value is not just the raw `start` you submitted—it reflects how the system defines the operational boundary of the calendar, including supplier check-in/checkout timing logic.	date-time
`"end_date"`	The effective end boundary (date + time) of the returned calendar window for this unit. Like `"start_date"`, this includes time-of-day and represents the operational end of the returned range based on how availability is computed for the unit.	date-time
`"days"`	An array of evaluated day records for the requested date range. Each entry represents what the system believes is bookable/unbookable for that date, and includes both the high-level outcome (`"availability"`) and the constraint data required to validate arrivals, departures, and stay lengths.	array
`"allocation_on_arrival"`	An optional object returned for units participating in Allocation-on-Arrival (AOA) group inventory. In these cases, availability may be evaluated at the group level rather than strictly at the individual unit level. This is typically used for “like-for-like” units where the actual assigned unit may be decided later.	object
`"error"`	Optional error object returned when this unit cannot produce a usable calendar under the current integration context. The unit may still be included in the response, but should generally be treated as not actionable for booking flows unless the issue is resolved.	object

`"days"` Object

Response Item	Description	Data Type
`"date"`	The calendar date this record applies to (local to the unit’s operational calendar). This is the day you would display on a calendar UI and the day you would evaluate as a candidate check-in/check-out date.	date
`"availability"`	The top-level “can I book the unit on this date?” outcome. Partners should treat this as the primary availability indicator when building search results and calendar displays. Availability is computed using supplier rules, reservations, blackout rules, fences, and other constraints. See valid availability values.	string
`"availability_type"`	A more specific reason explaining the availability outcome. This is useful for internal diagnostics and for building “why can’t I book this?” messaging (for example: blocked by fence, blocked by blackout, blocked by booking category). This is not purely decorative—different types may imply different next actions. See valid availability_type values.	string
`"closed_to_arrival"`	Indicates whether a reservation is allowed to start on this date. If `true`, the guest cannot check in on this day even if surrounding dates might be available. This is commonly used for operational changeover rules, fixed turnover days, or to prevent split-week patterns.	boolean
`"closed_to_departure"`	Indicates whether a reservation is allowed to end on this date. If true, the guest cannot check out on this day. This is often paired with fixed changeover policies and can be critical when validating modifications (a stay might be “available” but still ineligible to end on certain dates).	boolean
`"minimum_nights"`	The minimum stay length (nights) required if the guest’s check-in date is this `"date"`. This value is the “effective rule” for that day and may reflect global defaults, seasonal overrides, blackout constraints, or channel-scoped limitations. Use this during pre-book validation before quoting.	int
`"maximum_nights"`	The maximum stay length (nights) allowed if the guest’s check-in date is this `"date"`. This matters for long-stay restrictions, owner blocks, seasonal limits, and operational rules. Some inventories may use very large values to represent no practical maximum.	int
`"settings"`	A nested object containing the underlying rule components that produced the effective constraints for this date—booking fence, gap rules, and allowed arrival/departure weekdays. This is the policy layer that supports the high-level fields like `"minimum_nights"` and `"closed_to_arrival"`.	object
`"stay_durations"`	An explicit list of allowed lengths of stay (nights) for reservations beginning on this `"date"`. When present and populated, this is the most precise representation of what the system will accept. Partners may use it to build UX features like allowed stay lengths dropdowns or to efficiently hard-filter out invalid stay patterns.	array[int]

`"settings"` Object

Response Item	Description	Data Type
`"booking_fence"`	Minimum lead time (in days) required to create a booking arriving on this date. For example, `2` means the booking must be made at least 2 days before arrival. This is commonly used to prevent last-minute same-day turnovers or allow operational prep time. A value of `0` indicates same-day booking is allowed.	int
`"gap_days"`	Minimum number of empty days required between reservations. This acts like a buffer rule—often for cleaning, inspections, or maintenance—and can render otherwise available nights effectively unbookable depending on surrounding reservations.	int
`"minimum_nights"`	The rule-derived minimum stay length for arrivals on this date. This often mirrors `"minimum_nights"` at the day level, but represents the value as part of the underlying settings bundle (useful for troubleshooting rule application).	int
`"maximum_nights"`	The rule-derived maximum stay length for arrivals on this date. Like minimum, this is the underlying settings value used to generate the effective constraints for the day.	int
`"arrival_days"`	List of weekdays on which guests are permitted to check in. If a weekday is not included, arrivals on that weekday should be treated as invalid even if there appears to be availability.	array[string]
`"departure_days"`	List of weekdays on which guests are permitted to check out. If a weekday is not included, departures on that weekday should be treated as invalid, especially for modification and rebooking logic.	array[string]

📘
How to Interpret Calendar Availability
Availabilirty in CiiRUS is rule-driven, not binary. A date may appear open but still be invalid for a specific booking pattern.
Partners must evaulate calendar data as a composed rule set, not individual fields.
Example Evaluation order:

Check "availability"

"available" → Potentially bookable (subject to rules)

"unavailable" → Not bookable under any conditions

Validate "closed_to_arrival" and "closed_to_departure"

"closed_to_arrival" = true → Cannot check in

"closed_to_departure" = true → Cannot check out

Validate stay length using "stay_durations" or "minimum_nights" and "maximum_nights"

If stay_durations is present, prefer it over calculating ranges.

Apply Allocation-on-Arrival logic if present

Proceed to quoting and booking

`"stay_durations"` Array

Response Item	Description	Data Type
(value)	A permitted stay length (in nights) for arrivals on the associated `"date"`. If a length is not listed here, it should be treated as invalid.	int

`"allocation_on_arrival"` Object

Response Item	Description	Data Type
`"availability"`	Availability status evaluated at the allocation group level. This represents whether the group has capacity, not whether a specific unit instance is guaranteed.	string
`"available_unit_count"`	Number of currently available units within the allocation group for the requested date range. This is the key capacity signal used when presenting AOA inventory availability.	string
`"change_over"`	Group-level changeover rule indicating how turnovers are handled (for example, same-day changeover policies or fixed turnover patterns).	string
`"max_stay"`	The maximum length of stay allowed when booking from the allocation group. Used to enforce consistent policy across the shared inventory pool.	string
`"min_prior_notify"`	The minimum lead time required before arrival when booking from the group, similar to a booking fence, but applied at the AOA group level.	string
`"min_stay"`	The minimum stay length enforced across the allocation group. This prevents booking patterns that would create operational inefficiencies across shared inventory.	string
`"stay_increment"`	The required increment (in nights) for valid stays within the group (for example, only 7-night increments). This is commonly used for weekly-only inventory or fixed-length stay models.	string

📘
Allocation-on-Arrival (AOA) Considerations
For AOA units:

Availability is evaluated at group level

A booking does not guarantee assignment of a specific unit

Avoid displaying unit-specific promises pre-assignment

`"error"` Object

Response Item	Description	Data Type
`"message"`	Informational error message explaining why calendar data could not be produced for this unit under the current request. When present, partners should generally exclude the unit from booking/quote flows until corrected.	string

`"paging"` Object

Response Item	Description	Data Type
`"next_page_url"`	A URL that can be used to retrieve the next page of supplier results, if additional pages exist.	string
`"previous_page_url"`	A URL that can be used to retrieve the previous page of supplier results, if applicable.	string
`"total_page_count"`	The total number of available pages for the current request.	int
`"page"`	The current page number being returned.	int
`"page_size"`	The number of records being included per page.	int

Sample Request

curl --location 'https://api.ciiruspartners.com/v2024.07.31/unit_calendars?page=1&page_size=25&enabled=true&start=2025-03-04&end=2026-03-03' \
--header 'Content-Type: application/json' \
--header 'authorization: Basic {APIUsername:APIPassword}'

Sample Response

{
    "unit_calendars": [
        {
            "unit_id": 104798,
            "management_company_user_id": 11006,
            "start_date": "2025-03-04T17:00:00",
            "end_date": "2026-03-03T12:00:00",
            "days": [
                {
                    "date": "2025-03-04",
                    "availability": "available",
                    "availability_type": "available",
                    "closed_to_arrival": false,
                    "closed_to_departure": false,
                    "minimum_nights": 2,
                    "maximum_nights": 1763,
                    "settings": {
                        "booking_fence": 0,
                        "gap_days": 0,
                        "minimum_nights": 2,
                        "maximum_nights": 1763,
                        "arrival_days": [
                            "monday",
                            "tuesday",
                            "wednesday",
                            "thursday",
                            "friday",
                            "saturday",
                            "sunday"
                        ],
                        "departure_days": [
                            "monday",
                            "tuesday",
                            "wednesday",
                            "thursday",
                            "friday",
                            "saturday",
                            "sunday"
                        ]
                    },
                    "stay_durations": [
                        2,
                        3,
                        4,
                        5,
                        6,
                        7,
                        8,
                        9,
                        10,
                        ...
                    ]
                },
                 {
            "unit_id": 0,
            "management_company_user_id": 0,
            "start_date": "0001-01-01T00:00:00",
            "end_date": "0001-01-01T00:00:00",
            "error": {
                "message": "{\"message\":\"Unit quote options could not be found.\"}"
            }
        }
    ],
    "paging": {
        "next_page_url": "https://api.ciiruspartners.com/v2024.07.31/unit_calendars?page=2&page_size=25&enabled=true&start=2025-03-04&end=2026-03-03",
        "total_page_count": 3,
        "page": 1,
        "page_size": 25
    }
}

Overview

Related Supplier Configuration (Optional Context)

Endpoints Available

Path Parameters

Query String Parameters

Note

Response Definition

"unit_calendars" Object

"days" Object

"settings" Object

How to Interpret Calendar Availability

"stay_durations" Array

"allocation_on_arrival" Object

Allocation-on-Arrival (AOA) Considerations

"error" Object

"paging" Object

Sample Request

Sample Response

`"unit_calendars"` Object

`"days"` Object

`"settings"` Object

`"stay_durations"` Array

`"allocation_on_arrival"` Object

`"error"` Object

`"paging"` Object