# Orders modify – Migrating to v3.2

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

## Introduction

The /orders/modify endpoint allows partners to update specific aspects of existing accommodation orders — for example, to adjust guest details, change dates, update room allocations, or modify payment details.

This guide explains the changes introduced in **Demand API v3.2** for the /orders/modify endpoint compared to v3.1, and how to update your integration accordingly.

## Breaking changes

Breaking changes

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

| Area | Change | Description |
|  --- | --- | --- |
| **Identifiers** | Data type change. | All reservation-related IDs (`reservation`, `room_reservation`) must now be sent as **strings** instead of numeric values. |
| **PaymentModification** | Field requirement change. | The `order` field is **no longer required** for PaymentModification objects. |


## Overview of all updates

| Change area | Summary |
|  --- | --- |
| **Type consistency** | Several fields now use `string` instead of `integer` or `long` for better cross-language compatibility. |
| **Required fields** | The `order` field requirement has been relaxed for `PaymentModification` objects. |
| **Validation** | v3.2 enforces stricter type validation for `reservation` and `room_reservation` IDs. |
| **No structural changes in responses** | The overall schema structure, request patterns, and response format remain backward-compatible. |


## Request schema changes

### Identifier type alignment

In **v3.1**, several ID fields were typed as `integer` or `long`.

In **v3.2**, all IDs are now `strings` fields to ensure cross-language consistency and prevent numeric precision issues.

| Field path | v3.1 type | v3.2 type | object |
|  --- | --- | --- | --- |
| `modification.accommodation.reservation` | integer | string | `AccommodationModification` |
| `modification.accommodation.change.room_reservation` | long | string | `RoomChange` |


**Action required**

* Update your integration to send these identifiers as **strings** rather than numeric values.
* If your system currently serialises these as numbers, ensure conversion before making the API request.


### Updated required fields for PaymentModification

In **v3.1**, the `order` field was required at the top level of all modification types.

In **v3.2**, it remains required for `AccommodationModification`, but is **now optional** for `PaymentModification`.

| Object | v3.1 required fields | v3.2 required fields |
|  --- | --- | --- |
| `PaymentModification` | `order`, `modification` | `modification` only |


**Action required**

* If your integration always sends `order` for Payment modifications, you can safely continue to include it — the field will be ignored if redundant.
* However, ensure your schema or validation rules (if any) do not enforce it as mandatory for payment modifications.


### Validation tightening

v3.2 enforces **stricter data validation** on ID and date fields.

Make sure your integration complies with the following:

* `checkin` and `checkout` must use `YYYY-MM-DD` format.
* `expiry_date` for card details must follow `YYYY-MM`.
* `accommodation.type` must be either `dates` or `room`.


Sending numeric values where strings are expected will result in validation errors.

### Example request comparison

v3.1 request

```json
{
  "order": "12345",
  "modification": {
    "accommodation": {
      "reservation": 67890,
      "type": "dates",
      "change": {
        "checkin": "2025-07-01",
        "checkout": "2025-07-03"
      }
    }
  }
}
```

v3.2 request

```json
{
  "order": "12345",
  "modification": {
    "accommodation": {
      "reservation": "67890",
      "type": "dates",
      "change": {
        "checkin": "2025-07-01",
        "checkout": "2025-07-03"
      }
    }
  }
}
```

## Response schema changes

The 200 response remains structurally unchanged.
Both modification types (`AccommodationModificationResponse` and `PaymentModificationResponse`) remain structurally identical between v3.1 and v3.2.

However:

* Response validation now expects consistent data types — for example, price and status objects follow stricter type enforcement.
* The `status` field continues to accept only `successful` or `failed` values.


Example (unchanged response):


```json
{
  "modification": {
    "accommodation": {
      "new_price": 245.50,
      "status": "successful"
    }
  }
}
```

## Implications for migration

### Breaking changes:

* All reservation-related IDs (reservation, room_reservation) must be sent as strings. Sending numeric values will fail validation.
* Omitting order in PaymentModification is now allowed; any integration schema validation should be updated accordingly.


### Non-breaking changes:

* Response handling does not need to change.
* All other fields can remain as-is.


## Migration checklist

| Checklist | Action |
|  --- | --- |
| ☑ | Convert all numeric IDs (`reservation`, `room_reservation`) to strings. |
| ☑ | Verify date formats use ISO 8601 (`YYYY-MM-DD` for stay dates, `YYYY-MM` for expiry). |
| ☑ | Adjust internal schema validation for `PaymentModification` to allow missing `order` field. |
| ☑ | Test both accommodation and payment modification flows in the sandbox environment with test hotels. |
| ☑ | Validate error handling for invalid data types and formats. |


## Testing and validation

Before deploying to production, confirm the following through sandbox testing:

* At least one accommodation modification (date or room)
* One payment modification (card details update)
* Error handling for invalid ID types and date formats. See the [Error handling guide](/demand/docs/support/error-handling/error-codes).


Once these tests pass, your integration is fully compatible with Demand API v3.2.

## What's next

* Track the overall v3.2 updates in [Orders migration guide](/demand/docs/migration-guide/v3.2/orders/intro).
* Check the [Orders modify guide](/demand/docs/orders-api/order-preview-create) for step-by-step instructions.
* Refer to [v3.2 Orders API reference](/demand/docs/open-api/3.2/demand-api) for details in fields.
* Contact your Booking.com technical account manager for migration support.