Accommodations details – Migrating to v3.2

Learn how to update your integration to support /accommodations/details in Demand API v3.2. This guide explains breaking changes, new nested structures, and recommended migration practices.


Summary of key impacts

  • Addition of a new extras option: refuses_free_cancellation_requests needed for the "Cancel for less" functionality (See guide for details).
  • Replacement of deep_link_url with a consolidated url object containing app and web URLs.
  • No breaking changes to request parameters other than adapting to extras if you want the new cancellation data.

Breaking changes

Breaking changes

The following v3.1 fields are deprecated or replaced in v3.2. Update your integration to avoid disruption.

  • deep_link_url removed → must switch to url.app.
  • Integrations relying on deep_link_url should be updated immediately.

Deprecated fields

Deprecated fieldStatusReplacement
cribs_and_extra_beds❌ Removed✅ Use cots_and_extra_beds
is_work_friendly❌ Removed✅ Use cots_and_extra_beds
deep_link_url❌ Removed✅ Use url.app

Request body changes

Fieldv3.1v3.2Impact
extrasdescription, facilities, payment, photos, policies, roomsdescription, facilities, payment, photos, policies, refuses_free_cancellation_requests, roomsNon-breaking addition: request this extra if you want cancellation refusal data.
Other parameters (accommodations, airport, city, country, region, languages, rows, page, payment)SameSameNo changes.

Recommendation: Update integrations that parse extras to optionally handle the new refuses_free_cancellation_requests field.

Response body changes

Fieldv3.1v3.2Impact
deep_link_urlString URL to appRemovedBreaking change: clients using this field must migrate.
urlNot presentNew object with app and web propertiesConsolidates URLs: url.app replaces deep_link_url; url.web provides a property page link for web.
cribs_and_extra_bedsPresent❌ RemovedUse cots_and_extra_beds instead.
Other fields (id, accommodation_type, booker_address_required, brands, checkin_checkout_times, contacts, currency, description, facilities, facility_details)SameSameNo changes.

Example of the new url object:

"url": {
  "app": "https://app.booking.com/...",
  "web": "https://www.booking.com/..."
}

Example - accommodations/details response


