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.

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.

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.

Enhanced in v3.3

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

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.

Breaking change

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

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.

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.

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

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

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

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.

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:

{
  "filters": {
    "cancellation_type": "non_refundable"
  }
}

with:

{
  "filters": {
    "cancellation_type": "free_cancellation"
  }
}

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

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

• 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.
• Handle occupancy_mismatch as a warning that requires an application decision.

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

Use the Demand API 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.

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

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