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.
• 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)

Request examples

{
  "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]
}

Response

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

Response examples

{
  "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": "..."
}

Third party products example response

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

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 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.

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

What´s next