# 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](/demand/docs/orders-api/3.2/cancel-for-less) 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 field | Status | Replacement |
|  --- | --- | --- |
| `cribs_and_extra_beds` | ❌ Removed | ✅ Use `cots_and_extra_beds` |
| `is_work_friendly`, `work_friendly_home` | ❌ Removed | ✅ Use `work_friendly` |
| `long_stay_friendly_home` | ❌ Removed | ✅ Use `long_stay_friendly` |
| `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:


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

### Example - accommodations/details response

v3.1 response 

```json

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

v3.2 response

```json

{
  "request_id": "abc123-unique-request-id",
  "data": [
    {
      "id": 101,
      "accommodation_type": 2,
      "booker_address_required": true,
      "brands": [5, 8],
      "checkin_checkout_times": {
        "checkin_from": "15:00:00",
        "checkin_to": "23:00:00",
        "checkout_from": "07:00:00",
        "checkout_to": "11:00:00"
      },
      "contacts": {
        "general": {
          "email": "info@property.com",
          "telephone": "+31 20 1234567"
        },
        "reservations": {
          "email": "reservations@property.com",
          "telephone": "+31 20 7654321"
        }
      },
      "currency": "EUR",
      "description": {
        "host_type": "professional",
        "important_information": {
          "en-us": "Check-in after 3 PM, check-out before 11 AM",
          "nl-nl": "Inchecken na 15:00, uitchecken voor 11:00"
        },
        "license_numbers": ["NL12345", "VAT67890"],
        "text": {
          "en-us": "A beautiful property in the city centre with modern amenities.",
          "nl-nl": "Een prachtig pand in het stadscentrum met moderne voorzieningen."
        },
        "trader": {
          "name": "Property Trader Ltd",
          "address": {
            "address_line": "Main Street 1",
            "city": "Amsterdam",
            "country": "NL",
            "post_code": "1012AB"
          },
          "email": "trader@property.com",
          "registration_number": "REG12345",
          "telephone": "+31 20 5555555",
          "trade_register": "Amsterdam Chamber of Commerce",
          "trader_verified": true
        }
      },
      "facilities": [
        {
          "id": 1,
          "attributes": ["offsite", "paid"]
        },
        {
          "id": 3,
          "attributes": []
        }
      ],
      "facility_details": {
        "internet_facility": {
          "charge_mode": "free",
          "connection_type": "wifi",
          "coverage": "all_rooms",
          "price": null
        },
        "parking_facilities": [
          {
            "charge_mode": "charges_are_applicable",
            "location": "on_site",
            "price": 10.0,
            "reservation": "needed",
            "type": "private"
          }
        ],
        "restaurant_facilities": [
          {
            "accept_reservations": true,
            "guests_only": false,
            "name": "Main Restaurant",
            "status": "open"
          }
        ],
        "swimming_pool_facilities": [
          {
            "allowed_age_type": "all_ages",
            "payment_type": "free",
            "type": "indoor"
          }
        ]
      },
      "fiscal_information": {
        "legal_name": "Property Legal Name",
        "vat_number": "NL123456789B01"
      },
      "is_genius": true,
      "key_collection_information": {
        "alternate_location": {
          "address": "Side Street 2",
          "city": "Amsterdam",
          "postal_code": "1013CD"
        },
        "checkin_method": "door_code",
        "key_location": "at_the_property"
      },
      "location": {
        "address": {
          "en-us": "Main Street 1, 1012AB Amsterdam",
          "nl-nl": "Hoofdstraat 1, 1012AB Amsterdam"
        },
        "city": 1234,
        "coordinates": {
          "latitude": 52.370216,
          "longitude": 4.895168
        },
        "country": "nl",
        "districts": [567, 568],
        "postal_code": "1012AB",
        "regions": [10, 12]
      },
      "long_stay_friendly": false,
      "meal_prices": {
        "breakfast": 15.0,
        "lunch": 20.0,
        "dinner": null
      },
      "name": {
        "en-us": "Central City Apartment",
        "nl-nl": "Centraal Stadsappartement"
      },
      "number_of_rooms": 50,
      "payment": {
        "methods": {
          "cards": [1, 2, 3],
          "cash": true,
          "virtual_cards": [4, 5]
        },
        "timings": ["pay_at_the_property", "pay_online_now"],
        "cvc_required": true,
        "domestic_no_cc": false,
        "amex_cvc_required": true
      },
      "photos": [
        {
          "main_photo": true,
          "tags": ["Bathroom"],
          "url": {
            "large": "https://q-xx.bstatic.com/xdata/images/hotel/max1280/20934654.jpg",
            "standard": "https://q-xx.bstatic.com/xdata/images/hotel/max500/20934654.jpg",
            "thumbnail": "https://q-xx.bstatic.com/xdata/images/hotel/100x100/20934654.jpg",
            "thumbnail_large": "https://q-xx.bstatic.com/xdata/images/hotel/300x300/20934654.jpg"
          }
        }
      ],
      "policies": {
        "cots_and_extra_beds": [
          {
            "age": {"from": 0, "to": 3},
            "mode": "per_night",
            "price": 10.0,
            "type": "cot"
          }
        ],
        "maximum_checkin_age": null,
        "minimum_checkin_age": 18,
        "minimum_guest_age": 0,
        "pets": {"allowed": "yes", "charge_mode": "charges_may_apply"},
        "damage": {
          "deposit": {
            "collect": {
              "date": {"reference_date": "checkin", "days_offset": 3},
              "payment_method": "credit_card"
            },
            "refund": {
              "date": {"reference_date": "checkout", "days_offset": 2},
              "payment_method": "credit_card"
            }
          },
          "amount": 200.0,
          "currency": "EUR"
        }
      },
      "price_category": "$$",
      "programmes": {"travel_proud": true},
      "ranking": 150,
      "rating": {
        "number_of_reviews": 200,
        "preferred": true,
        "review_score": 8.5,
        "stars": 4,
        "stars_type": "estimated_by_booking"
      },
      "refuses_free_cancellation_requests": false,
      "rooms": [
        {
          "id": "room101",
          "attributes": ["non_smoking", "work_friendly"],
          "bed_options": [
            {
              "bed_configurations": [
                {
                  "id": "bed101a",
                  "configuration": [
                    {"bed_type": 1, "number_of_beds": 1},
                    {"bed_type": 2, "number_of_beds": 1}
                  ]
                }
              ],
              "has_bathroom": true,
              "is_bedroom": true
            }
          ],
          "cots_and_extra_beds": {
            "are_allowed_together": true,
            "maximum_number_of_cots": 1,
            "maximum_number_of_extra_beds": 1
          },
          "description": {"en-us": "Spacious double room", "nl-nl": "Ruime tweepersoonskamer"},
          "facilities": [{"id": 1, "attributes": ["offsite"]}],
          "maximum_occupancy": {"adults": 2, "children": 2, "total_guests": 4},
          "name": {"en-us": "Double Room", "nl-nl": "Tweepersoonskamer"},
          "number_of_rooms": {"bathrooms": 1, "bedrooms": 1, "living_rooms": 0},
          "photos": [
            {
              "main_photo": true,
              "tags": ["Bathroom"],
              "url": {
                "large": "https://q-xx.bstatic.com/xdata/images/hotel/max1280/20934654.jpg",
                "standard": "https://q-xx.bstatic.com/xdata/images/hotel/max500/20934654.jpg",
                "thumbnail": "https://q-xx.bstatic.com/xdata/images/hotel/100x100/20934654.jpg",
                "thumbnail_large": "https://q-xx.bstatic.com/xdata/images/hotel/300x300/20934654.jpg"
              }
            }
          ],
          "room_type": 1,
          "size": 20
        }
      ],
      "spoken_languages": ["en-us", "nl-nl"],
      "themes": [1, 5],
      "url": {
        "app": "bookingapp://property/101?aid=12345",
        "web": "https://www.booking.com/hotel/nl/central-city-apartment.html"
      },
      "work_friendly": true
    }
  ],
  "next_page": "token_for_next_page"
}
```

a
span
strong
Try v3.2 yourself!
## Migration guide – Steps

### 1. Inventory & schema discovery

* Pull the current [v3.2 OpenAPI schema](/demand/docs/open-api/3.2/demand-api/accommodations/accommodations/details) 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:

## What's next

* Check the [v3.2 Accommodations API reference](/demand/docs/open-api/3.2/demand-api/accommodations) for all endpoints details.
* Try the new version in this portal console.
* Contact your Booking.com technical account manager for migration support.