{
  "request_id": "01fr9ez700exycb98w90w5r9sh",
  "data": [
    {
      "id": 10004,
      "accommodation_type": 204,
      "brands": [],
      "checkin_checkout_times": {
        "checkin_from": "15:00:00",
        "checkin_to": null,
        "checkout_from": "07:00:00",
        "checkout_to": "12:00:00"
      },
      "currency": "EUR",
      "deep_link_url": "booking://hotel/10004?affiliate_id=!AFFILIATE_ID!",
      "description": {
        "important_information": {
          "en-gb": "The credit card that has been used to book a non-refundable rate, will be charged on the day of booking and needs to be presented upon check-in. In case the credit card owner is not traveling with you, an online payment link will be sent to prepay your stay.\n\nPlease note that the hotel pre-authorizes your credit card with the amount for the first night, 8 days prior to arrival. This is not a payment and this only applies to flexible rates.\n\nParking in Amsterdam is challenging, there are parking garages near to the hotel or a valet service is possible to arrange upon request. Charges are applicable. Please contact the hotel ahead of time for information",
          "zh-cn": "酒店将在预订当天收取用于支付不退款房价的信用卡,客人需在办理入住手续时出示该信用卡。如果信用卡持有人未与客人同行,酒店将发送在线付款链接以预付客人的住宿费用。\n\n请注意,酒店将在客人抵达前8天通过其信用卡预授权第一晚的房费。这不是付款,这仅适用于变化的利率。\n\n在阿姆斯特丹(Amsterdam)停车很有挑战性,酒店附近有停车库,或者可应要求为客人安排代客泊车服务,收费适用。请提前联系酒店以获取信息。",
          "fallback": null
        },
        "license_numbers": [],
        "text": {
          "en-gb": "The Pavilions Amsterdam, The Toren features elegant accommodation alongside the famous Keizersgracht canal, around the corner from the Anne Frank House. It offers elegant rooms with flat-screen TVs with digital entertainment system.\n\nEach air-conditioned room at the Toren has an en suite bathroom with a bathtub. They have classic decorations such as chandeliers and ceiling paintings. Tea/coffee making facilities and a complimentary mini bar are also provided in every room.\n\nIn the morning, guests can enjoy a delightful breakfast buffet in the elegant breakfast room with views of the Keizersgracht. The trendy hotel bar serves refreshing drinks during the day.\n\nWestermarkt Tram Stop is less than 250 metres from the hotel. Dam Square and the Royal Palace are a 10-minute walk away.",
          "zh-cn": "The Pavilions Amsterdam, The Toren酒店位于安妮弗兰克之家(Anne Frank House)拐角处,毗邻著名的Keizersgracht运河,提供典雅的住宿。酒店提供带平板电视和数字娱乐系统的典雅客房。\n\nToren酒店的每间空调客房均配有带浴缸的独立浴室。客房拥有典雅的装饰,如吊灯和天花板画。每间客房还提供沏茶/咖啡设施和免费迷你吧。\n\n早晨,客人可在典雅的早餐室享用可口的自助早餐,并欣赏Keizersgracht的景色。时髦的酒店酒吧白天提供清凉饮料。\n\n酒店距离韦斯特马克特电车站(Westermarkt Tram Stop)不到250米,距离水坝广场(Dam Square)和皇宫(Royal Palace)有10分钟的步行路程。",
          "fallback": null
        },
        "trader": {
          "address": {
            "address_line": "Prinsengract 153",
            "city": "Amsterdam",
            "country": "nl",
            "post_code": "94571"
          },
          "email": "test@test.test",
          "name": "Test Test",
          "registration_number": "123456788",
          "telephone": "+123456789",
          "trade_register": "hjdfvhfjd",
          "trader_verified": true
        }
      },
      "facilities": [
        {
          "id": 5,
          "attributes": []
        },
        "..."
      ],
      "is_genius": true,
      "is_work_friendly": false,
      "location": {
        "address": {
          "fallback": "Keizersgracht 164"
        },
        "city": -2140479,
        "coordinates": {
          "latitude": 52.375858,
          "longitude": 4.886006
        },
        "country": "nl",
        "districts": [
          145,
          3024,
          9173
        ],
        "postal_code": "1015 CZ",
        "regions": [
          1010,
          2776
        ]
      },
      "long_stay_friendly_home": false,
      "meal_prices": {
        "breakfast": 20,
        "dinner": null,
        "lunch": null
      },
      "name": {
        "fallback": "The Pavilions Amsterdam, The Toren"
      },
      "number_of_rooms": 11,
      "payment": {
        "amex_cvc_required": false,
        "cvc_required": true,
        "domestic_no_cc": false,
        "methods": {
          "cash": true,
          "cards": [
            1,
            2,
            3
          ],
          "virtual_cards": [
            1,
            2,
            3
          ]
        },
        "timings": [
          "pay_at_the_property"
        ]
      },
      "photos": [
        {
          "main_photo": true,
          "tags": [
            "Neighbourhood"
          ],
          "url": {
            "large": "https://q-xx.bstatic.com/xdata/images/hotel/max1280/243931754.jpg?k=a1fea83a088f20b8f8a0e68ac06cb0090a093808f6e2a129bfb990165a0009f3&o=",
            "standard": "https://q-xx.bstatic.com/xdata/images/hotel/max500/243931754.jpg?k=a1fea83a088f20b8f8a0e68ac06cb0090a093808f6e2a129bfb990165a0009f3&o=",
            "thumbnail": "https://q-xx.bstatic.com/xdata/images/hotel/100x100/243931754.jpg?k=a1fea83a088f20b8f8a0e68ac06cb0090a093808f6e2a129bfb990165a0009f3&o=",
            "thumbnail_large": "https://q-xx.bstatic.com/xdata/images/hotel/300x300/243931754.jpg?k=a1fea83a088f20b8f8a0e68ac06cb0090a093808f6e2a129bfb990165a0009f3&o="
          }
        },
        "..."
      ],
      "policies": {
        "cots_and_extra_beds": [
          {
            "age": {
              "from": 0,
              "to": 2
            },
            "mode": "per_night",
            "price": 0,
            "type": "crib"
          }
        ],
        "damage": {
          "amount": 50,
          "currency": "EUR",
          "deposit": {
            "collect": {
              "date": {
                "days_offset": 0,
                "reference_date": "checkin"
              },
              "payment_method": "credit_card"
            },
            "refund": {
              "date": {
                "days_offset": 0,
                "reference_date": "checkout"
              },
              "payment_method": "credit_card"
            }
          }
        },
        "maximum_checkin_age": null,
        "minimum_checkin_age": 18,
        "minimum_guest_age": 0,
        "pets": {
          "allowed": "no",
          "charge_mode": null
        }
      },
      "price_category": "$$$$",
      "programmes": {
        "travel_proud": false
      },
      "ranking": 123456,
      "rating": {
        "number_of_reviews": 930,
        "preferred": true,
        "review_score": 9,
        "stars": 4,
        "stars_type": "official"
      },
      "rooms": [
        {
          "id": 1000420,
          "attributes": [
            "non_smoking"
          ],
          "bed_options": [
            {
              "bed_configurations": [
                {
                  "id": "1000420-1",
                  "configuration": [
                    {
                      "bed_type": 6,
                      "number_of_beds": 1
                    }
                  ]
                },
                {
                  "id": "1000420-2",
                  "configuration": [
                    {
                      "bed_type": 1,
                      "number_of_beds": 2
                    }
                  ]
                }
              ],
              "has_bathroom": true,
              "is_bedroom": true
            }
          ],
          "cots_and_extra_beds": {
            "are_allowed_together": false,
            "maximum_number_of_cots": 0,
            "maximum_number_of_extra_beds": 0
          },
          "cribs_and_extra_beds": {
            "are_allowed": false,
            "maximum_number_of_cribs": 0,
            "maximum_number_of_extra_beds": 0
          },
          "description": {
            "en-gb": "This room features decor with rich colours and original features. It is located in the annex building, 8 houses away from the main building. It is internally positioned, overlooking a small courtyard.",
            "fallback": null
          },
          "facilities": [
            1,
            "..."
          ],
          "maximum_occupancy": {
            "adults": 2,
            "children": 1,
            "total_guests": 2
          },
          "name": {
            "en-gb": "Standard Double or Twin Room",
            "zh-cn": "标准双人或双床间 ",
            "fallback": null
          },
          "number_of_rooms": {
            "bathrooms": 1,
            "bedrooms": 1,
            "living_rooms": 0
          },
          "photos": [
            {
              "tags": [
                "Neighbourhood"
              ],
              "url": {
                "large": "https://q-xx.bstatic.com/xdata/images/hotel/max1280/243931754.jpg?k=a1fea83a088f20b8f8a0e68ac06cb0090a093808f6e2a129bfb990165a0009f3&o=",
                "standard": "https://q-xx.bstatic.com/xdata/images/hotel/max500/243931754.jpg?k=a1fea83a088f20b8f8a0e68ac06cb0090a093808f6e2a129bfb990165a0009f3&o=",
                "thumbnail": "https://q-xx.bstatic.com/xdata/images/hotel/100x100/243931754.jpg?k=a1fea83a088f20b8f8a0e68ac06cb0090a093808f6e2a129bfb990165a0009f3&o=",
                "thumbnail_large": "https://q-xx.bstatic.com/xdata/images/hotel/300x300/243931754.jpg?k=a1fea83a088f20b8f8a0e68ac06cb0090a093808f6e2a129bfb990165a0009f3&o="
              }
            },
            "..."
          ],
          "room_type": 9,
          "size": 18
        },
        "..."
      ],
      "spoken_languages": [
        "de",
        "en-gb",
        "fr",
        "nl"
      ],
      "themes": [
        6,
        "..."
      ],
      "url": "https://www.booking.com/hotel/nl/toren.html?affiliate_id=!AFFILIATE_ID!",
      "work_friendly_home": false
    }
  ]
}
Try v3.2 yourself!

Migration guide – Steps

1. Inventory & schema discovery

  • Pull the current v3.2 OpenAPI schema for /accommodations/details and inspect the data[] object.

2. Update URL handling:

  • Replace all deep_link_url references with url.app.
  • Optionally use url.web for web redirects.

3. Handle new extra:

  • Include refuses_free_cancellation_requests in extras if your integration requires cancellation refusal information.

4. Business logic & reporting

  • Update

5. Testing

  • Run integration tests with sample v3.2 responses.
  • Use test hotels and sandbox environment for the accommodation implementation.
  • Validate pagination and language handling.

6. Check downstream systems:

  • Update any systems or reporting logic that relied on deep_link_url..

Other accommodation migration guides

Refer to each endpoint migration guide for details:

3.2 accommodations/search migration

Learn how to migrate your accommodations/search integration from v3.1 to v3.2. Understand the structural changes and key request and response differences.

3.2 accommodations/availability migration

Learn how to migrate your accommodations/search integration from v3.1 to v3.2. Understand the structural changes and key request and response differences.


What's next

  • Check the v3.2 Accommodations API reference for all endpoints details.
  • Try the new version in this portal console.
  • Contact your Booking.com technical account manager for migration support.