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_requestsneeded for the "Cancel for less" functionality (See guide for details). - Replacement of
deep_link_urlwith a consolidatedurlobject containingappand webURLs. - No breaking changes to request parameters other than adapting to
extrasif 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_urlremoved → must switch tourl.app.- Integrations relying on
deep_link_urlshould be updated immediately.
Deprecated fields
| Deprecated field | Status | Replacement |
|---|---|---|
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
| Field | v3.1 | v3.2 | Impact |
|---|---|---|---|
extras | description, facilities, payment, photos, policies, rooms | description, facilities, payment, photos, policies, refuses_free_cancellation_requests, rooms | Non-breaking addition: request this extra if you want cancellation refusal data. |
Other parameters (accommodations, airport, city, country, region, languages, rows, page, payment) | Same | Same | No changes. |
✅ Recommendation: Update integrations that parse extras to optionally handle the new refuses_free_cancellation_requests field.
Response body changes
| Field | v3.1 | v3.2 | Impact |
|---|---|---|---|
deep_link_url | String URL to app | Removed | Breaking change: clients using this field must migrate. |
url | Not present | New object with app and web properties | Consolidates URLs: url.app replaces deep_link_url; url.web provides a property page link for web. |
cribs_and_extra_beds | Present | ❌ Removed | Use cots_and_extra_beds instead. |
Other fields (id, accommodation_type, booker_address_required, brands, checkin_checkout_times, contacts, currency, description, facilities, facility_details) | Same | Same | No 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
}
]
}
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_requestsin 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.