# 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:

| Endpoint | Integration |
|  --- | --- |
| /accommodations/search | Real-time availability search with structured filters. |
| /accommodations/availability | Property + room availability lookups with multi-currency support. |
| /accommodations/details and /accommodations/details/changes | Property content, room mappings, and change detection. |


## 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:

| Key change | Description |
|  --- | --- |
| ✅ **Unified availability endpoint** | /availability and /bulk-availability are now merged into a single, streamlined endpoint. |
| ✅ **Consistent identifiers** | `room` ID is now a string across all endpoints to support unmapped rooms. |
| ✅ **Improved URL structure** | `deep_link_url` is removed. All redirect URLs are now grouped under a unified url object:* `web` (previously url)
* `app` (previously deep_link_url)

 |
| ✅ **New filtering structure in accommodations/search** | A new `filters` object replaces individual filtering parameters for a more scalable design. |
| ✅ **Removal of third_party_inventory** | The legacy flag is removed in favour of the new `inventory` object that better supports multiple inventory rates. |
| ✅ **Metadata standardisation for pagination** | Paginated endpoints now return a metadata object containing:* `next_page_token`
* `total_results`

 |
| ✅ **New property status values** | /accommodations/details/changes now includes additional closure reasons: temporary, permanent, and fraud. |
| ✅ **Renamed refundability field** | `special_conditions` is now `partially_refundable` to improve clarity. |
| ✅ **Multi-currency improvements** | /accommodations/availability now returns both booker and accommodation currencies. |


## 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:


```json
      "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](/demand/docs/open-api/3.2/demand-api/accommodations/accommodations/details)
* [/accommodations/details/changes](/demand/docs/open-api/3.2/demand-api/accommodations/accommodations/details/changes)
* [/accommodations/search](/demand/docs/open-api/3.2/demand-api/accommodations/accommodations/search)
* [/accommodations/reviews/scores](/demand/docs/open-api/3.2/demand-api/accommodations/accommodations/reviews/scores)
* [/accommodations/reviews](/demand/docs/open-api/3.2/demand-api/accommodations/accommodations/reviews)


The Metadata object has been also included across version 3.2 common/location endpoints for better pagination.

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

Example:


```json
"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.

| Field / Endpoint | Status in v3.2 | Replacement / Notes |
|  --- | --- | --- |
| `third_party_inventory` (search, availability, details, preview) | Removed | Replaced by the structured `inventory` object (`third_party`, `type`) |
| `is_work_friendly` (accommodations/details) | Removed | Use `work_friendly` |
| `cribs_and_extra_beds` (accommodations/details) | Removed | Use `cots_and_extra_beds` |
| `deep_link_url` (accommodations/details) | Removed | Replaced by `url.app` inside the unified `url` object |
| `special_conditions` (search, availability, details) | Deprecated / Renamed | Replaced by `partially_refundable` |
| `extra_charges` (search, availability) | Removed | Replaced by structured `charges[]` |
| `bulk-availability` endpoint | Removed | Merged into `/accommodations/availability` |
| Numeric `room.id` (all accommodation endpoints) | Removed (breaking) | Must be parsed as string |
| Offset-based pagination fields (search, details, reviews) | Removed | Replaced by `metadata.next_page_token` |


### Endpoint-specific highlights

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

| Endpoint | Key updates in v3.2 |
|  --- | --- |
| `/accommodations/search` | • New `filters` object replaces legacy filtering fields.• `special_conditions` → `partially_refundable`.• `room.id` now string.• New `metadata` object for pagination.• `third_party_inventory` removed. |
| `/accommodations/availability` | • `/availability` and `/bulk-availability` merged.• Full multi-currency output (booker + accommodation currencies).• `extra_charges` removed → new `charges[]` structure.• `room.id` now string.• `special_conditions` renamed.• `third_party_inventory` removed. |
| `/accommodations/details` | • Removal of deprecated fields: `is_work_friendly`, `cribs_and_extra_beds`, `deep_link_url`.• New unified `url` object (`web`, `app`).• `room.id` changed to string.• New `metadata` object added.• Cleaner, more consistent nested structures. |
| `/accommodations/details/changes` | • `room.id` now string.• Expanded property closure statuses: `temporary`, `permanent`, `fraud`.• New `metadata` object for paginated changes. |
| `/accommodations/reviews`, `/accommodations/reviews/scores` | • New `metadata` object for pagination.• Consistent response envelope updates. |
| Common (accommodation-related) | • Inventory model updated (new `inventory` object).• Pagination standardised across endpoints.• Deprecation removals aligned across all accommodation endpoints. |


## 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: