# Orders preview – Migrating to v3.2

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

## Introduction

This guide explains what changed in the /orders/preview responses between v3.1 and v3.2  and outlines what your integration needs to do to continue working correctly.

**Key update:** The endpoint returns calculated order details for **both accommodation and car products**, including pricing, policies, and payment schedules.

3.2 Beta
The car rental booking functionality is currently in beta, restricted to members of the pilot programme, and may change in future releases. Refer to this guide for the latest updates.

## Breaking changes

Breaking changes

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

| Breaking change | Description | Version |
|  --- | --- | --- |
| **Multi-service support** | /orders/preview now supports both accommodation and car products. | Beta |
| **Accommodation booker moved** | Nested inside accommodation. | Stable |
| **Car object introduced** | Mutually exclusive with accommodation. Includes search_token + offer. | Beta |
| **Price structure Updated** | `base, charges, display, chargeable_online, total`. | Stable |
| **Monetary fields split** | `display` (traveller-facing) vs `pay`(accounting), with `timing`. | Stable |
| **Car policies structured** | Includes `cancellation, damage_excess, deposit, fuel_policy, mileage, theft_excess`. | Beta |
| **Order token usage** | Still required for /orders/create. | Stable |


## Structural changes

✅ Version 3.2 orders/preview now provides calculated order information for accommodation and car products.

✅ Both travel services include pricing breakdowns, policies, and currency information.

✅ The `data` object contains separate structures for `accommodation` and `car`, enabling unified parsing.

All filters, pricing, and policies are included in the top-level `data` object for easier parsing and unified handling.

### Request differences

Here’s a clear summary of the main differences in the /orders/preview request (input) between v3.1 and v3.2:

#### Accommodation

| Aspect | v3.1 | v3.2 | Notes |
|  --- | --- | --- | --- |
| `booker` location | Top-level object | Nested inside `accommodation` | In v3.2, `booker` info moves inside `accommodation` to allow multiple order types (accommodation or car). |
| Mutual exclusivity | N/A | `accommodation` is **mutually exclusive** with `car` | Schema uses `oneOf` to enforce either car or accommodation. |
| Required fields | `booker` + `accommodation` | `accommodation.id`, `accommodation.booker`, `accommodation.checkin`, `accommodation.checkout`, `accommodation.products` | More explicit in v3.2, reflecting the nested structure. |


#### Car

| Aspect | v3.1 | v3.2 | Notes |
|  --- | --- | --- | --- |
| Car input | Not supported | `car` object introduced | Contains `search_token` and `offer`. **Mutually exclusive** with `accommodation`. Only one can be included per request. |
| Required fields for car | N/A | `search_token` and `offer` | `search_token` comes from `cars/search`; `offer` identifies the selected car offer. |


Ensure requests include either accommodation or car, never both.

### Request examples

v3.1 request

```json
{
  "booker": {
    "country": "nl",
    "platform": "mobile",
    "travel_purpose": "leisure",
    "user_groups": [
      "authenticated"
    ]
  },
  "currency": "EUR",
  "accommodation": {
    "id": 6745031,
    "checkin": "2025-12-10",
    "checkout": "2025-12-13",
    "products": [
      {
        "id": "674503106_275710478_0_2_0",
        "allocation": {
          "number_of_adults": 2,
          "children": [8]
        }
      },
      {
        "id": "674503113_275710486_0_1_0",
        "allocation": {
          "number_of_adults": 1,
          "children": []
        }
      }
    ]
  }
}
```

v3.2 request
Accommodation example in v3.2 now nests booker inside accommodation.


```json
{
  "currency": "EUR",
  "accommodation": {
    "id": 6745031,
    "booker": {
      "country": "nl",
      "platform": "mobile",
      "travel_purpose": "leisure",
      "user_groups": [
        "authenticated"
      ]
    },
    "checkin": "2025-12-10",
    "checkout": "2025-12-13",
    "products": [
      {
        "id": "674503106_275710478_0_2_0",
        "allocation": {
          "number_of_adults": 2,
          "children": [8]
        }
      },
      {
        "id": "674503113_275710486_0_1_0",
        "allocation": {
          "number_of_adults": 1,
          "children": []
        }
      }
    ]
  }
}
```

v3.2-Beta request (car)
Car rentals are now supported in v3.2 Beta using the new car object.

This field is mutually exclusive with accommodation.


```json
{
  "currency": "EUR",
  "car": {
    "search_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "offer": 9876543210
  }
}
```

### Response differences

Key differences from v3.1 responses are:

* **Price structure** - base + charges + display + chargeable_online + total.
* **Monetary fields split** - Split into `display` (traveller-facing) vs `pay` (accounting) with `timing`.
* **Extra charges** - Conditional vs non_conditional.
* **Car policies** - Fully structured with cancellation, damage_excess, deposit, fuel_policy, mileage.
* **Accommodation products** - Include room ID and optional extra charges.


#### Key field mappings (v3.1 -v3.2)

