Guides
Start typing to search…

What's New in API v2024.07.31

A changelog of what has changed in API v2024.07.31 (12/25)

Overview

Welcome to the What's New? page for the CiiRUS-API. Here, we provide a comprehensive overview of the latest updates, enhancements, and changes introduced in the most recent version. This section highlights key modifications made since previous versions, ensuring you're up-to-date with the latest features and improvements.

📘

Version Scope Notice

The information on this page describes how API v2024.07.31 differs from v2023.07.31 in its current form. Any incremental updates made after the initial rollout of v2024.07.31 are documented separately in the Changelog.

🚧

Currency Format Notice

All currency values in the API are returned in fixed-point format using a scale of 10⁸. For example, a value of 100000000 represents 1.00. This ensures precision in financial calculations. Be sure to adjust your implementation accordingly when parsing or displaying amounts.

Availability Endpoint

🔄 What's Changed?

  • GET /v2023.07.31/availability is now GET /v2024.07.31/unit_calendars
    • The endpoint has been renamed to reflect its updated functionality and now returns a richer, day-by-day unit calendar structure.
  • GET /v2023.07.31/availability/{unitId} is now GET /v2024.07.31/unit_calendars/{unit_id}
    • The unitId path parameter is now formatted as unit_id and the response has been expanded to include detailed per-day availability data.

❌ What's Removed?

  • POST /v2023.07.31/availability
    • Availability checks via this endpoint are no longer available.
  • POST /v2023.07.31/availability/{unitId}
    • Availability checks for specific units via POST have been removed.
  • PUT /v2023.07.31/availability/{unitId}
    • Alteration availability checks for specific units via this endpoint have been removed.
  • Query Parameters Removed:
    • calendarLength – Calendar length is no longer controlled via this parameter.
    • restrictions – Gap-day restriction enforcement is no longer toggled via this flag.

🆕 What's Added?

  • GET /unit_calendars introduces several new query parameters:
    • last_reservation_update_date (date-time) – Filters units that have received a booking (direct or calendar sync) after a specified date.
    • last_agent_module_property_update_date (date-time) – Filters units whose agent module property configuration has changed after a given date.
    • last_agent_module_agent_update_date (date-time) – Filters units whose agent module agent configuration has changed after a given date.
    • enabled (boolean) – Filters units by enabled/disabled status.
    • display_on_website (boolean) – Filters to units enabled for website display.
    • allocation_on_arrival (boolean) – Includes allocation-on-arrival information in the response.
    • allocation_on_arrival_unit (boolean) – Filters to units that are the representative unit in their allocation-on-arrival group.
    • fallback_rates (enum) – Controls how rate information is used when generating the calendar (explicitly_in_date_range_only, fallback_max_value_rate, fallback_max_value_rate_plus_guards).
    • reservation_id (int32) – Allows the calendar to be generated in the context of a specific booking.
    • allocated_reservations (array of int32) – Virtually allocates one or more reservations when generating availability.
    • category_to_ignore (int32) – Ignores reservations for a specific booking category when generating availability.
    • channel (enum) – Filters calendars by channel context (all, bdc, vrbo, airbnb).
    • listing_id (string) – Filters calendars by external listing identifier.
  • GET /unit_calendars/{unit_id}:
    • Now requires start and end dates to define the calendar window.
    • Supports reservation_id, allocated_reservations, category_to_ignore, fallback_rates, and channel to generate channel- and booking-context-aware calendars.

📝 What’s Modified?

  • Pagination Parameters Renamed:
    • pageSize is now page_size
  • Supplier Identifiers Renamed:
    • mcUserId is now management_company_user_id
    • mcUserIds is now management_company_user_ids
  • Unit Identifiers Renamed:
    • unitId is now unit_id
    • unitIds is now unit_ids
  • Update Timestamp Parameter Renamed:
    • lastUpdateDate is now last_unit_update_date
  • Calendar Window Parameters Updated:
    • calendarLength has been replaced by an explicit start and end date range.
    • start is now required for both /unit_calendars and /unit_calendars/{unit_id} and uses a date type (rather than optional date-time).
    • A new required end date parameter defines the end of the calendar range.
  • Updated Calendar Response Structure:
    • The response container has changed from calendars to unit_calendars.
    • Each unit now includes:
      • start_date and end_date for the returned window.
      • A days collection with per-day:
        • availability
        • availability_type
        • closed_to_arrival / closed_to_depature
        • minimum_nights / maximum_nights
        • stay_durations
        • Additional settings flags
      • An allocation_on_arrival object describing pooled availability when allocation-on-arrival is used.
      • An error object to surface unit-level issues when generating calendars.

Booking Endpoint

🔄 What's Changed?

  • POST /v2023.07.31/booking is now POST /v2024.07.31/reservations
    • The booking creation process has been renamed to align with the reservations workflow.
  • PUT /v2023.07.31/booking is now PUT /v2024.07.31/reservations or PUT /v2024.07.31/reservations/{reservation_id}
    • Updates to bookings now go through the reservations endpoint, and if a reservation ID is specified, it targets a specific reservation.

