# Orders cancel – Migrating to v3.2

**Detailed guide for integrating /orders/cancel with Demand API v3.2.**

## Introduction

This guide describes the structural and validation changes introduced in **v3.2** for the /orders/cancel endpoint.

Version 3.2 introduces **explicit multi-travel service support** and refined validation, replacing the flat v3.1 schema. Existing integrations must update their request bodies to align with the new nested structure.

## Breaking changes

Breaking changes

The following v3.1 fields are deprecated or replaced in v3.2 /orders/cancel endpoint. Update your integration to avoid disruption.

| v3.1 field | v3.2 replacement | Impact | Notes / migration action |
|  --- | --- | --- | --- |
| `order` | `accommodation.order` | ⚠️**Breaking** | Move under the `accommodation` object for accommodation cancellations. |
| `reason` | `accommodation.reason` | ⚠️ **Breaking** | Same purpose; nested under `accommodation`. |
| `request_property_approval` | `accommodation.request_property_approval` | ⚠️**Breaking** | Renamed and relocated inside the `accommodation` object with refined description. (This is part of "Cancel for less" functionality) |


### Example – orders/cancel request

#### For an accommodation reservation

v3.1 request

```json
{
  "order": "509430129718799",
  "reason": "I would like to book another property instead of this one.",
  "request_property_approval": "true"
}
```

v3.2 request

```json
{
  "accommodation": {
    "order": "509430129718799",
    "reason": "I would like to book another property instead of this one.",
    "request_property_approval": "true"
  }
}
```

### Key differences

| Change | v3.1 | v3.2 |
|  --- | --- | --- |
| Request body structure | Flat (no travel service distinction) | Nested by travel service: `accommodation` |
| Product type support | Accommodation only (implicit) | Accommodation (explicit) |
| Field naming | Generic (`order` identifier, `reason` for cancellation) | Scoped per travel service. |
| Validation | Only `order` and `reason` required | Additional per-travel service required fields. |


### Example - orders/cancel response

#### For v3.1 and v3.2


```json
{
  "request_id": "01fr9ez700exycb98w90w5r9sh",
  "data": {
    "status": "successful"
  }
}
```

(*Response structure remains unchanged*)

## Non-breaking improvements

**Multi-travel service readiness** - Unified structure prepares for future travel services beyond accommodation.

## Deprecations

The following fields are deprecated in **v3.1** and should be replaced with their updated equivalents.

| Deprecated field | Status | Replacement field |
|  --- | --- | --- |
| `order` (top level) | Deprecated | `accommodation.reservation` |
| `reason` (top level) | Deprecated | `accommodation.reason` |
| `request_property_approval` (top level) | Deprecated | `accommodation.request_property_approval` |


## Example migration workflow (step-by-step)

### 1. Schema inspection

- Retrieve the v3.2 OpenAPI schema for /orders/cancel.
- Review the new nested structure: `accommodation` and `cars` objects.


### 2. Update backend payload generation

- Replace top-level fields with the nested format.
- Map old fields:
  * `order` → `accommodation.reservation`
  * `reason` → `accommodation.reason`
  * `request_property_approval` → `accommodation.request_property_approval` (This is needed for the "Cancel for less" functionality - [See guide for details](/demand/docs/orders-api/3.2/cancel-for-less))


### 3. Validation logic

- Ensure required fields are respected per travel service:
  - `accommodation`: `reservation`, `reason`


### 4. Response handling

- Keep existing success/failure handling logic; response structure unchanged.


### 5. Testing

- Test accommodation example using [Sandbox environment and testing properties](/demand/docs/getting-started/sandbox).
- Validate failure cases for missing required fields and invalid enum values.


### 6. Deployment

- Release with updated request format.
- Verify production logs for successful cancellations across supported travel services.


## Migration checklist

| Checklist | Action | Notes |
|  --- | --- | --- |
| ☑ | Wrap all existing accommodation cancellations inside the `accommodation` object. | Ensures correct nesting and alignment with v3.2 schema. |
| ☑ | Remove top-level `order`, `reason`, and `request_property_approval` fields. | Avoids conflicts with nested structure and deprecated fields. |
| ☑ | Update internal models, DTOs, and schema validators. | Reflect new nested structure for accommodation. |
| ☑ | Run end-to-end tests with sample accommodation payloads. | Confirm correctness, including edge cases for fees and optional fields. |


## Migration notes & tips

- **Breaking format change** - Requests must now use a nested travel service structure.
- **Dual-read period** - Maintain backward compatibility temporarily by checking both the old and new structures if necessary.
- **Validation** - Enforce strict required fields to prevent 400 responses.


## What's next

* Explore the [Handling cancellations guide](/demand/docs/orders-api/cancel-order) for a quick guide.
* Read the [Orders management overview](/demand/docs/orders-api/overview) and use cases.
* Check the [Troubleshooting guide](/demand/docs/messaging/messaging-troubleshooting).
* Refer to [v3.2 Orders API reference](/demand/docs/open-api/3.2/demand-api/orders) for details in fields.
* Contact your Booking.com technical account manager for migration support.