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

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

{
  "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": []
        }
      }
    ]
  }
}

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:

{
  "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"
    }
  }
}
"""

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.
Check the Orders create guide for step-by-step instructions on how to create orders.
Refer to v3.2 Orders API reference for details in fields.
Contact your Booking.com technical account manager for migration support.