❌ What's Removed?

  • POST /v2023.07.31/booking
    • The old booking creation process is no longer available. Now, reservations are created using the /reservations endpoint.
  • PUT /v2023.07.31/booking
    • Updating bookings is now handled via /reservations with the updated parameter structure.
  • DELETE /v2023.07.31/booking/{bookingId}
    • The removal of bookings now happens using DELETE /reservations/{reservation_id}.
  • Request Fields Removed:
    • organization_id – The booking organization field is no longer supplied in the write payload.
    • source_id – The explicit source identifier is no longer part of the create/modify request body.

🆕 What's Added?

  • Consolidated Booking Operations into Reservations:
    • Create Booking → now performed via POST /reservations using the reservation schema (unit_id, type, details, guests, comments, financials, etc.).
    • Cancel Booking → now performed via DELETE /reservations/{reservation_id}, returning the updated reservation (including details and type) instead of a minimal cancellation payload.

📝 What’s Modified?

  • Endpoint & Identifier Migration:
    • Booking write operations moved from /booking → /reservations.
    • booking_id → standardized reservation id (and reservation_id in path parameters).
    • inventory_id → unit_id.
  • Status Representation:
    • type enums are now lower case:
      • CONFIRMED → confirmed
      • CANCELLED → cancelled
      • TENTATIVE → tentative
    • Guest & Party Structure:
      • party_members + customer_details have been consolidated into a unified guests array with:
        • type (lead_guest, party_member, pet)
        • Contact info (phone_numbers, email_addresses)
        • address, notes, allow_marketing_emails
      • Headcount fields (number_of_adults, number_of_children, number_of_pets) are preserved but now live inside the expanded details object.
    • Comments Structure:
      • Comments remain, but are now under details.comments with enum values:
        • PRIVATE/GENERAL/SCRATCH_PAD → private/general/scratch_pad.
    • Financials & Currency Handling:
      • Old model:
        • financials[] with amount + amount_decimal_places
        • A flat total_amount + amount_decimal_places
      • New model:
        • financials.charges[] with value as 10⁸ fixed-point.
        • financials.total_value, financials.total_paid, amount_paid, etc. also stored as 10⁸ fixed-point.
        • Payments retain amount with amount_decimal_places for payment recording, but totals and charges are strictly fixed-point.
      • Update Patterns:
        • 2023: PUT /booking used a single booking payload.
        • 2024: Updates now use:
          • PUT /reservations for batch updates, and
          • PUT /reservations/{reservation_id} for targeted single-reservation updates, both using the expanded reservation schema.
📘

Note: Currency values utilized by this endpoint use 10⁸ fixed-point format (e.g. 100000000 = $1.00).

Content (Amenities) Endpoint

🔄 What's Changed?

  • GET /v2023.07.31/content/amenities is now GET /v2024.07.31/unit_amenities
    • The old endpoint has been renamed to /unit_amenities to provide a clearer purpose for retrieving unit amenities.
  • GET /v2023.07.31/content/amenities/{unitId} is now GET /v2024.07.31/unit_amenities/{unit_id}
    • The unitId path parameter is now formatted as unit_id for consistency across the API.

❌ What's Removed?

  • unitId – The unitId parameter is now called unit_id, which is a more consistent and clear naming convention.
  • unitIds – This parameter is now referred to as unit_ids in plural form.

🆕 What's Added?

  • GET /unit_amenities introduces several new query parameters:
    • last_unit_update_date (date-time) – Filters the response to only return units modified after a specified date.
    • last_reservation_update_date (date-time) – Filters for units that have received a booking or calendar sync after a specified date.
    • last_agent_module_property_update_date (date-time) – Filters for units where the agent module property configuration was modified after a specified date.
    • last_agent_module_agent_update_date (date-time) – Filters for units where the agent module agent configuration was modified after a specified date.
    • management_company_user_id (int32) – Filters results by the management company identifier.
    • enabled (boolean) – Filters for only enabled or disabled units.
    • display_on_website (boolean) – Filters for units enabled for display on the website.
    • allocation_on_arrival (boolean) – Returns the allocation on arrival object.
    • allocation_on_arrival_unit (boolean) – Returns units that are representative units in their group.
  • GET /unit_amenities/{unit_id} introduces the unit_id path parameter, replacing unitId, and allows the retrieval of unit amenities with the same query parameters as the general endpoint.

📝 What’s Modified?

  • Query Parameters Renaming:
    • pageSize is now page_size for consistency
    • mcUserId is now management_company_user_id
    • mcUserIds is now management_company_user_ids
    • unitId is now unit_id
    • unitIds is now unit_ids

Content (Details) Endpoint

🔄 What's Changed?

  • GET /v2023.07.31/content/details is now GET /v2024.07.31/unit_details
    • The endpoint has been renamed to /unit_details to better reflect its purpose of retrieving unit-specific details.
  • GET /v2023.07.31/content/details/{unitId} is now GET /v2024.07.31/unit_details/{unit_id}
    • The unitId path parameter is now formatted as unit_id for consistency.

❌ What's Removed?

  • unitId – Replaced with unit_id for uniform naming conventions.
  • unitIds – Now unit_ids, ensuring consistency across parameters.

