# Accommodations search – Migrating to v3.2

**Learn how to migrate from accommodations/search v3.1 to v3.2. This guide highlights breaking changes, new fields, deprecated fields, and step-by-step migration actions.**

## Introduction

This guide summarises changes between /accommodations/search v3.1 → v3.2 and explains the updates required to maintain correct functionality, including:

* Request and response field changes.
* Price and currency handling.
* Product-level and inventory updates.
* Pagination and filtering improvements.


## Breaking changes v3.2  Breaking changes

These changes **require updates to partner logic, data models, or UI** to avoid errors or misinterpretation.

### Key field changes

Request changes:

* `Filters` - Several request-level filters (e.g., `24_hour_reception`, `accommodation_facilities`, `accommodation_types`, `brands`, `cancellation_type`, `dormitories`, `meal_plan`, `payment`, `price`, `rating`, `room_facilities`, `travel_proud`) are now inside the `filters` object.
* `cancellation_type.non_refundable` - This is deprecated.
* No fields were removed entirely, but the restructuring of filters may break clients that relied on top-level placement.


Response changes:

- **Currency handling**- `currency` is now an object with `currency.accommodation` and `currency.booker`.
- **Price structure**- Use `price.display` instead of `price.book`, `price.total`, and `price.charges` instead of `extra_charges`.
- **Cancellation policy enum** - `special_conditions` is replaced by `partially_refundable`.
- **Conditional charges** - Charges may now include `included_in.display` and `chargeable_online`.
- **extra_charges** - Renamed to "charges".
- **Products array** - Detailed product-level pricing, policies, and inventory are returned only when requested with `extras=products`.
- **third_party_inventory** - The boolean is removed and replaced by `"inventory"` object.


## Request

### Comparison table (v3.1 → v3.2)

| v3.1 | v3.2 | Impact | Notes / migration action |
|  --- | --- | --- | --- |
| Top-level filters: `24_hour_reception`, `accommodation_facilities`, `accommodation_types`, `brands`, `cancellation_type`, `dormitories`, `meal_plan`, `payment`, `price`, `rating`, `room_facilities`, `travel_proud` | All moved inside `filters` object. | Breaking | Update request models and client logic to use `filters` object. |
| X | New filter: `filters.sustainability_certification` | Non-breaking | Optional filter. Partners can ignore or start using it. |
| `cancellation_type.non_refundable` | Deprecated: `cancellation_type.non_refundable` | Non-breaking | Update request models and client logic to avoid using this filter. |


### Request examples

v3.1 request 

```json

{
  "booker": {
    "country": "nl",
    "platform": "desktop"
  },
  "checkin": "!START_DATE!",
  "checkout": "!END_DATE!",
  "city": -2140479,
  "extras": ["extra_charges", "products"],
  "guests": {
    "number_of_adults": 2,
    "number_of_rooms": 1
  },
  "24_hour_reception": true,
  "accommodation_facilities": [1,2,3],
  "accommodation_types": [1,2]
}
```

v3.2 request
v3.2 search request with new `filters` object:


```json
{
  "booker": {
    "country": "nl",
    "platform": "desktop"
  },
  "checkin": "!START_DATE!",
  "checkout": "!END_DATE!",
  "city": -2140479,
  "extras": ["extra_charges", "products"],
  "guests": {
    "number_of_adults": 2,
    "number_of_rooms": 1
  },
  "filters": {
    "24_hour_reception": true,
    "accommodation_facilities": [1,2,3],
    "accommodation_types": [1,2]
  }
}
```

See more examples in the [Filter and sorting guide](/demand/docs/accommodations/filter-sorting).

## Response

The /accommodations/search response now supports multi-currency pricing, product-level inventory, and enhanced charges.

| Field | v3.1 | v3.2 | Notes / Migration Action |
|  --- | --- | --- | --- |
| `currency` | string | object `{ accommodation, booker }` | Update models to support two currency fields. |
| `price` | `{ base, book, extra_charges, total }` | `{ base, display, charges, total }` | Use `display` for UI, `total` for calculations, and `charges` array for breakdown. |
| `products` | array | array | Include `extras=products` to get detailed pricing and policies. |
| In policies: `cancellation.type` | `special_conditions` | `partially_refundable` | Update enums in models and logic. |
| `third_party_inventory` | boolean | object `inventory` | Any code or UI logic that relied on `third_party_inventory` must be updated to check `inventory.third_party` and, optionally, `inventory.type`. |


