# Accommodations migration to Demand API v3.3

**Review the changes introduced in Demand API v3.3 for accommodations and update the endpoints, fields, objects, enum values, and integration behaviour affected by the release.**

## Introduction

Demand API v3.3 introduces new accommodation discovery capabilities, enhanced sustainability metadata, expanded deal tagging, and updated occupancy information.

The real-time autocomplete capability, previously available in Beta, is now available as stable functionality in v3.3.

Use this guide to:

* Identify the changes that affect your integration.
* Review the changes relevant to integrations migrating from v3.1, v3.2 stable, or v3.2 Beta.
* Update accommodation response models and enum handling.
* Add real-time autocomplete to guided search flows.
* Display enhanced sustainability and seasonal deal information.
* Validate the updated occupancy and check-in information.
* Remove fields and enum values that are no longer supported in v3.3.


Before you begin
* Review the [Demand API v3.3 migration overview](/demand/docs/migration-guide/v3.3/changes) for the complete release scope and API availability model.
* Changes to order modification and order modification preview, including modifications to accommodation orders, are covered in the [Orders migration guide](/demand/docs/migration-guide/v3.3/orders/intro).


## Accommodation capability availability after the v3.3 launch

| Capability | v3.2 stable | v3.3 stable | Notes |
|  --- | --- | --- | --- |
| Accommodation search and details | ✓ Available | ✓ Available | Continue using /accommodations/search and /accommodations/details. |
| Real-time autocomplete | ✗ Not available as stable functionality | ✓ Available | /common/autocomplete is promoted from Beta to v3.3 stable. |
| Sustainability metadata | ✓ Available | ✓ Available | v3.3 adds certification logo metadata and makes certification information available without additional access requirements. |
| Seasonal deal tagging | ✓ Available | ✓ Available | v3.3 provides more explicit deal tags for seasonal deals. |
| Check-in after midnight information | ✗ Not available | ✓ Available | The accommodation details response includes whether check-in service is available after midnight. |


Accommodation search, availability, booking, and post-booking management remain available as stable functionality in both v3.2 and v3.3.

## What changes in v3.3

| Area | Change in v3.3 | Action |
|  --- | --- | --- |
| Autocomplete | Real-time autocomplete is available as stable functionality through /common/autocomplete. | Replace any Beta endpoint configuration with the v3.3 stable endpoint. |
| Sustainability | Accommodation details include certification metadata, including certification names and logo URLs. | Update response models and use the metadata to provide clearer sustainability information to travellers. |
| Deal tagging | Deal tags are more explicit and include seasonal deal categories. | Update enum mappings and presentation logic. Do not treat the deal tag enum as closed. |
| Occupancy metadata | Room occupancy information uses `occupancy_total` and age-based child rules. | Update consumers of maximum_occupancy and distinguish children who count towards the total occupancy limit. |
| Check-in information | Accommodation details include accepts_reservations_after_midnight. | Use the field when presenting check-in expectations to travellers. |


## Real-time autocomplete

Stable in v3.3

The /common/autocomplete endpoint supports low-latency, as-you-type destination suggestions and typo-tolerant search experiences.

Use it to help travellers find valid search criteria before starting an accommodation search.

Typical uses include:

* Suggesting cities, regions, countries, airports, or other supported destinations while the traveller types.
* Correcting minor spelling mistakes.
* Reducing invalid location searches.
* Helping travellers reach a valid location identifier more quickly.


When integrating autocomplete:

* Debounce requests generated by user input.
* Display returned suggestion names in the traveller’s selected language where available.
* Use returned location identifiers when constructing accommodation search requests.
* Handle an empty result without treating it as an API failure.
* Do not assume that a suggestion represents an accommodation search result.


See the [Autocomplete API reference](/demand/docs/open-api/3.3/demand-api/commonautocomplete) for the request and response schema.

## Sustainability certification metadata

Enhanced in v3.3

The /accommodations/details response includes additional sustainability certification metadata without requiring separate access to the sustainability programme.

### Handle new sustainability fields

The certification object can now include logo_url.

Ensure that:

* Additional response fields do not cause deserialisation failures.
* A missing logo URL is handled safely.
* Certification names and logos are displayed together only when both are available.


See the [Sustainability certifications guide](/demand/docs/accommodations/sustainability/about) for details.

## Accepts reservations after midnight

New in v3.3

