# Orders migration to Demand API v3.3

**Migrate your Orders API integration from Demand API v3.2 stable to v3.3.**

Demand API v3.3 introduces a consultative order-modification preview flow, extends accommodation modifications to eligible orders paid online, and updates several Orders API response structures and enum values.

## Before you begin

This guide covers the migration of the Orders API collection from Demand API v3.2 stable to v3.3.

If your integration uses an earlier version, choose the appropriate guide:

If you use Demand API v3.2 stable, continue with this guide.

Review the [Demand API v3.3 migration overview](/demand/docs/migration-guide/v3.3/changes) for the complete release scope and API availability model.

Use this guide to:

* Review the changes between Demand API v3.2 stable and v3.3.
* Add order-modification preview before applying accommodation changes.
* Support modifications to eligible accommodation orders paid online.
* Update Orders API response models and enum handling.
* Validate the migrated integration in the sandbox where supported.


**Note:** Car rental post-booking details, terms and conditions, FAQs, and invoicing are covered in the dedicated [Car rentals migration guides](/demand/docs/migration-guide/v3.3/cars/intro).

## Orders API availability

| Capability | v3.2 stable | v3.3 stable | Notes |
|  --- | --- | --- | --- |
| Order preview | ✓ Available | ✓ Available | The request and response structures are compatible. v3.3 also supports car rental order previews. |
| Order creation | ✓ Available | ✓ Available | The request supports accommodation and car rental order creation. Car rental creation is asynchronous. |
| Order details and reporting | ✓ Available | ✓ Available | Continue using /orders/details for cross-service reporting and synchronisation, including `transfers`. |
| Accommodation order modification | ✓ Available | ✓ Available | v3.3 extends supported modifications to eligible accommodation orders paid online. |
| Order modification preview | ✗ Not available in v3.2 stable | ✓ Available | Use /orders/modify/preview before /orders/modify when you need to validate a requested change. |


## What’s changing in v3.3

| Area | Change in v3.3 | Required action |
|  --- | --- | --- |
| Order modification preview | /orders/modify/preview is available as stable functionality in v3.3. | Add the preview step before /orders/modify where the traveller needs to review feasibility or price impact. |
| Online-payment modifications | Eligible accommodation orders paid online can be modified through /orders/modify. | Update eligibility checks and handle separate modification and payment outcomes. |
| Modification responses | /orders/modify can return a standard status or a detailed response with modification_status, payment_status, and message. | Do not assume that a successful modification means that payment has also completed. |
| Car order creation response | The car response changes `reservation_id` to `reservation`, and `Processing` to `processing`. | Update response models, stored identifiers, and enum handling. |
| Transfer order details | The order details response uses `transfers` instead of `taxis` for transfer reservations. | Update request services values, response models, serialisation, and reporting consumers. |


## Migrating from v3.2 stable

### Order preview and creation

The accommodation request and response structures for /orders/preview and /orders/create remain compatible with v3.3.

Continue to:

* Use /orders/preview before /orders/create.
* Pass the latest `order_token` returned by /orders/preview to /orders/create.
* Re-run /orders/preview when the traveller changes dates, rooms, guests, products, or another price-affecting selection.
* Treat car rental order creation as asynchronous.
* Update generated clients to use the v3.3 schema references.


For car rental order creation, update the response model as follows:

* `booker`;
* `car`;
* `order_token`; and
* payment when required by the selected offer.


**Action:** Update generated clients or schema references to use the v3.3 car creation model. Do not continue importing the v3.2 Beta schema into a v3.3 client.

#### Car order creation response

The car order creation response changes as follows:

| v3.2 | v3.3 | Action |
|  --- | --- | --- |
| `data.car.reservation_id` | `data.car.reservation` | Rename the response property and update stored reservation identifiers. |
| `data.car.status: Processing` | `data.car.status: processing` | Update enum validation and status comparisons to use the lower-case value. |
| /orders/details/cars/live | /orders/details/cars | Update the endpoint used to retrieve the latest car reservation status. |