| Field / Path | v3.1 | v3.2 | Notes |
|  --- | --- | --- | --- |
| `request_id` | string | string | No change |
| `data.accommodation.payment` | Array of objects | Object with `dates`, `method_required`, `methods` | Refined structure, check `nullable` fields |
| `data.accommodation.price` | `base`, `total` | `base`, `charges`, `chargeable_online`, `display`, `total` | Unified pricing model |
| `data.car.offer` | Not included | integer | Unique car offer ID |
| `data.car.price` | Not included | `base`, `extra_charges`, `total` | Extra charges split, includes `display`/`pay` |
| `data.car.policies` | Not included | Structured object | Includes cancellation, deposit, fuel_policy, mileage, theft_excess |
| `data.order_token` | string | string | Required for `/orders/create` |


#### v3.2 Accommodation key fields (`data.accommodation`)

| Item | Description |
|  --- | --- |
| ID and Currency | * `id` - Unique accommodation identifier.
* `currency` - ISO 4217 codes for `accommodation` and `booker` currencies.

 |
| `General_policies` | Structured payment schedules for `pay_online_now`, `pay_online_later`, `pay_at_the_property`.* `dates` - Each installment’s charge date and amount.
* `method_required` - Boolean.
* `methods` - Available payment methods (airplus, cards, wallet).

 |
| Price summary | `price` includes:* `base` - Sum base price, excluding extras.
* `chargeable_online` - Amount payable online (null for agency properties).
* `charges` - Each charge’s type, condition, and inclusion in total/display price.
* `display` - Price shown to traveller.
* `total` - Sum including all extra charges.

 |
| Products | Each selected product has `id`, optional `deal`, `inventory`, `policies`, `price`, `room`.* `Deal` info: discount percentage, original price, applied tags.
* `Policies`: cancellation schedule, meal plan.
* `Price` details: base, charges, total.

 |


#### Car response key fields (`data.car`)

| Item | Description |
|  --- | --- |
| Offer and Currency | * `offer` - Car offer ID from cars/search and cars/availability responses. It is needed for orders/create request.
* `currency` - Separate codes for `booker` and `payment` currencies (ISO 4217).

 |
| Price summary | `price:`* `base`: Base price for all selected products.
* `extra_charges`: Conditional and non-conditional extra fees including the `charge_type` and `amount`.
* `total`: Grand total including base and all extra charges.
* All monetary fields split into `display`(traveller-facing) and `pay` (local currency) with `timing`.

 |
| Policies | `cancellation` - Details including context and duration.* `damage_excess`, `deposit`, `fuel_policy`, `mileage`, `payment`, `theft_excess`: Each with detailed amounts, display/pay currencies, and timing.

 |


### Response examples

This is a simplified response for orders/preview in different versions:

v3.1 response

```json
{
  "request_id": "01fr9ez700exycb98w90w5r9sh",
  "data": {
    "accommodation": {
      "id": 6745031,
      "currency": {
        "accommodation": "EUR",
        "booker": null
      },
      "general_policies": {
        "payment": {
          "pay_online_now": {
            "dates": [
              {"at": "2025-11-12", "price": {"accommodation_currency": 177.65, "booker_currency": null}}
            ],
            "method_required": false,
            "methods": {
              "airplus": true,
              "cards": [1, 2, 3],
              "wallet": true
            }
          }
        }
      },
      "price": {
        "base": {"accommodation_currency": 100, "booker_currency": null},
        "chargeable_online": {"accommodation_currency": 100, "booker_currency": null},
        "total": {"accommodation_currency": 123, "booker_currency": null},
        "extra_charges": {
          "conditional": [],
          "non_conditional": [
            {"charge": 142, "chargeable_online": true, "total_amount": {"accommodation_currency": 6, "booker_currency": null}},
            {"charge": 21, "chargeable_online": false, "total_amount": {"accommodation_currency": 14.67, "booker_currency": null}}
          ]
        }
      },
      "products": [
        {
          "id": "1000420_278556531_2_0_0",
          "deal": null,
          "inventory": {"third_party": false, "type": "sell"},
          "policies": {
            "cancellation": [
              {"from": "now", "price": {"accommodation_currency": 0, "booker_currency": null}},
              {"from": "2025-11-10T22:00:00+00:00", "price": {"accommodation_currency": 177.65, "booker_currency": null}}
            ],
            "meal_plan": {"meals": [], "plan": "no_plan"}
          },
          "price": {
            "base": {"accommodation_currency": 155.96, "booker_currency": null},
            "chargeable_online": {"accommodation_currency": 186.92, "booker_currency": null},
            "extra_charges": {
              "conditional": [],
              "non_conditional": [
                {"charge": 142, "mode": "per_person_per_night", "total_amount": {"accommodation_currency": 6, "booker_currency": null}, "unit_amount": 3}
              ]
            },
            "total": {"accommodation_currency": 186.92, "booker_currency": null}
          },
          "third_party_inventory": false
        }
      ],
      "order_token": "your_order_token_here"
    }
  }
}
"""
```

v3.2 response