🆕 What's Added?

  • GET /unit_details introduces several new query parameters:
    • last_unit_update_date (date-time) – Filters response to only include units modified after a specified date.
    • last_reservation_update_date (date-time) – Filters for units that have received a booking or calendar sync after a specified date.
    • last_agent_module_property_update_date (date-time) – Filters for units with agent module property updates after a specified date.
    • last_agent_module_agent_update_date (date-time) – Filters for units with agent module agent updates after a specified date.
    • management_company_user_id (int32) – Filters by management company identifier.
    • enabled (boolean) – Filters results to show only enabled or disabled units.
    • display_on_website (boolean) – Filters to show only units enabled for website display.
    • allocation_on_arrival (boolean) – Returns the allocation on arrival object.
    • allocation_on_arrival_unit (boolean) – Returns units that are the representative unit in their group.
  • GET /unit_details/{unit_id} introduces the unit_id path parameter, replacing unitId, and allows retrieval of unit details with the same query parameters as the general endpoint.

📝 What’s Modified?

  • Query Parameters Renaming:
    • pageSize is now page_size for consistency
    • mcUserId is now management_company_user_id
    • mcUserIds is now management_company_user_ids
    • unitId is now unit_id
    • unitIds is now unit_ids

Content (Images) Endpoint

🔄 What's Changed?

  • GET /v2023.07.31/content/images is now GET /v2024.07.31/unit_images
    • The endpoint has been renamed to /unit_images to better align with unit-specific image retrieval.
  • GET /v2023.07.31/content/images/{unitId} is now GET /v2024.07.31/unit_images/{unit_id}
    • The unitId path parameter is now formatted as unit_id for consistency.

❌ What's Removed?

  • unitId – Replaced with unit_id for uniform naming conventions.
  • unitIds – Now unit_ids, ensuring consistency across parameters.
  • onlyFirstImage – No longer available in the new version.

🆕 What's Added?

  • GET /unit_images introduces several new query parameters:
    • last_unit_update_date (date-time) – Filters response to only include units modified after a specified date.
    • last_reservation_update_date (date-time) – Filters for units that have received a booking or calendar sync after a specified date.
    • last_agent_module_property_update_date (date-time) – Filters for units with agent module property updates after a specified date.
    • last_agent_module_agent_update_date (date-time) – Filters for units with agent module agent updates after a specified date.
    • management_company_user_id (int32) – Filters by management company identifier.
    • enabled (boolean) – Filters results to show only enabled or disabled units.
    • display_on_website (boolean) – Filters to show only units enabled for website display.
    • allocation_on_arrival (boolean) – Returns the allocation on arrival object.
    • allocation_on_arrival_unit (boolean) – Returns units that are the representative unit in their group.
  • GET /unit_images/{unit_id} introduces the {unit_id} path parameter, replacing {unitId}, and allows retrieval of unit images with the same query parameters as the general endpoint.

📝 What’s Modified?

  • Query Parameters Renaming:
    • pageSize is now page_size for consistency
    • mcUserId is now management_company_user_id
    • mcUserIds is now management_company_user_ids
    • unitId is now unit_id
    • unitIds is now unit_ids

Emails Endpoint

🔄 What's Changed?

  • The base path remains /emails, but it has been updated to /v2024.07.31 for consistency with the latest API version.
    • PUT /v2023.07.31/emails is now /v2024.07.31/emails
    • GET /v2023.07.31/emails/subaccount is now /v2024.07.31/emails/subaccount
    • POST /v2023.07.31/emails/subaccount is now /v2024.07.31/emails/subaccount
    • PUT /v2023.07.31/emails/subaccount is now /v2024.07.31/emails/subaccount
    • DELETE /v2023.07.31/emails/subaccount is now /v2024.07.31/emails/subaccount
  • No structural changes in functionality for sending emails or managing subaccounts.

❌ What's Removed?

  • No parameters or functionality have been removed.

🆕 What's Added?

  • No new fields or endpoints were introduced in this update.

📝 What’s Modified?

  • Version Update: All endpoints now use /v2024.07.31 instead of /v2023.07.31
  • Formatting Adjustments: Parameters and request structures remain the same.

Inventory Endpoint

🔄 What's Changed?

  • The base path has been renamed from /inventory to /units in v2024.07.31.
    • GET /v2023.07.31/inventory is now /v2024.07.31/units
    • PUT /v2023.07.31/inventory is now /v2024.07.31/units
    • GET /v2023.07.31/inventory/{unitId} is now /v2024.07.31/units/{units_id}
    • PUT /v2023.07.31/inventory/{unitId} is now /v2024.07.31/units/{units_id}
  • More granular filtering options have been introduced for retrieving units.

❌ What's Removed?

  • Community Filtering (communityId): No longer available in the query parameters.
  • Permissions & Airbnb Context (permissions, airbnb): These parameters have been removed.
  • no_total parameter has been removed.

🆕 What's Added?

  • New Query Parameters for Filtering Units:
    • last_reservation_update_date: Filters units that have received a booking (either direct or via calendar sync) after a specified date.
    • last_agent_module_property_update_date & last_agent_module_agent_update_date: Tracks modifications in the agent module property and agent configurations.
    • listing_id: Allows lookup by listing ID.