The /accommodations/details response includes accepts_reservations_after_midnight.

The field indicates whether the property offers check-in service after 00:00 on the scheduled arrival date.

When the value is true, guests arriving after midnight on that date can check in.

When displaying this information:

* Make the date and time interpretation clear to travellers.
* Do not interpret the field as permission to arrive on a different calendar date.
* Do not assume that the property offers 24-hour reception.
* Handle a missing or null value according to the API schema.


## Breaking changes to review

Breaking change

The following changes require code updates when migrating to v3.3.

### Seasonal deal tagging

In v3.3, seasonal deals are represented using more specific deal tags.

If your v3.2 integration explicitly handles seasonal_deal, review that mapping against the v3.3 enum values.

The deal.tags array can include tags such as:

* `early_year_deal`
* `flash_deal`
* `getaway_deal`
* `late_escape_deal`
* `limited_time_deal`
* `logged_in_deal`
* `mobile_rate`


Update your integration to:

* Accept the new deal tag values.
* Map tags to traveller-facing labels only where appropriate.
* Avoid treating an unknown tag as an error.
* Avoid assuming that one product has only one applicable deal.
* Keep the original price and discount information separate from the deal tag.


Unknown future tags should not cause the complete accommodation result to be rejected.

See more details in the [Deals dedicated guide](/demand/docs/accommodations/discounts).

### Occupancy metadata

The v3.3 accommodation details response provides a more precise representation of room occupancy limits.

This change applies to the static room occupancy information returned by /accommodations/details. It does not change the basic guest input structure used by accommodation search and availability requests.

See the [Occupancy and allocation guide](/demand/docs/accommodations/occupancy-allocation) for details.

#### Maximum occupancy

In previous versions, room occupancy could be represented using separate adult and total limits:

```json
{
  "maximum_occupancy": {
    "adults": 2,
    "children": [
      {
        "total": 1,
        "from_age": 3,
        "to_age": 12,
        "free_stay": true
      }
    ],
    "total": 3
  }
}
```

In v3.3, the response uses `occupancy_total` and more explicit child rules:

```json
{
  "maximum_occupancy": {
    "occupancy_total": 3,
    "children": [
      {
        "from_age": 3,
        "to_age": 12,
        "amount": 1,
        "included_in_total": true
      }
    ]
  }
}
```

Update consumers of room occupancy metadata from:

* `maximum_occupancy.adults`
* `maximum_occupancy.total`
* `maximum_occupancy.children[].total`
* `maximum_occupancy.children[].free_stay`


To:

* `maximum_occupancy.occupancy_total`
* `maximum_occupancy.children[].from_age`
* `maximum_occupancy.children[].to_age`
* `maximum_occupancy.children[].amount`
* `maximum_occupancy.children[].included_in_total`


Update your data model and presentation logic to:

* Apply included_in_total when calculating whether the room can accommodate the requested guests.
* Enforce the child limit represented by amount.
* Handle multiple age brackets.
* Avoid assuming that all children count towards the total occupancy limit.


### Removed fields and enum values

Demand API v3.3 removes fields and enum values that were deprecated in v3.2.

Before upgrading, check whether your integration sends, reads, stores, or validates the following value.

| Location | Deprecated value | Context | v3.3 action |
|  --- | --- | --- | --- |
| accommodations/search | `filters.cancellation_type`: `non_refundable` | The cancellation_type field remains supported; only the `non_refundable` enum value is removed. | Remove `non_refundable` from requests, validation rules, generated SDK models, and application logic. |


#### Remove the `non_refundable` cancellation filter

The `non_refundable` value is removed from `filters.cancellation_type` in /accommodations/search.

To return only products that can be cancelled for free, use free_cancellation.

To include products regardless of their cancellation type, omit the cancellation_type filter.

For example, replace:

```json
{
  "filters": {
    "cancellation_type": "non_refundable"
  }
}
```

with:

```json
{
  "filters": {
    "cancellation_type": "free_cancellation"
  }
}
```

Alternatively, omit cancellation_type when you do not want to filter by cancellation type.

## Endpoint changes

