Unit Rental
Returns day-level base rental rates and stay-rule configuration for units in the inventory
Overview
The Retrieve Unit Rental endpoint returns day-level base rental rate data and associated stay-rule configuration for one or more units over a defined date range. This includes nightly rate values, minimum and maximum stay requirements, arrival and departure restrictions, booking fences, gap rules, and rate-set evaluation metadata.
This endpoint represents the authoritative source for determining what a unit costs per night and under what stay conditions those rates apply for a given date range. While it does not return a full guest-facing price, it defines the pricing foundation used by downstream quoting and reservation workflows.
Rental results reflect a composed evaluation of supplier-defined rate sets, seasonal pricing rules, stay restrictions, and optional channel context when supplied. Returned values already reflect configured rate factors and markups, but do not represent a final quote.
This endpoint is commonly used for:
- Power nightly rate calendars and pricing previews
- Display base nightly pricing in search results
- Validate stay length rules prior to quoting
- Pre-check pricing feasibility before reservation creation
- Re-evaluate pricing during reservation modifications or re-quotes
By design, this endpoint should be treated as pricing configuration and validation data, not a finalized financial breakdown. Partners must use quoting endpoints to calculate taxes, fees, discounts, deposits, and totals.
Related Supplier Configuration (Optional Context)
Rental rate behavior returned by this endpoint is influenced by rate and reservation configuration within the CiiRUS system, including supplier-defined pricing, tax applicability, and online booking rules.
- Rate setup and assignment
- Tax applicability affecting rate interpretation
- Reservation settings impacting rate usability in booking flows
Endpoints Available
| Method | Endpoint | Description |
|---|---|---|
| GET | v2024.07.31/unit_rental | Returns rental rate configuration for units in the inventory. |
| GET | v2024.07.31/unit_rental/{unit_id} | Returns rental rate configuration for a specific unit in the inventory. |
Path Parameters
| Path Parameter | Required / Optional | Description |
|---|---|---|
| {unit_id} | Required | Unique Identifier for a unit in the inventory. |
Query String Parameters
| Parameter | Required / Optional | Description | Data Type |
|---|---|---|---|
| page | Optional | The page to be shown (defaults to 1). | int |
| page_size | Optional | Limits the number of returned results (defaults to 25). | int |
| last_unit_update_date | Optional | Only return units that have been modified after the specified date. | date-time |
| last_reservation_update_date | Optional | Only return units that have received a booking (their own or a calendar sync) after the specified date. | date-time |
| last_agent_module_property_update_date | Optional | Only return units that have had their agent module property configuration modified after the specified date. | date-time |
| last_agent_module_agent_update_date | Optional | Only return units that have had their agent module agent configuration modified after the specified date. | date-time |
| unit_id | Optional | Unique Identifier for Unit in Inventory | int |
| unit_ids | Optional | Unique Identifiers for Units in Inventory | array |
| management_company_user_id | Optional | Unique Identifier for Supplier | int |
| management_company_user_ids | Optional | Unique Identifiers for Suppliers | array |
| enabled | Optional | Use only enabled or disabled units. | boolean |
| deleted | Optional | Only show properties that are deleted or not deleted. | boolean |
| display_on_website | Optional | Only show properties that are enabled for the management company's website. | boolean |
| allocation_on_arrival | Optional | Return the allocation on arrival object. | boolean |
| allocation_on_arrival_unit | Optional | Return units that are the representative unit in their group. | boolean |
| start | Required | The desired start date for the rental rates. | date-time |
| end | Required | The desired end date for the rental rates. | date-time |
| maximum_future_days | Optional | Maximum future days for LOS. | int |
| fallback_rates | Optional | Determines fallback behavior when nightly rates are missing. Defaults to fallback_max_value_rate_plus_guards. | string |
| minimum_value_guard | Optional | Minimum value guard used when applying fallback rate logic. This constrains the resulting filled values to not fall below a configured minimum threshold during fallback evaluation. This does not “invent” pricing; it controls how fallback values are bounded when fallback mode is enabled. | int |
| maximum_value_guard | Optional | Maximum value guard used when applying fallback rate logic. This constrains the resulting filled values to not exceed a configured maximum threshold during fallback evaluation. | int |
| channel | Optional | Restrict results to a specific channel context. Leave empty for general/default behavior. | 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:allbdcvrboairbnb
Response Definition
| Response Item | Description | Data Type |
|---|---|---|
"unit_rental" | The primary result set. Each array element represents the evaluated rental-rate output for a single unit over the requested date range. A unit may return either a "rental" object (successful evaluation) or an "error" object (non-actionable). | array |
"paging" | Paging metadata used to navigate through large result sets when multiple units are returned. | object |
"unit_rental" Object
"unit_rental" Object| Response Item | Description | Data Type |
|---|---|---|
"unit_id" | The unique identifier for the unit this rental evaluation applies to. This is the same canonical unit identifier used across the platform (/units, /unit_details, /unit_calendars, /unit_quotes, etc.) and should be used as the primary join key when correlating data across endpoints. | int |
"management_company_user_id" | The unique identifier of the supplier (property manager) that owns or manages the unit. This is critical in multi-supplier integrations, as unit visibility and pricing are scoped by enabled supplier relationships. | int |
"rental" | The evaluated rental-rate object for the unit and date range. This object is only present when pricing can be successfully resolved under the current integration context. | object |
"error" | An informational error object returned when rental rates cannot be produced for this unit (for example, when the supplier or partner has not enabled the property connection). When present, the unit should generally be excluded from pricing and booking flows. | object |
NoteIn multi-unit queries it is normal to receive a mixed array where some units have
"rental"while others have"error". Partner integrations should handle partial success cleanly.
"rental" Object
"rental" ObjectResponse Item | Description | Data Type |
|---|---|---|
| Unique identifier of the rate set used to generate the returned pricing for this unit and date range. A rate set represents the supplier’s configured pricing “source” assigned to the unit (for example: seasonal bands, default pricing schedules, or other rate structures). | int |
| Start date (inclusive) of the pricing window returned within the | string |
| End date (inclusive) of the pricing window returned within the | string |
| ISO 4217 currency code for all monetary values represented in the See valid iso_currency values. | string |
| Optional currency exchange metadata, when applicable. This array is typically empty in partner-facing scenarios, but is included for completeness when the system needs to express converted currency context. Partners should not assume it is populated. | array |
| Array of nightly rental rate values, one entry per day starting at | array |
Array of rule context objects aligned day-for-day with the | array | |
| An array of tax identifiers/names indicating which taxes apply to the nightly rental rates returned in | array |
Rate-set configuration flags and multipliers that describe how the returned base rates are adjusted or interpreted within the integration context (for example: markups/factors, whether rates include tax, whether mandatory extras should be included downstream, and whether LOS pricing behavior is enabled). Partners should treat this as the “pricing policy layer” that helps explain how nightly rates are expected to be consumed. | object |
The
"rates"array represents nightly rate values only. It does not represent a final quote total and does not include required fees, mandatory extras, taxes, discounts, or channel fee logic. For bookable totals and accurate guest-facing pricing, use the quoting flow (for example:/unit_quotes).
"settings" Object
"settings" Object| Response Item | Description | Data Type |
|---|---|---|
"booking_fence" | The minimum lead time (in days) required to create a booking arriving on this date. A value of 0 means same-day bookings are allowed by this rule layer. This is commonly used to prevent last-minute turnovers or to allow operational conflicts to be resolved. | int |
"gap_days" | Required minimum number of vacant days between adjacent reservations for this date context. This acts as a buffer rule (cleaning, inspections, maintenance) and can make nights effectively unbookable depending on surrounding reservations. A value of 0 means no gap requirement under this rule layer. | int |
"minimum_nights" | Minimum length of stay (in nights) allowed for reservations that begin on this date. This is a rule constraint aligned to rate applicability (often seasonal or policy-driven). Partners should validate this alongside calendar rules when deciding if a stay pattern is valid. | int |
"maximum_nights" | Maximum length of stay (in nights) allowed for reservations that begin on this date. A value of 0 is commonly used to represent “no enforced maximum” under this rule layer. Partners should not assume a maximum exists unless this field is non-zero. | int |
"arrival_days" | List of weekdays on which a reservation is allowed to start (check in) under this rule layer. If a weekday is not present, arrivals on that weekday should be treated as invalid even if a nightly rate exists for that date. | array[string] |
"departure_days" | List of weekdays on which a reservation is allowed to end (check out) under this rule layer. If a weekday is not present, departures on that weekday should be treated as invalid, especially during modification or re-quote workflows. | array[string] |
"season_name" | Supplier-defined season label applied to this date’s pricing/rule context (for example: “High Season”, “Holiday”, etc.). This is intended for display and diagnostics (helpful for explaining seasonal pricing shifts). It may be blank, and some inventories may use placeholder values depending on configuration. | string |
NoteThere will be multiple
"settings"objects in the array. The"settings"array aligns 1:1 with `"rates" by index over the requested date range.
"rate_set_details" Object
"rate_set_details" Object| Response Item | Description | Data Type |
|---|---|---|
"agent_daily_markup" | Flat per-night markup applied at the agent/integration level, expressed in currency units (not fixed-point). A value of 0.00 indicates no flat daily markup is applied. This can be used as an additional adjustment layer on top of base nightly rates when applicable. | decimal |
"agent_rate_factor" | Multiplicative factor applied at the agent/integration level to adjust base nightly rates. A value of 1.00 indicates no adjustment. Partners should treat this as a policy multiplier, not a discount, unless their business logic explicitly interprets it as such. | decimal |
"management_company_rate_factor" | Multiplicative factor applied by the supplier (management company) to the underlying base rate configuration. A value of 1.00 indicates no adjustment. This is commonly used for operational pricing adjustments without redefining every rate value. | decimal |
"includes_tax" | Indicates whether the rental rate values are configured as tax-inclusive (true) or tax-exclusive (false). Even when true, partners should still use quoting for final totals, as tax treatment can vary based on reservation composition and configured taxable items. | boolean |
"ciirus_percentage" | Percentage retained by CiiRUS when applicable. This is typically 0.00 in partner-facing contexts. Partners should treat this as informational and not use it as a pricing input unless explicitly instructed by CiiRUS. | decimal |
"include_mandatory_extras" | Indicates whether mandatory extras are expected to be included in downstream pricing flows. This does not mean extras are already included in "rates"—it signals how mandatory extras should be treated during quote composition. Partners should follow quote responses as the authoritative source for fee/extras application. | boolean |
"days_in_month" | Number of days in the month used by the system for certain prorated or monthly-rate behaviors within the rate configuration. This is typically relevant for long-stay or monthly-rate pricing logic. | int |
"allow_length_of_stay" | Indicates whether length-of-stay (LOS) pricing logic is enabled for the associated rate set. When true, the nightly rate returned for a day may reflect LOS-driven pricing configuration rather than a simple flat nightly value. Partners should treat this as a signal that LOS behavior may apply when evaluating multi-night stays. | boolean |
If a 0 appears in the
"rates"array, this was defined by the Property Manager. Please contact the PM and request they populate this data. As long as a rateband has been defined (even as 0) for the date period of a reservation and the user has set the property to be bookable online, the property can be booked and the quote will be calculated based on the defined rates.
"error" Object
"error" Object| Response Item | Description | Data Type |
|---|---|---|
"error" | Human-readable explanation describing why rental pricing could not be returned for this unit under the current request. Common causes include missing rate bands for the unit, or the unit not being enabled/authorized for the current partner/supplier connection context. Partners should treat this as informational and exclude the unit from pricing/booking flows until resolved. | string |
"paging" Object
"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_rental?page=1&page_size=25&management_company_user_id=42330&start=2026-01-13&end=2026-01-20' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {APIUsername:APIPassword}' \Sample Response
{
"unit_rental": [
{
"unit_id": 219264,
"management_company_user_id": 42330,
"rental": {
"rate_set_id": 75114,
"start": "2026-01-13",
"end": "2026-01-20",
"iso_currency": "USD",
"currency_exchanges": [],
"rates": [
1000000000,
1000000000,
1000000000,
1000000000,
1000000000,
1000000000,
1000000000
],
"settings": [
{
"booking_fence": 0,
"gap_days": 0,
"minimum_nights": 1,
"maximum_nights": 0,
"arrival_days": [
"monday",
"tuesday",
"wednesday",
"thursday",
"friday",
"saturday",
"sunday"
],
"departure_days": [
"monday",
"tuesday",
"wednesday",
"thursday",
"friday",
"saturday",
"sunday"
],
"season_name": ""
},
{
"booking_fence": 0,
"gap_days": 0,
"minimum_nights": 1,
"maximum_nights": 0,
"arrival_days": [
"monday",
"tuesday",
"wednesday",
"thursday",
"friday",
"saturday",
"sunday"
],
"departure_days": [
"monday",
"tuesday",
"wednesday",
"thursday",
"friday",
"saturday",
"sunday"
],
"season_name": ""
},
{
"booking_fence": 0,
"gap_days": 0,
"minimum_nights": 1,
"maximum_nights": 0,
"arrival_days": [
"monday",
"tuesday",
"wednesday",
"thursday",
"friday",
"saturday",
"sunday"
],
"departure_days": [
"monday",
"tuesday",
"wednesday",
"thursday",
"friday",
"saturday",
"sunday"
],
"season_name": ""
},
{
"booking_fence": 0,
"gap_days": 0,
"minimum_nights": 1,
"maximum_nights": 0,
"arrival_days": [
"monday",
"tuesday",
"wednesday",
"thursday",
"friday",
"saturday",
"sunday"
],
"departure_days": [
"monday",
"tuesday",
"wednesday",
"thursday",
"friday",
"saturday",
"sunday"
],
"season_name": ""
},
{
"booking_fence": 0,
"gap_days": 0,
"minimum_nights": 1,
"maximum_nights": 0,
"arrival_days": [
"monday",
"tuesday",
"wednesday",
"thursday",
"friday",
"saturday",
"sunday"
],
"departure_days": [
"monday",
"tuesday",
"wednesday",
"thursday",
"friday",
"saturday",
"sunday"
],
"season_name": ""
},
{
"booking_fence": 0,
"gap_days": 0,
"minimum_nights": 1,
"maximum_nights": 0,
"arrival_days": [
"monday",
"tuesday",
"wednesday",
"thursday",
"friday",
"saturday",
"sunday"
],
"departure_days": [
"monday",
"tuesday",
"wednesday",
"thursday",
"friday",
"saturday",
"sunday"
],
"season_name": ""
},
{
"booking_fence": 0,
"gap_days": 0,
"minimum_nights": 1,
"maximum_nights": 0,
"arrival_days": [
"monday",
"tuesday",
"wednesday",
"thursday",
"friday",
"saturday",
"sunday"
],
"departure_days": [
"monday",
"tuesday",
"wednesday",
"thursday",
"friday",
"saturday",
"sunday"
],
"season_name": ""
}
],
"applicable_taxes": [],
"rate_set_details": {
"agent_daily_markup": 0.00,
"agent_rate_factor": 1.00,
"management_company_rate_factor": 1.00,
"includes_tax": false,
"ciirus_percentage": 0.00,
"include_mandatory_extras": true,
"days_in_month": 30,
"allow_length_of_stay": false
}
}
}
],,
"paging": {
"next_page_url": "https://api.ciiruspartners.com/v2024.07.31/unit_rental?page=1&page_size=25&management_company_user_id=42330&start=2025-01-01&end=2025-12-31",
"total_page_count": 13,
"page": 1,
"page_size": 25
}
}Updated 20 days ago