📝 What’s Modified?

  • Pagination Parameters Renamed:
    • pageSize is now page_size
  • Supplier Identifiers Renamed:
    • mcUserId is now management_company_user_id
    • mcUserIds is now management_company_user_ids
  • Updated Structure for Unit Updates:
    • Now uses units/{unit_id} instead of inventory/{unitId}

LengthOfStay Endpoint

🔄 What's Changed?

  • The endpoint structure has been renamed from /los/bwlayers and /los/loslayers to /layers/length and /layers/window in v2024.07.31.
  • BW and LoS layers have been consolidated into "Length Layers" and "Window Layers" under the new /layers/ namespace.

❌ What's Removed?

  • Decimal Places (decimal_places): No longer required.
  • User ID (user_id): Now replaced with management_company_user_id

🆕 What's Added?

  • Management Company Identifier (management_company_user_id): Replaces user_id to standardize ownership of layers.
  • Separation of Length and Window Layers:
    • /layers/length: Handles traditional Length of Stay logic.
    • /layers/window: Introduced for different pricing or restriction layers.

📝 What’s Modified?

  • Path Parameter Renaming:
    • layerId is now referred to as layer_id.
  • Endpoint Paths Updated:
    • /los/bwlayers/ is now /layers/length/
    • /los/loslayers/ is now /layers/window/
  • Multipliers & Layer Properties Remain the Same but are now used for both length and window layers.
📘

Note: Currency values utilized by this endpoint use 10⁸ fixed-point format (e.g. 100000000 = $1.00).

Payments Endpoint

📘

Note: Payment-related capabilities are available by request and are no longer documented as part of the public API reference. Partners who need details on submitting credit card information, see Steps to Success → Submitting Credit Card Details.

Quotes Endpoint

🔄 What’s Changed?

  • Endpoint & Naming Changes:
    • Old Endpoint: /quote
    • New Endpoint: /unit_quotes/{unit_id}
      • The endpoint has been renamed and requires a unit_id as a path parameter.
      • The path now includes {unit_id} instead of using inventory_id in the body.
    • Old Endpoint for Multiple Quotes: /quotes
    • New Endpoint for Multiple Quotes: /unit_quotes
      • The endpoint for retrieving multiple quotes has also been renamed and is now /unit_quotes instead of /quotes.
  • Terminology & Parameter Changes:
    • inventory_id is now unit_id (moved to the path parameter in the URL).
      • Previously in the request body as an integer.
      • Now it’s required in the path to identify the unit uniquely.
    • organization_id is now management_company_user_id.
      • This was previously an optional field and is now renamed for clarity.
    • source_id is now reference.
      • The previous source_id field is replaced by reference.
    • optional_extras is now moved under charges (within financials):
      • Previously represented in the body as an array of integers.
      • Now it is part of a structured object within the financials object.
    • discount_code remains, but now it is placed under financials.
      • Previously part of the main body, now nested under financials.
    • thread_id is now included in the details object.
      • Previously was a separate top-level field.
  • Expanded Guest Information:
    • party_members is now renamed to guests (which is a nested object):
      • This object includes more structured and detailed guest information.
      • New guest details include:
        • first_name (string)
        • last_name (string)
        • phone_numbers (array of strings)
        • email_addresses (array of strings)
        • address (object):
          • Contains notes, allow_marketing_emails (boolean), and airbnb_guest_id.
        • id (integer) – CRM ID of the guest.
        • type (string, required)
        • lead_guest (boolean, explicitly supported).
  • Structure Improvements:
    • origination_date has now been added:
      • Tracks the date and time when the quote was originally created.
    • expiration is now included:
      • This field indicates when the quote or tentative reservation expires.
    • cancelled_on now tracks reservation cancellations:
      • This is a new field, indicating when a reservation has been canceled.
    • category, category_id, and category_description are now explicitly defined:
      • These were previously undefined, but now explicitly describe the reservation category associated with the Agent.
    • secure_details now contains additional security-related fields for access:
      • lock_box_code, gate_code, alarm_code, wifi_ssid, wifi_password.
  • Financial Structure Changes:
    • financials is now a more structured object that includes:
      • charges (array of objects with detailed charge information):
        • item (string)
        • id (integer)
        • code (string)
        • quantity (integer)
        • charge_type (string)
        • amount (integer)
      • payments (array of objects with detailed payment tracking):
        • amount (integer)
        • amount_decimal_places (integer, now defaults to 2)
        • payment_date (date-time)
        • payment_schedule (array of objects for scheduled payments)
        • total_paid (total amount paid by the customer)
        • total (total reservation value)
        • currency (string)
      • merchant_of_record (new field)
      • merchant_of_record_user (new field)
    • scenario has been added:
      • Identifies different reservation viewing scenarios, giving more flexibility in quoting and viewing.
    • allocation_on_arrival and allocation_on_arrival_unit (new fields) provide more flexibility in the reservation and allocation process.
    • fallback_rates (new query parameter):
      • Ensures that length-of-stay pricing is applied when available.
    • length_of_stay (boolean field under financials):
      • Indicates whether length-of-stay pricing is applicable.

❌ What’s Removed?

  • amount_decimal_places from payment_schedule:
    • Pricing now uses micros, and this field is no longer necessary.
  • decimalPlaces field for total calculations has been removed:
    • The new structure uses more precise calculations.
  • source and source_id have been removed:
    • These fields are no longer needed, replaced by reference.
  • party_members has been removed:
    • This has been replaced by the more structured and detailed guests object.
  • optional_extras is removed from the body and is now part of charges under financials.
  • thread_id has been removed from the top-level fields and moved into the details object.

🆕 What’s Added?

  • financials explicitly groups and structures financial data:
    • charges, payments, currency, merchant_of_record, and merchant_of_record_user are all part of financials.
  • scenario allows defining multiple reservation viewing conditions.
  • allocation_on_arrival and allocation_on_arrival_unit offer more flexible booking and allocation options.
  • fallback_rates enables better pricing flexibility by using length-of-stay pricing.
  • merchant_of_record and merchant_of_record_user track transaction ownership.
  • length_of_stay ensures length-of-stay pricing is applied.
📘

Note: Currency values utilized by this endpoint use 10⁸ fixed-point format (e.g. 100000000 = $1.00).

Rates (Rental) Endpoint

🔄 What’s Changed?

  • Endpoint Renaming & Structure Updates
    • Old:
      • /v2023.07.31/rates
      • /v2023.07.31/rates/{unitId}
    • New:
      • /v2024.07.31/unit_rental
      • /v2024.07.31/unit_rental/{unit_id}
  • Terminology & Parameter Updates
    • Page Size Parameter:
      • pageSize is now page_size (case change).
    • Query Parameter Changes:
      • mcUserId is now management_company_user_id
      • mcUserIds is now management_company_user_ids
      • unitId is now unit_id (with underscores instead of camel case)
      • unitIds is now unit_ids
      • ratesLength is now maximum_future_days (more descriptive)
      • lastUpdateDate is now split into more specific parameters:
        • last_unit_update_date
        • last_reservation_update_date
        • last_agent_module_property_update_date
        • last_agent_module_agent_update_date
  • New Parameters Added:
    • enabled (boolean): Filters results to only include enabled or disabled units.
    • display_on_website (boolean): Filters results based on whether the unit is enabled for the website.
    • allocation_on_arrival (boolean): Returns the allocation on arrival object.
    • allocation_on_arrival_unit (boolean): Returns units which are the representative unit in their group.
    • channel (string): Specifies the channel for the rates.
  • Date Parameters Changes:
    • start and end (now required) for the date range of rate information.
    • start (date) and end (date) now appear for both unit rental query and individual unit rental query.
  • Query for Length of Stay:
    • lengthOfStay is now included in the query as fallback_rates (boolean) under both endpoints, ensuring length-of-stay pricing is applied if available.

❌ What’s Removed?

  • Removed Parameters:
    • ratesLength has been replaced by maximum_future_days
    • lastUpdateDate is now split into more specific query parameters and is no longer a single parameter.
    • The minValue and maxValue parameters are removed, as they were specific to the old implementation of rate guards.
    • no_total parameter has been removed.

🆕 What’s Added?

  • New Query Parameters & Improvements:
    • management_company_user_id and management_company_user_ids replace mcUserId and mcUserIds for more precise filtering of suppliers.
    • enabled filters units based on whether they are enabled or disabled.
    • display_on_website filters units specifically enabled for the website.
    • allocation_on_arrival and allocation_on_arrival_unit provide more flexibility with arrival unit allocation queries.
    • Additional date fields such as last_agent_module_property_update_date and last_agent_module_agent_update_date provide more detailed tracking for unit updates.
📘

Note: Currency values utilized by this endpoint use 10⁸ fixed-point format (e.g. 100000000 = $1.00).

Rates (Extras) Endpoints

🔄 What's Changed?

  • GET /v2023.07.31/rates/extras is now GET /v2024.07.31/unit_extras
    • The endpoint has been renamed to align with the updated unit-based API structure.
  • GET /v2023.07.31/rates/extras/{unitId} is now GET /v2024.07.31/unit_extras/{unit_id}
    • The unitId path parameter is now formatted as unit_id for consistency.
  • The extras model has been expanded significantly to support advanced extra logic such as date-range rules, age bands, stay duration rules, quantity rules, value types, and vendor/supplier allocation.

❌ What's Removed?

  • Legacy Endpoints:
    • /rates/extras
    • /rates/extras/{unitId}
  • Removed Parameters:
    • airbnb – No longer available in the Extras endpoints.

🆕 What's Added?

  • GET /unit_extras introduces several new query parameters:
    • last_unit_update_date (date-time) – Filters for units modified after a specified date.
    • last_reservation_update_date (date-time) – Filters for units that received a booking or calendar sync after a specified date.
    • last_agent_module_property_update_date (date-time) – Filters for units with agent module property updates.
    • last_agent_module_agent_update_date (date-time) – Filters for units with agent module agent updates.
    • enabled (boolean) – Filters for enabled or disabled units.
    • display_on_website (boolean) – Filters units enabled for website display.
    • allocation_on_arrival (boolean) – Returns allocation-on-arrival information.
    • allocation_on_arrival_unit (boolean) – Returns units that are the representative unit in their group.
    • channel (enum) – Specifies channel context (all, bdc, vrbo, airbnb).
    • listing_id (string) – Filters by listing ID.
    • retrieve_all_extras (boolean) – Returns all extras regardless of rule applicability.
    • include_extras_without_value (boolean) – Includes zero-value extras.
  • GET /unit_extras/{unit_id} introduces the updated path parameter and supports the same new selectors as the main endpoint.

