Accommodation API collection – Migrating to v3.2

A complete guide to updating your Accommodation API integration to Demand API v3.2. Use this overview before diving into the endpoint-specific migration guides.

Introduction

Demand API v3.2 introduces key schema improvements across the Accommodation API collection, including more consistent identifiers, better pagination, unified URL structures, and multi-inventory support.

This page summarises the main changes and highlights where your integration may require updates.

Who is this for

This migration overview is intended for developers and integration partners who consume any of the following Accommodation endpoints:

Summary of key changes

v3.2 introduces structural improvements, multi-currency support, and greater schema consistency across the Accommodation APIs.

Here’s a summary of the most significant changes across the Accommodation APIs:

Breaking changes v3.2 Breaking changes

Multi-currency support

All prices (base, display, charges, totals) now expose both accommodation and booker currencies.

Charges structure

• extra_charges in v3.1 is replaced by detailed charges array in v3.2.
• Each charge includes: charge, condition, included_in, mode, percentage, total_amount, unit_amount.

Cancellation policy

• special_conditions is renamed to "partially_refundable" for clarity.

Product-level pricing

• Full multi-currency support for base, display, charges.
• New chargeable_online field added to indicate conditional online charges.

Third party inventory (TPI) products

• The 3.1 third_party_inventory boolean removed.
• New inventory object with:
  • third_party – boolean, indicates if the inventory is provided by a third party.
  • type – string, either net or sell, indicating the inventory type.

Unmapped room rates

Room IDs are now strings, not integers. In version 3.1 the rooms.id is integer, changes to string to address unmapped room, rooms not defined in Booking.com databases and sourced directly from the wholesaler (TPI partners only)

• This change allows room identifiers to include non-numeric characters, ensuring consistent identification across all property types.

Affected endpoints: /accommodations/details, /accommodations/details/changes, /availability , /bulk-availability, /search

Migration guidance:

1. Update room ID handling to strings.
2. Avoid numeric assumptions (e.g., addition, sorting numerically)
3. If you previously stored room as an integer, update your database schema to string/text type.
4. Fetch the full list of room identifiers via /accommodations/details to ensure your integration correctly maps the string values.

Example of accommodations/details response:

      "rooms": [
        {
          "id": "1000420",
          "attributes": [
            "non_smoking"
          ],

Metadata object added to responses

In v3.2, a new top-level field — metadata — has been added to the responses of the following endpoints:

• /accommodations/details
• /accommodations/details/changes
• /accommodations/search
• /accommodations/reviews/scores
• /accommodations/reviews

This object provides useful information about the request and result set, particularly for pagination and analytics purposes.

Example:

"metadata": {
  "next_page": "eyJhbGciOiJIUzI1NiJ9....",
  "total_results": 128
}

Deprecated fields

List any fields or endpoints no longer supported in v3.2.

Update your integration to avoid relying on them.

Endpoint-specific highlights

Below is a concise summary of the most relevant changes for each Accommodation endpoint.

Need help?

If you have questions about your Accommodation integration migration, contact your Booking.com technical account manager.

By following these guidelines and making the required updates, you can smoothly transition to Demand API v3.2 and continue to provide a seamless Accommodation booking experience for your travellers.

What´s next

Refer to each endpoint migration guide for details: