MIGRATION GUIDES
/
v3.2 Migration
/
Orders endpoints
/
/orders/create
Last updated

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.

3.2 Beta

The car rental booking functionality is currently available only in beta. This is still under active development and restricted only to members of the early access pilot programme. Contact your Booking Account Manager for details.

  • Note this integration may change in future releases. Follow up this guide for the latest updates.

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
ChangeImpactAction
RequestServices BetaOnly 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)

PaymentDeprecated: payment.card.authentication.3d_secure.cavvAny code using this field will break.Update integration to remove cavv
ResponseTop-level order IDNot present → Added data.orderSystems reading accommodation.order only will fail.Update integrations to read data.order
accommodation.orderPresent → RemovedAny code using this field will break.Read data.order instead.
Reservation typeInteger → StringMay break strict type validations.Ensure code handles string type.
Car object BetaNot present → Added data.carIf 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 v3.2 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 v3.2 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. (Note: Special access is needed. Contact your Booking Account Manager for details.)
  • Check payment authorisation and receipt handling.

6. Monitoring

  • Log request_id for support/troubleshooting.

What's next

Previous page
Next page