📝 What’s Modified?

  • Query Parameter Renaming:
    • pageSize is now page_size
    • mcUserId is now management_company_user_id
    • mcUserIds is now management_company_user_ids
    • unitId is now unit_id
    • unitIds is now unit_ids
    • retrieveAllExtras is now retrieve_all_extras
  • Updated Structure for Retrieving Extras:
    • Retrieving extras is now unit-driven using /unit_extras and /unit_extras/{unit_id}
    • The new schema includes expanded logic that replaces the 2023 model:
      • Mandatory extras
      • Per-guest pricing
      • Per-day pricing
      • Guest-quantity ranges
      • Stay-duration ranges
      • Age-band pricing
      • Date-range restrictions (bookable and effective)
      • Full-stay requirements
      • Percent vs fixed value (value_type)
      • Minimum and maximum values
      • Vendor, supplier, owner, and MC allocations
      • Insurance policy class
      • Channel-specific visibility
      • Optional inclusion of zero-value extras
    • Tax Structure Updated:
      • applicable_taxes now uses a simple enum string array (e.g., "tax_one"), replacing the v2023 object structure.
📘

Note: Currency values utilized by this endpoint use 10⁸ fixed-point format (e.g. 100000000 = $1.00).

Rates (Fees) Endpoints

🔄 What's Changed?

  • GET /v2023.07.31/rates/fees is now GET /v2024.07.31/unit_quotes
    • The endpoint is now part of the unit-based quoting architecture, returning all fee-related configuration for a unit.
  • GET /v2023.07.31/rates/fees/{unitId} is now GET /v2024.07.31/unit_quotes/{unit_id}
    • The unitId path parameter has been updated to unit_id for consistency.
  • Fee retrieval no longer uses the Rates namespace and is now delivered through the unified quote options structure.

❌ What's Removed?

  • Legacy Endpoints:
    • /rates/fees
    • /rates/fees/{unitId}
  • Airbnb Context Parameter (airbnb): This has been removed as a query parameter.

🆕 What's Added?

  • New /unit_quotes Endpoint:
    • Allows more granular filtering using updated query parameters.
  • New Query Parameters for Enhanced Filtering:
    • last_unit_update_date (date-time): Filters units modified after a specified date.
    • last_reservation_update_date (date-time): Filters units that received a booking after a specified date.
    • last_agent_module_property_update_date (date-time): Tracks changes in agent module property settings.
    • last_agent_module_agent_update_date (date-time): Tracks changes in agent module agent settings.
    • enabled (boolean): Filters based on whether a unit is enabled or disabled.
    • display_on_website (boolean): Filters units enabled for website display.
    • allocation_on_arrival (boolean): Returns allocation-on-arrival details.
    • allocation_on_arrival_unit (boolean): Filters for representative units in grouped properties.
    • channel (enum): Filters results for a specific channel (all, bdc, vrbo, airbnb).
  • GET /unit_quotes/{unit_id} introduces the updated path parameter and supports channel filtering.

📝 What’s Modified?

  • Query Parameter Renaming:
    • pageSize is now page_size
    • mcUserId is now management_company_user_id
    • mcUserIds is now management_company_user_ids
    • unitId is now unit_id
    • unitIds is now unit_ids
  • Updated Structure for Retrieving Fees:
    • Retrieving Fees is now unit-driven using /unit_quotes and /unit_quotes/{unit_id}.
    • The new schema consolidates all fee-related configuration for the unit, including:
      • Cleaning fee settings
      • Booking fee configuration
      • Security deposit amounts and settings
      • Pool heat and spa heat pricing
      • Fee/tax rules and inclusion flags
      • Percentage distributions to management company or owner
      • Down-payment and balance-due rules
      • Minimum night stay, gap days, and validity windows
      • Daily rate factors for short/long stays
📘

Note: Currency values utilized by this endpoint use 10⁸ fixed-point format (e.g. 100000000 = $1.00).

Rates (Ratesets) Endpoint

🔄 What's Changed?

  • Endpoint URL has changed:
    • Old: /v2023.07.31/rates/ratesets
    • New: /v2024.07.31/ratesets
  • Query Parameter Renaming:
    • pageSize is now page_size for consistency with other endpoints.
    • The mcUserId and mcUserIds parameters have been replaced with management_company_user_id and management_company_user_ids
    • unitId and unitIds parameters have been renamed to unit_id and unit_ids to follow the new naming convention
    • excludeExpiredRates parameter has been renamed to exclued_expired_rates

❌ What's Removed?

  • lastUpdateDate is no longer available; instead, filters have been streamlined.

🆕 What's Added?

  • New rateset_id and rateset_ids parameters for retrieving specific rateset(s).
  • arrival_days and departure_days arrays are added to rate_bands for more granular control over arrival and departure day filtering.
  • no_total parameter added to improve performance by omitting the total page count.