| v3.2 endpoint or capability | v3.3 endpoint or capability | Migration action |
|  --- | --- | --- |
| Accommodation search | /accommodations/search | Continue using the endpoint. Update response handling for the v3.3 deal tags and remove the `non_refundable` cancellation filter value. |
| Accommodation availability | /accommodations/availability | Continue using the endpoint. Review occupancy mismatch and response handling. |
| Accommodation details | /accommodations/details | Continue using the endpoint. Add sustainability certification metadata, updated occupancy metadata, and check-in information. |
| Location autocomplete | Beta autocomplete endpoint | Use /common/autocomplete in the v3.3 stable API. |


## Generic Beta boundary

AI Smart Search remains in the generic Beta version and is not part of the v3.3 stable accommodation migration.

If you use Smart Search:

* Keep it on the generic Beta version.
* Do not describe it as a v3.3 stable capability.
* Treat its schema and behaviour as subject to change.
* Keep the stable accommodation search flow separate from the AI-assisted Beta flow.


## Migration checklist

### Request changes

* Replace Beta autocomplete configuration with /common/autocomplete.
* Remove `non_refundable` from `filters.cancellation_type`.
* Continue sending the existing accommodation search and availability request structures.
* Confirm that price filter objects contain at least a minimum or maximum value when the price filter is used.


### Response changes

* Add support for sustainability certification logo URLs.
* Update deal tag mappings and enum validation.
* Replace the previous maximum occupancy representation with `occupancy_total` and age-based child rules.
* Add support for accepts_reservations_after_midnight.
* Handle occupancy_mismatch as a warning that requires an application decision.


### Integration behaviour

* Use autocomplete suggestions to guide travellers towards valid search criteria.
* Do not treat an empty autocomplete response as an API failure.
* Do not assume that every accommodation has sustainability certifications.
* Do not use deal tags to calculate prices.
* Do not assume that all children count towards `occupancy_total`.
* Do not treat occupancy_mismatch as an automatic order-blocking error.
* Handle unknown enum values and newly introduced response fields safely.


## Testing recommendations

Use the [Demand API sandbox](/demand/docs/getting-started/sandbox) to validate your accommodation integration before switching to production.

* The sandbox provides test accommodation inventory for validating search, availability, pricing, occupancy, cancellation policies, and booking behaviour.
* Use the test accommodation IDs listed in the sandbox guide rather than production accommodation IDs.


Sandbox limitations
The sandbox has request-rate limits. Accommodation booking tests that involve payments require a real credit card; charges are temporary and are automatically cancelled according to the sandbox payment process.

Do not use sandbox accommodation IDs with the production environment.

### Search and autocomplete

* Search for destinations using /common/autocomplete.
* Test partial input and minor spelling errors.
* Test empty autocomplete results.
* Use returned location identifiers in accommodation search requests.
* Confirm that search results remain valid when autocomplete is not used.
* Confirm that requests no longer send `filters.cancellation_type` with the `non_refundable` value.


### Accommodation details

* Retrieve details with and without sustainability information.
* Verify that certification names and logo URLs are parsed correctly.
* Test accommodations with no certifications.
* Test rooms with multiple child age brackets.
* Verify accommodation details using a sandbox test accommodation with multiple occupancy configurations.
* Verify occupancy calculations when `included_in_total` is true and false.
* Test `accepts_reservations_after_midnight` when it is true, false, null, or omitted.


### Search and availability

* Test standard adult and child occupancy requests.
* Test products that return `occupancy_mismatch`.
* Confirm that allocated and unallocated guests are displayed correctly.
* Validate price filters with both minimum and maximum values.
* Confirm that an empty price filter object is rejected.
* Test seasonal and non-seasonal deal tags.
* Confirm that unknown deal tags do not break response processing.
* Validate that price calculations use the price object rather than deal tags.


## What’s next

* [Version 3.3 Accommodations API reference](/demand/docs/open-api/3.3/demand-api/accommodations/accommodations/details) — For the complete endpoint schemas and examples.
* [Accommodation details guide](/demand/docs/accommodations/look-accommodation-details) — For retrieving property and room information.
* [Deals dedicated guide](/demand/docs/accommodations/discounts) — For displaying deal information.
* [Sustainability certifications guide](/demand/docs/accommodations/sustainability/about) — For sustainability programme information.
* [Occupancy and allocation guide](/demand/docs/accommodations/occupancy-allocation) — For occupancy information and examples.
* [Orders migration guide](/demand/docs/migration-guide/v3.3/orders/intro) — For changes affecting order modification and preview.
* [Error handling guide](/demand/docs/support/error-handling/about-errors) — For common errors and recovery strategies.