Understand how Demand API versions are released and maintained, how Beta capabilities become stable, and how to plan your integration upgrades.
Demand API follows a versioning strategy designed to provide predictable API contracts while allowing new capabilities to be introduced and tested.
The strategy distinguishes between:
- Stable versions: Numbered API versions that provide predictable contracts and follow backward-compatibility rules.
- Beta: An independent API collection that provides early access to selected capabilities and may introduce breaking changes.
New capabilities and changes are introduced according to their compatibility with existing integrations and the lifecycle of each API version.
Changes to Demand API are classified according to whether they affect compatibility with existing integrations.
| Change type | Description | Stable API impact | Beta API impact |
|---|---|---|---|
| Breaking changes | Changes that require partners to modify their existing integrations to continue using the API. Examples include removing fields, changing existing field types or modifying request structures in incompatible ways. | Breaking changes cannot be introduced into the current stable version. They must be released in the next stable version, with migration guidance to help partners adapt. | Breaking changes are permitted. Beta endpoints may evolve without introducing a new numbered API version. |
| Non-breaking changes | Changes that preserve compatibility with existing integrations. Examples include adding optional fields, introducing new endpoints or making backward-compatible improvements. | Non-breaking changes may be introduced into the current stable version or included in the next stable version. Frozen versions do not receive new features or enhancements. | Non-breaking changes may be introduced as part of ongoing Beta development and testing. |
Demand API does not follow strict Semantic Versioning. Stable versions use numbered releases, such as 3.2 and 3.3, while Beta operates independently of numbered versions.
- Predictable stable contracts: Existing integrations are protected from breaking changes within the current stable version.
- Controlled introduction of new capabilities: New functionality can be tested in Beta before being considered for stable release.
- Clear version lifecycle: When a new stable version is released, the previous version is frozen.
- Simplified migration planning: Changelogs and migration guides help partners identify changes and prepare their integrations.
Demand API follows an annual stable release cycle, complemented by incremental updates and independent Beta development.
| Release type | Description |
|---|---|
| Annual stable release | A new numbered stable version is released every autumn. It introduces new capabilities and may include breaking changes. When the new version is released, the previous stable version becomes frozen. |
| Incremental updates | Non-breaking changes can be introduced into the current stable version throughout the year, following a continuous delivery approach. These updates are communicated through the Changelog. |
| Beta updates | Beta endpoints can be introduced or updated independently of the annual stable release cycle. Both breaking and non-breaking changes are permitted. |
This approach allows partners to plan upgrades around predictable annual releases while accessing backward-compatible improvements throughout the year.
Each numbered stable version follows a lifecycle that determines which changes it can receive.
| Lifecycle stage | Description | Allowed changes |
|---|---|---|
| Current stable | The latest numbered stable version, recommended for new integrations. | Non-breaking changes, including new capabilities, enhancements and bug fixes. Breaking changes must wait until the next stable version. |
| Frozen | When a new stable version is released, the previous stable version becomes frozen. It remains available for existing integrations. | Only strictly necessary bug fixes. No new features or enhancements. |
| Deprecated | A version that has been formally announced as deprecated. Partners should plan to migrate according to the published deprecation and retirement guidance. | Any applicable support arrangements are defined in the deprecation announcement. |
When version 3.3 is released, it becomes the current stable version and version 3.2 becomes frozen.
Version 3.1 exception
Version 3.1 remains available for existing integrations as an exception to the standard version lifecycle. Partners using this version are encouraged to migrate to a newer stable version.
Backward compatibility is a core principle of the Demand API stable-version strategy.
- Current stable version: Non-breaking changes may be introduced without requiring existing integrations to change.
- Frozen versions: API contracts remain unchanged, except for strictly necessary bug fixes.
- New stable versions: Breaking changes may be introduced. Partners should review the migration guide and update their integrations where required.
These compatibility guarantees apply to stable versions. Beta follows a different lifecycle and may introduce breaking changes.
The Demand API Beta collection provides early access to selected capabilities before they are introduced into a stable version.
Unlike numbered stable versions, Beta is an independent API collection with its own endpoints, specification and lifecycle.
| Characteristic | Description |
|---|---|
| Dedicated API paths | Beta endpoints use the /beta path, independently of numbered stable versions. For example, https://demandapi.booking.com/beta/transfers/search. |
| Separate API specification | Beta endpoints are documented in a dedicated Beta API reference. Stable API references contain only stable endpoints. |
| Selected endpoints only | Beta contains only endpoints with Beta capabilities. Stable endpoints without Beta capabilities are not duplicated in Beta. |
| Independent endpoint contracts | An endpoint may exist in both Beta and stable versions, with different paths and request or response structures. |
| Breaking changes | Beta endpoints may introduce breaking changes without requiring a new numbered version. |
| Promotion to stable | Product determines which Beta capabilities are promoted to stable and when they are released. |
Beta capabilities are evaluated before being introduced into a stable API version. Product determines which capabilities are promoted and when.
The target stable version depends on whether the changes are backward-compatible.
| Change type | Promotion to stable |
|---|---|
| Non-breaking changes | May be introduced into the current stable version or included in the next stable version. |
| Breaking changes | Must be introduced in the next stable version. Breaking changes cannot be promoted directly into the current stable version. |
When Beta capabilities are promoted to stable:
- The promoted capabilities become available in the corresponding stable API version and are announced in the monthly Changelog.
- Partners can start using the stable implementation.
- The promoted capabilities remain available in Beta for three months after the changelog announcement.
- After this period, the promoted capabilities are retired from Beta.
Partial promotions
An endpoint may contain multiple Beta capabilities that are promoted to stable at different times.
If only some capabilities are promoted, the Beta endpoint remains available with its remaining Beta capabilities. Only the promoted capabilities are retired from Beta after the three-month transition period.
For example, if /beta/accommodations/search contains three Beta capabilities and only one is promoted to stable:
- The promoted capability becomes available in the appropriate stable version.
- The Beta endpoint continues to expose all three capabilities during the three-month transition period.
- After the transition period, the promoted capability is retired from Beta.
- The Beta endpoint remains available with the two capabilities that have not yet been promoted.
Beta compatibility and retirement
Beta endpoints may introduce breaking changes to request and response structures.
When a capability is promoted to stable, review the changelog and migrate to the stable implementation before the three-month retirement period ends.
An endpoint may remain available in Beta after individual capabilities have been retired.
You can use stable and Beta endpoints as part of an integration, depending on the capabilities you need.
For example:
- Use /3.3/accommodations/search to access the stable accommodations search endpoint.
- Use /beta/transfers/search to access the Beta transfers search endpoint.
The Beta collection does not include every endpoint available in stable versions. If an endpoint is not available in Beta, use the appropriate stable API version.
We recommend keeping integrations up to date with the latest stable API version to access new capabilities and improvements.
When upgrading between numbered stable versions, follow these steps:
| Step | Description |
|---|---|
| 1. Review the changelog | Check the Changelog to identify new capabilities, changes and deprecations. |
| 2. Check deprecation announcements | Review News for announcements affecting the version you are using. |
| 3. Read the migration guide | Consult the Migration guidelines to identify breaking changes and any required integration updates. |
| 4. Test in Sandbox | Validate your integration using the Sandbox environment before deploying changes to production. |
| 5. Monitor your integration | After upgrading, monitor API responses and error handling to identify unexpected behaviour. |
If you need assistance with version upgrades or Beta integrations, refer to the support documentation or contact your Booking.com Account Manager.
- API References — Explore available stable versions and the independent Beta collection.
- Changelog — Review API changes, new capabilities and Beta-to-stable announcements.
- Migration guidelines — Find guidance for upgrading between stable API versions.