Orders create – Migrating to v3.2

Learn how to update your integration to support /orders/create in Demand API v3.2.

Introduction

In v3.2, both accommodation and car orders can be created directly via orders/preview and orders/create.

Quick reference – Breaking changes (v3.2)

Breaking changes

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

Input/output	Area	Change	Impact	Action
Request	Services Beta	Only `accommodation` allowed → `accommodation` or `car` (mutually exclusive)	Sending both will fail.	Validate and send only one travel service per request.
	Car object Beta	Not present → New object with required `driver`	Driver info mandatory.	Any system sending car info must include all required driver fields (`first_name`, `last_name`, `title`, `address`)
	Payment	Deprecated: `payment.card.authentication.3d_secure.cavv`	Any code using this field will break.	Update integration to remove `cavv`
Response	Top-level order ID	Not present → Added `data.order`	Systems reading `accommodation.order` only will fail.	Update integrations to read `data.order`
	accommodation.order	Present → Removed	Any code using this field will break.	Read `data.order` instead.
	Reservation type	Integer → String	May break strict type validations.	Ensure code handles string type.
	Car object Beta	Not present → Added `data.car`	If implementing car rental booking flows, integration must handle car orders.	Check for presence of `data.car` and parse `reservation_id` and `status`

Request examples

{
  "accommodation": {
    "label": "Sample label",
    "products": [
      {
        "id": "333",
        "bed_configuration": "123456",
        "guests": [{"email": "test.name@booking.com","name":"Test Name"}]
      }
    ],
    "remarks": {
      "estimated_arrival_time": {"hour": 12},
      "special_requests": "Extra cot requested"
    }
  },
  "booker": {
    "address": {"address_line":"Road-1, house-2","city":"Amsterdam","country":"nl","post_code":"11111"},
    "company":"Booking B.V",
    "email":"test.name@booking.com",
    "language":"en-gb",
    "name":{"first_name":"Test","last_name":"Name"},
    "telephone":"12345678"
  },
  "order_token": "sample-token",
  "payment": {
    "card": {
      "cardholder": "Test Name",
      "cvc": "111",
      "expiry_date": "2030-10",
      "number": "23333333333333"
    },
    "Include_receipt": true,
    "method": "card",
    "timing": "pay_online_now"
  }
}

✅ Key request breaking changes: Addition of car rental service and mutual exclusivity enforcement.

Response examples

{
  "request_id": "01fr9ez700exycb98w90w5r9sh",
  "data": {
    "accommodation": {
      "order": "509430129718799",
      "pincode": "0000",
      "reservation": 12345678,
      "third_party_inventory": {
        "checkin_number": "123456789",
        "confirmation_number": "12345678912345678912"
      }
    },
    "payment": {
      "receipt_url": "https://secure.booking.com/payment_receipt.html?bn=0000000000&pincode=0000&lang=en"
    }
  }
}

Always check for data.accommodation or data.car depending on order type.
Existing integrations that only expect accommodation must use v3.2 while those handling car rental orders, can test in Beta.
Existing payment handling logic must be adapted to remove payment.card.authentication.3d_secure.cavv.

Migration steps

1. Schema inspection

Retrieve the v3.2 OpenAPI schema if integrating only accommodation /orders/create.
Retrieve the Beta OpenAPI schema for testing purposes, if integrating both accommodation and car rental /orders/create.
Review the new nested structure: accommodation and cars objects.

2. Payload generation

Implement logic for accommodation OR car, never both.
Include label for attribution if needed.

3. Payment

Support airplus, business_information, authorisation_form where required.
Ensure timing and method are provided.
Remove cavv field from card authentication.

4. Response handling

Parse data.accommodation or data.car depending on vertical.
Handle optional authorisation_form_url or receipt_url.

5. Testing

Validate both accommodation and car flows with Beta version.
Check payment authorisation and receipt handling.

6. Monitoring

Log request_id for support/troubleshooting.

What's next

Explore the order/details migration guide.
Read the Orders management overview and use cases.
Check the Troubleshooting guide.
See the Orders v3.2 API reference and v3.2 API reference for details in fields.