📝 What’s Modified?

  • rate_band has been expanded with new fields:
    • arrival_days and departure_days as arrays for finer control over specific days.
    • minimum_nights_stay is now more specific at the unit level.
  • rate_band includes the floor_rate, season_name, and maximum_nights_stay fields for additional flexibility in rate bands.
📘

Note: Currency values utilized by this endpoint use 10⁸ fixed-point format (e.g. 100000000 = $1.00).

Reservations Endpoint

🔄 What's Changed?

  • The base path remains /reservations, but the reservation model and response shape have been restructured:
    • GET /v2023.07.31/reservations → GET /v2024.07.31/reservations
    • GET /v2023.07.31/reservations/{reservationId} → GET /v2024.07.31/reservations/{reservation_id}
  • Reservation data that was previously mostly flat at the root is now organized into:
    • A new details object (arrival/departure, guests, category, secure details, comments, etc.).
    • A new financials object (charges, payments, payment schedule, totals, merchant-of-record, etc.).
  • The single-reservation update path has been aligned with the plural naming convention:
    • PUT /v2023.07.31/reservation/{reservationId} is now PUT /v2024.07.31/reservations/{reservation_id} and uses the same details/financials-based schema as retrieval.
  • Pagination metadata has been moved from top-level properties into a dedicated paging object in the response.
📘

The create / update / cancel behaviors (including migration from /booking) are detailed under the separate Booking Endpoint section. This Reservations section focuses on retrieval and the shared reservation model.

❌ What's Removed?

  • Query Parameters:
    • no_total – previously used to suppress the total page count; no longer supported.
    • lastUpdateDate – previously used for modification-based filtering; in practice, modifiedStart/modifiedEnd (now modified_start/modified_end) are the supported pattern.
  • Response Fields:
    • The following fields from the 2023 reservation resource are not present in the 2024 schema:
      • status – reservation state is now expressed via the type field.
      • clone_id
      • clone_user_id
      • agent_id

🆕 What's Added?

  • Root-Level Fields:
    • management_company_user_id – added at the reservation root to identify the supplier per reservation.
    • type – string representing reservation type (confirmed, cancelled, tentative).
    • error – per-reservation error object with:
      • message
  • details Object:
    • A details object has been introduced. It consolidates existing data from 2023 and adds several new fields:
      • Existing concepts now grouped under details:
        • arrival
        • departure
        • added
        • expiration
        • cancelled_on
        • scenario
        • category
        • category_id
        • secure_details (lock/gate/Wi-Fi/access codes)
        • early_check_in
        • late_check_out
        • arrival_departure_info
        • owner_reservation
      • Newly introduced or more explicit fields within details:
        • quote_as_super_site_user_id
        • comments – now an array of objects:
          • text
          • type (private, etc.)
      • guests – unified guest collection:
        • id
        • type (lead_guest, party_member, pet)
        • title
        • first_name
        • last_name
        • age
        • phone_numbers[]
        • email_addresses[]
        • address:
          • address_line_1
          • address_line_2
          • city
          • state_province
          • country
          • postal_code
        • notes
        • allow_marketing_emails
      • Headcount fields (replacing root-level adults / children):
        • number_of_adults
        • number_of_children
        • number_of_pets
      • Category metadata extensions:
        • category_description
        • calendar_sync_category_id
      • Extended secure_details:
        • Adds door_code in addition to the existing codes.
      • Additional metadata:
        • source
        • thread_id
        • unit_name
        • referrer
  • financials Object:
    • The 2023 financials array and root-level totals have been refactored into a structured financials object, which both reorganizes and extends the financial model:
      • High-level properties:
        • rate_set_id
        • length_of_stay
        • pool_heat
        • discount_code
        • currency
        • merchant_of_record (string)
        • merchant_of_record_user
      • charges – replaces the 2023 financials[] array:
        • item
        • id (int)
        • code
        • applies_to_id
        • quantity
        • type
        • value (monetary value, fixed-point)
      • payments – extended from the 2023 root-level payments[]:
        • amount
        • payment_date
        • amount_decimal_places
        • payment_user_id
        • payment_method
        • payment_type
        • payment_description
      • payment_schedule – extended from the 2023 root-level payment_schedule[]:
        • value
        • value_due
        • payment_type
        • payment_status
        • due_date
      • Totals and balance tracking (replacing root-level monetary fields):
        • total_paid
        • total_value
        • payment_taken_by
        • merchant_grantee_agent
        • merchant_grantee_supplier
        • amount_paid
        • mc_total_inclusive_tax
        • balance_due_amount
        • balance_due_date
  • Pagination Object
    • A new paging object has been introduced at the response root:
      • next_page_url
      • previous_page_url
      • total_page_count
      • page
      • page_size
  • Filtering Enhancements
    • New singular category filter:
      • category_id – added alongside category_ids to filter by a single category ID.

📝 What’s Modified?

  • Query Parameters:
    • The following query parameters have been renamed for consistency (primarily camelCase → snake_case and clarified naming):
      • Pagination:
        • pageSize → page_size
      • Supplier / Management Company:
        • mcUserId → management_company_user_id
        • mcUserIds → management_company_user_ids
      • Identifiers:
        • unitId → unit_id
        • unitIds → unit_ids
        • reservationId → reservation_id
        • reservationIds → reservation_ids
      • Date filters:
        • modifiedStart → modified_start
        • modifiedEnd → modified_end
        • arrivalStart → arrival_start
        • arrivalEnd → arrival_end
        • departureStart → departure_start
        • departureEnd → departure_end
        • cancelledStart → cancelled_start
        • cancelledEnd → cancelled_end
        • addedStart → added_start
        • addedEnd → added_end
      • Category & Merchant filters:
        • categoryIds → category_ids
        • merchantOfRecord → merchant_of_record
      • Miscellaneous filters:
        • addedByStaffId → added_by_staff_id
      • (Other filters such as reference, references, cancelled, quote, and tentative retain their semantics; only naming has been normalized where noted.)
  • Status / Type Representation
    • 2023:
      • Reservation state was expressed via status with values like CONFIRMED, CANCELLED, TENTATIVE.
    • 2024:
      • State is now expressed via type with values like confirmed, cancelled, tentative.
      • The status field is no longer present.
  • Guest & Party Data
    • 2023:
      • Headcount and guests were modeled via:
        • Root fields: adults, children
        • lead_guest_details
        • guest_list[]
    • 2024:
      • Headcount is now:
        • details.number_of_adults
        • details.number_of_children
        • details.number_of_pets
      • Guests are consolidated under:
        • details.guests[] with explicit type and richer contact / address / marketing fields.
      • Comments move from a single root comments string to:
        • details.comments[] with text + type.
  • Secure Details:
    • 2023:
      • secure_details at the root contained:
        • lock_box_code, gate_code, alarm_code, wifi_ssid, wifi_password, lobby_code, fitness_room_code, pool_access_code, beach_access_code.
    • 2024:
      • secure_details is now under details.secure_details and adds:
        • door_code.
  • Financial Structure & Currency Representation:
    • 2023:
      • Monetary data was spread across:
        • Root fields: total, total_paid, total_amount, amount_decimal_places.
        • financials[] (array) with line items (amount + amount_decimal_places).
        • Root payments[] and payment_schedule[] with amount + amount_decimal_places.
        • Root merchant_of_record (integer).
    • 2024:
      • Monetary data is centralized in financials:
        • Line items under financials.charges[] using value.
        • Totals such as total_value, total_paid, amount_paid, mc_total_inclusive_tax, balance_due_amount are all part of financials.
        • payments[] and payment_schedule[] now include additional metadata while keeping amount/amount_decimal_places (payments) and introducing value/value_due (payment_schedule).
        • merchant_of_record is now a string within financials, with merchant_of_record_user added for clarity.
  • Pagination Metadata:
    • 2023:
      • Top-level pagination fields:
        • next_page_url
        • previous_page_url
        • total_page_count
    • 2024:
      • Pagination metadata is moved into the paging object:
        • paging.next_page_url
        • paging.previous_page_url
        • paging.total_page_count
        • paging.page
        • paging.page_size
📘

Note: Monetary values under the financials.charges, financials.payment_schedule, and financial total fields are expressed using a fixed-point integer representation (e.g. 100000000 = $1.00). Payment amount fields continue to use amount_decimal_places for scaling. Ensure your integration applies the appropriate conversion before displaying currency values.

Suppliers Endpoint

🔄 What's Changed?

  • GET /v2023.07.31/suppliers is now GET /v2024.07.31/suppliers
    • The base path remains /suppliers, with the version updated to v2024.07.31.
  • Pagination metadata has been restructured:
    • In 2023, next_page_url, previous_page_url, and total_page_count were returned at the root level.
    • In 2024, these are now returned inside a paging object alongside page and page_size.

❌ What's Removed?

  • Response Fields:
    • user_id – This field is no longer present in the supplier object. It has been superseded by a new identifier field (id).

🆕 What's Added?

  • Query Parameter:
    • no_total (boolean): Defaults to false. If set to true, omits the total page count from the response to improve performance for large result sets.
    • active (boolean): Filters suppliers by activity status. Only returns suppliers marked as active when set to true.
  • Response Fields (per supplier):
    • id – Integer identifier for the supplier (replaces the old user_id string identifier).
    • credit_cards – Array of credit card configuration objects:
      • id
      • card_type
      • percentage
    • arrival_time – Default arrival time configured for the supplier.
    • departure_time – Default departure time configured for the supplier.
  • Pagination Object:
    • paging – New object encapsulating pagination metadata:
      • next_page_url
      • previous_page_url
      • total_page_count
      • page
      • page_size

📝 What’s Modified?

  • Query Parameters:
    • pageSize → page_size – Page-size parameter renamed for consistency with other v2024 endpoints.
  • Pagination Metadata Structure:
    • Pagination-related fields have been moved from the response root into the paging object:
      • Previously: root-level next_page_url, previous_page_url, total_page_count.
      • Now: paging.next_page_url, paging.previous_page_url, paging.total_page_count, plus paging.page and paging.page_size.

Updated 4 days ago