```json
{
  "request_id": "123e4567-e89b-12d3-a456-426614174000",
  "data": {
    "accommodation": {
      "id": "acc_001",
      "currency": {
        "accommodation": "EUR",
        "booker": "EUR"
      },
      "products": [
        {
          "id": "prod_001",
          "deal": {
            "discount_percentage": 10,
            "tags": ["black_friday"]
          },
          "inventory": {
            "third_party": false,
            "type": "sell"
          },
          "policies": {
            "cancellation": [
              {
                "from": "2025-11-10T12:00:00Z",
                "price": {
                  "accommodation_currency": 50,
                  "booker_currency": 50
                }
              }
            ],
            "meal_plan": {
              "plan": "breakfast_included",
              "meals": ["breakfast"]
            }
          },
          "price": {
            "base": {
              "accommodation_currency": 100,
              "booker_currency": 100
            },
            "total": {
              "accommodation_currency": 120,
              "booker_currency": 120
            }
          },
          "room": "room_101"
        }
      ]
    },
    "car": {
      "offer": 987654321,
      "currency": {
        "booker": "EUR",
        "payment": "EUR"
      },
      "price": {
        "base": {
          "display": {
            "value": 129.99,
            "currency": "EUR",
            "timing": "pay_at_pickup"
          },
          "pay": {
            "value": 129.99,
            "currency": "EUR",
            "timing": "pay_at_pickup"
          }
        },
        "extra_charges": {
          "conditional": [
            {
              "charge_type": "one_way_fee",
              "amount": {
                "display": { "value": 15, "currency": "EUR", "timing": "pay_at_pickup" },
                "pay": { "value": 15, "currency": "EUR", "timing": "pay_at_pickup" }
              }
            }
          ],
          "non_conditional": [
            {
              "charge_type": "state_sales_tax",
              "amount": {
                "display": { "value": 10, "currency": "EUR", "timing": "pay_at_pickup" },
                "pay": { "value": 10, "currency": "EUR", "timing": "pay_at_pickup" }
              }
            }
          ]
        },
        "total": {
          "display": { "value": 154.99, "currency": "EUR", "timing": "pay_at_pickup" },
          "pay": { "value": 154.99, "currency": "EUR", "timing": "pay_at_pickup" }
        }
      },
      "policies": {
        "cancellation": { "type": "free_cancellation" },
        "fuel_policy": "return_same",
        "deposit": {
          "amount": {
            "display": { "value": 200, "currency": "EUR", "timing": "pay_at_pickup" },
            "pay": { "value": 200, "currency": "EUR", "timing": "pay_at_pickup" }
          }
        }
      }
    },
    "order_token": "token_abc123"
  }
}
```

> ![genius-bulb](/assets/genius-bulb.3e13976eeeabd0526f1d76bfb7de5967932211a5ef4afe526a3b0a71a7b02fb0.5e2a7131.png) Use this simplified response for integration tests and parsing logic verification.


## Migration guide – Steps

### 1. Inventory & schema discovery

- Pull the current v3.2 OpenAPI schema for /orders/preview and inspect the `data[]` object.


### 2. Pricing model

- Use `display` prices for traveller-facing UI and `pay` (cars) for accounting.
- Handle nullable fields (`chargeable_online, room, payment.dates`).


### 3. Car policies

- Policies are now structured; existing v3.1 flat fields must be mapped to objects.
- Add handling for `theft_excess`, `fuel_policy`, and `mileage` fields.


### 4. Currency consistency

- Update logic for `display` vs `pay` (in cars) split.


### 5. Feature updates

- Add support for the car `label` field in analytics/attribution pipelines.
- Add support for `accommodations.location` and `cars` objects where relevant.


### 6. Order Token

- Ensure `order_token` is used in subsequent orders/create requests.


### 7. Testing

- Run integration tests with sample v3.2 responses (include edge cases: missing `offer` in car object,  missing `booker` information in accommodation).
- Validate monetary rounding rules when converting between currencies.


### 7. Rollout

- Release with both new and deprecated parsing for a short transition window; after verifying data is correct, remove deprecated-path code.


## Migration checklist

| Checklist | Action | Notes |
|  --- | --- | --- |
| ☑ | Update currency handling `currency.booker / currency.accommodation` (accommodation) and `currencies.booker / currency.payment`(car) | Use booker for UI/display and payment/accommodation for accounting. |
| ☑ | Update parsing of `price` objects. | Handle `base`, `charges`, `extra_charges`, `display`, `chargeable_online`, and `total` for both accommodation and car products. |
| ☑ | Update front-end totals calculations | Use `booker_currency` values for `display` amounts (unless you intentionally display product currency). |
| ☑ | Add parsing logic for new objects. | `car` → includes price, policies, offer and `accommodation` → includes products, room, payment.dates. |
| ☑ | Support `label` for cars. | For partner attribution in reporting and analytics pipelines. |
| ☑ | Update order creation requests to include `order_token` returned by orders/preview. | Required |


Stop relying on deprecated flat fields. Update parsing of multi-currency structures to avoid issues when v3.2 is enforced.

## What's next

* Complete booking v3.2 updates in [/orders/creation migration guide](/demand/docs/migration-guide/v3.2/orders/create).
* Check the [Orders create guide](/demand/docs/orders-api/order-preview-create) for step-by-step instructions on how to create orders.
* 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.