* See the [Create orders guide](/demand/docs/orders-api/order-preview-create#create-orders) for details.
* See the [Car rental Tutorial](/demand/docs/cars/3.2/cars-tutorial) - For car rental specific orders instructions.


## Order details and reporting

The /orders/details request criteria remain available in v3.3, including retrieval by order ID, reservation ID, date range, and pagination.

Update the following request and response values:

| v3.2 stable | v3.3 stable | Required action |
|  --- | --- | --- |
| `services: taxis` | `services: transfers` | Replace taxis with transfers in request validation and service selection. |
| Response property `taxis` | Response property `transfers` | Rename the response property and update downstream consumers. |
| `cars.payment.timing: pay_partial_online_now` | `cars.payment.timing: pay_partially_online` | Replace the enum value everywhere it is stored, validated, or displayed. |


**Action:** Update any code that reads order details, including:

* Response models.
* Serialisation and deserialisation logic.
* Database mappings.
* Reporting and reconciliation code.
* Traveller-facing status or payment displays.


The /orders/details/accommodations request continues to support retrieval by order ID or reservation ID, with optional currency, extras, and language - Update the API reference to v3.3 and continue using the latest schema.

## Order modifications

Accommodation order modification is not new in v3.3. The v3.3 change is that eligible accommodation orders paid online can be modified through /orders/modify.

Supported changes can include:

* Payment card details.
* Check-in and check-out dates.
* Room configurations.
* Guest allocation.
* Guest names.
* Smoking preferences.


### Preview order modifications

The v3.3 includes a new endpoint, previously available in Beta: /orders/modify/preview.

* Use before /orders/modify when the traveller needs to review whether a change can be applied and understand its expected price impact.
* The preview endpoint is consultative. It does not apply the requested change.


### Modification responses

The v3.3 /orders/modify endpoint supports two response formats:

| Response format | Fields | Integration behaviour |
|  --- | --- | --- |
| Standard | status: successful or failed | Use the overall result when no separate payment status is returned. |
| Detailed | `modification_status`, `payment_status`, and `message`. | Process modification and payment outcomes independently. |


If payment is pending or fails, retrieve the latest order details and present an appropriate next step to the traveller. Do not treat a successful modification status as proof that payment has completed.

### Order cancellation

The /orders/cancel request remains available in v3.3.

## Breaking changes to review

Breaking change

| Area | v3.2 stable | v3.3 stable | Required action |
|  --- | --- | --- | --- |
| Car order creation identifier | `reservation_id` | `reservation` | Rename the response property and update stored identifiers. |
| Car order creation status | `Processing` | `processing` | Update enum validation and status comparisons. |
| Transfer service selection | `taxis` | `transfers` | Update request validation and service selection. |
| Transfer order details | `taxis` | `transfers` | Rename the response property and downstream mappings. |
| Car payment timing | `pay_partial_online_now` | `pay_partially_online` | Replace the enum value everywhere it is consumed. |


## Migration checklist

### Before changing the client

* Confirm that the integration uses Demand API v3.2 stable.
* Compare generated models against the v3.3 Orders API reference.
* Identify code paths that validate service names, statuses, payment timing, or response property names.


### Endpoint and request changes

* Update the Demand API version and API reference links to v3.3.
* Add /orders/modify/preview before /orders/modify where a consultative validation step is required.
* Replace taxis with transfers in /orders/details service criteria.


### Response changes

* Rename reservation_id to reservation in car order creation responses.
* Handle the lower-case processing car order creation status.
* Replace taxis with transfers in order details responses.
* Replace pay_partial_online_now with pay_partially_online.
* Handle both standard and detailed /orders/modify responses.
* Handle unknown and newly introduced enum values safely.


### Integration behaviour

* Re-run /orders/preview when traveller selections change.
* Do not create an order with an expired or stale order_token.
* Do not retry asynchronous car order creation solely because processing is still in progress.
* Do not treat a successful modification preview as confirmation that a change was applied.
* Treat modification and payment statuses as separate outcomes.
* Retrieve the latest order details after a modification, cancellation, or asynchronous booking operation.


## Testing recommendations

Use the [Demand API sandbox](/demand/docs/getting-started/sandbox) to test supported accommodation order flows before switching to production.

The sandbox supports accommodation search, availability, booking, modifications, and cancellations. Car order creation and car cancellation are not available in the sandbox and must be tested in the production environment using the appropriate partner configuration.

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.

Test the following scenarios after migration:

* Preview an accommodation order and create it with the latest valid order_token.
* Confirm that changing dates, rooms, guests, or products requires a new preview.
* Retrieve orders by order ID, reservation ID, date range, and pagination token.
* Confirm that transfer details are read from transfers rather than taxis.
* Preview a supported accommodation modification and confirm that it does not change the order.
* Test successful and failed modifications.
* Test successful, failed, and pending payment statuses.
* Test successful and unsuccessful cancellation requests.


## What’s next

* [Version 3.3 Orders API reference](/demand/docs/open-api/3.3/demand-api/orders) — For complete endpoint schemas and examples.
* [Order details guide](/demand/docs/orders-api/order-details) — For reporting, synchronisation, and order retrieval.
* [Order modification guide](/demand/docs/orders-api/order-modify) — For modifying accommodation orders.
* [Cancellations guide](/demand/docs/orders-api/cancel-order) — For cancelling travel-service reservations.
* [Demand API sandbox](/demand/docs/getting-started/sandbox) — For supported test inventory and sandbox limitations.