### Response examples

v3.1 response 

```json

{
  "request_id": "01fr9ez700exycb98w90w5r9sh",
  "data": [
    {
      "id": 10004,
      "currency": "EUR",
      "deep_link_url": "booking://hotel/10004?affiliate_id=!AFFILIATE_ID!&checkin=!START_DATE!&checkout=!END_DATE!&mcid=10",
      "price": {
        "base": 1081.49,
        "book": 1260.52,
        "extra_charges": {
          "excluded": 0,
          "included": 179.04
        },
        "total": 1260.52
      },
      "products": [
        {
          "id": "1000420_95127794_2_0_0",
          "children": [],
          "deal": null,
          "inventory": {
            "third_party": false,
            "type": "sell"
          },
          "number_of_adults": 2,
          "policies": {
            "cancellation": {
              "free_cancellation_until": null,
              "type": "non_refundable"
            },
            "meal_plan": {
              "meals": [],
              "plan": "no_plan"
            },
            "payment": {
              "timings": [
                "pay_at_the_property"
              ]
            }
          },
          "price": {
            "base": 1081.49,
            "book": 1260.52,
            "extra_charges": {
              "conditional": [],
              "excluded": [],
              "included": [
                {
                  "charge": 21,
                  "mode": "percentage",
                  "percentage": 9,
                  "total_amount": 107.07,
                  "unit_amount": null
                },
                {
                  "charge": 22,
                  "mode": "percentage",
                  "percentage": 7,
                  "total_amount": 83.27,
                  "unit_amount": null
                },
                {
                  "charge": 142,
                  "mode": "per_person_per_night",
                  "percentage": null,
                  "total_amount": 6,
                  "unit_amount": 3
                }
              ]
            },
            "total": 1260.52
          },
          "room": 1000426,
          "third_party_inventory": false
        }
      ],
      "url": "https://www.booking.com/hotel/nl/conscious-the-tire-station.html?affiliate_id=!AFFILIATE_ID!&checkin=!START_DATE!&checkout=!END_DATE!&group_adults=2&no_rooms=1"
    },
    "..."
  ],
  "next_page": "..."
}
```

v3.2 response

```json
{
  "request_id": "01fr9ez700exycb98w90w5r9sh",
  "data": [
    {
      "id": 10004,
      "currency": {
        "accommodation": "EUR",
        "booker": "EUR"
      },
      "deep_link_url": "booking://hotel/10004?affiliate_id=!AFFILIATE_ID!&checkin=!START_DATE!&checkout=!END_DATE!&mcid=10",
      "price": {
        "base": {
          "accommodation_currency": 1081.49,
          "booker_currency": 1081.49
        },
        "charges": [
          {
            "charge": 21,
            "condition": null,
            "included_in": { "display": true },
            "mode": "percentage",
            "percentage": 9,
            "total_amount": {
              "accommodation_currency": 97.34,
              "booker_currency": 97.34
            },
            "unit_amount": null
          },
          {
            "charge": 22,
            "condition": null,
            "included_in": { "display": true },
            "mode": "percentage",
            "percentage": 7,
            "total_amount": {
              "accommodation_currency": 75.7,
              "booker_currency": 75.7
            },
            "unit_amount": null
          }
        ],
        "display": {
          "accommodation_currency": 1260.52,
          "booker_currency": 1260.52
        },
        "total": {
          "accommodation_currency": 1260.52,
          "booker_currency": 1260.52
        }
      },
      "products": [
        {
          "id": "1000420_95127794_2_0_0",
          "children": [],
          "deal": null,
          "inventory": { "third_party": false, "type": "sell" },
          "number_of_adults": 2,
          "policies": {
            "cancellation": { "free_cancellation_until": null, "type": "non_refundable" },
            "meal_plan": { "meals": [], "plan": "no_plan" },
            "payment": { "timings": ["pay_at_the_property"], "prepayment_required": null }
          },
          "price": {
            "base": { "accommodation_currency": 1081.49, "booker_currency": 1081.49 },
            "charges": [
              {
                "charge": 21,
                "condition": null,
                "included_in": { "display": true, "chargeable_online": true },
                "mode": "percentage",
                "percentage": 9,
                "total_amount": { "accommodation_currency": 107.07, "booker_currency": 107.07 },
                "unit_amount": null
              }
            ],
            "display": { "accommodation_currency": 1260.52, "booker_currency": 1260.52 },
            "total": { "accommodation_currency": 1260.52, "booker_currency": 1260.52 }
          },
          "room": "1000426"
        }
      ],
      "url": "https://www.booking.com/hotel/nl/conscious-the-tire-station.html?affiliate_id=!AFFILIATE_ID!&checkin=!START_DATE!&checkout=!END_DATE!&group_adults=2&no_rooms=1"
    }
  ],
  "next_page": null
}
```

#### Third party products example response

v3.1 response 

```json
"products": [
  {
    "id": "1000420_95127794_2_0_0",
    "third_party_inventory": false
  }
]
```

v3.2 response

```json
"products": [
  {
    "id": "1000420_95127794_2_0_0",
    "inventory": {
      "third_party": false,
      "type": "sell"
    }
  }
]
```

## Migration steps

### 1. Inventory & schema discovery

* Review v3.2 inventory model changes (net vs sell rates, third-party inventory, product-level pricing).
* Identify renamed or restructured fields (filters, currency, price, cancellation).


### 2. Update models

* Update your internal data models to reflect v3.2 fields:
  * Multi-currency support (`currency.accommodation` and `currency.booker`)
  * New `price.display`, `price.total`, and `price.charges` structures
  * Product-level inventory and pricing changes
* Update enums, e.g., `cancellation.type: partially_refundable` replacing `special_conditions`.


### 3. Location mappings

* Verify location IDs and filters if applicable (regions, countries, geo-coordinates).
* Ensure that any mapping to your internal location logic aligns with v3.2 parameters.


### 4. UI & Business logic

* Update front-end display to use `price.display` instead of `price.book`.
* Adjust booking flows for multiple payment timings (`products[].policies.payment.timings`).
* Update handling of conditional charges and charge breakdowns, including `chargeable_online`.


### 6. Testing

* Test all API responses end-to-end:
  * Validate multi-currency prices.
  * Verify cancellation, and payment policies.
  * Confirm correct inventory type (net/sell) and third-party flags.
* Use [Sandbox environment](/demand/docs/getting-started/sandbox) and test properties.


### 7. Rollout

* Gradually switch your integration to v3.2 in a staging environment.
* Monitor logs using `request_id`.
* Fully migrate once all tests pass and all business logic is confirmed.


## Non-breaking improvements

These add new fields or extend existing behaviour without breaking existing responses.

| Field | Change | Why it's non-breaking |
|  --- | --- | --- |
| `filters.sustainability_certification` | New optional filter | Partners ignoring it will behave the same. |


## Migration cheat sheet (v3.1 → v3.2)

| Area | v3.1 | v3.2 | Migration Checklist |
|  --- | --- | --- | --- |
| **Currency** | Single `currency` field | `currency.accommodation` & `currency.booker` | ✅ Update data models to handle multi-currency pricing.✅ Update UI to show both accommodation and booker currencies if relevant. |
| **Price** | `price.book` | `price.display`, `price.total`, `price.charges` | ✅ Use `display` for UI presentation.✅ Use `total` for calculations and summaries.✅ Parse `charges` for detailed breakdowns. |
| **Cancellation policy** | `special_conditions` | `partially_refundable` | ✅ Update enums in your code.✅ Ensure cancellation logic maps `partially_refundable` correctly. |
| **Conditional charges** | `extra_charges.included` / `excluded` | `charges[].included_in.display` & `chargeable_online` | ✅ Adjust pricing logic to account for conditional charges.✅ Check `included_in.display` to calculate what is shown to users.✅ Consider `chargeable_online` for online payment flow. |
| **Inventory** | `third_party_inventory` | `inventory.type` (`net`/`sell`) & `inventory.third_party` | ✅ Update models to store inventory type and third-party flag.✅ Adjust business logic for net vs sell rate products. |


## What´s next

* See the [accommodations/search guide](/demand/docs/accommodations/search-for-available-properties)
* Refer to [version 3.2 accommodations/search API](/demand/docs/open-api/3.2/demand-api/accommodations/accommodations/search) reference