Migration Guide for Car partners integrating with Demand API

This guide provides a summary of key architectural, design, and functional differences between the legacy XML API and the new Car Rental service in the Demand API. It is designed to assist you in planning your migration.

The new Car Rental endpoints in the Demand API are designed to facilitate the "Search" part of the traveller experience.

These endpoints allow you to redirect travellers to the Booking.com/cars website to complete their bookings.

This migration guide outlines the essential changes and helps you transition from the legacy system to the new API and associated processes.

Key differences between XML and Car Demand API

API architecture and design

The new Car Rental service under Demand API introduces a modular architecture, replacing the legacy XML-based design.

This transition offers several advantages, including improved performance, enhanced features, and a more efficient user experience.

The key changes you should be aware of before migrating include:

Authentication

Following the same authentication strategy as the the one applied to the accommodation endpoints, each request to the Demand API - Car endpoints must identify a valid API user. The user authentication is a combination of your affiliate ID and token.

To start using Demand API - Car endpoints, follow these steps:

1. Generate an API key - This is done via the Affiliate Partner Centre.

2. Include the API key in requests

• Every request must include your API key (token) and the appropriate affiliate ID in the header.
• The API key acts as a secure way to identify your requests, replacing the older method of sending username and password in the request.

Example request:

curl --request POST 'https://demandapi.booking.com/3.1/cars/search' \
  --header 'X-Affiliate-Id: 123456' \
  --header 'Authorization: Bearer xyz.........xyz' \
  --data-raw '{
    "booker": {
      "country": "nl"
    },
    ...
  }'

Endpoint caching

In the Demand API, static data is decoupled from dynamic data, enabling more efficient caching of static information.

We strongly recommend caching relevant endpoints and refreshing the cache daily to improve performance, while ensuring that the information stays up-to-date and to avoid serving stale data to users.

If you do not cache static data, you will need to call the relevant endpoints whenever that data is required. This includes obtaining necessary codes or IDs for request parameters and processing response fields.

Benefits of caching:

✓ Reduces repeated calls to the API.

✓ Improves performance and response times.

✓ Reduces the likelihood of hitting rate limits.

Multilingual support

The Demand API now supports multiple languages in a single request.

If your application needs to support several languages, this feature can reduce the number of calls needed to retrieve content.

Language request field

Instead of the preflang field in the XML API, the Demand API uses a new languages request field.

• You can specify an array of language codes in the request to receive the response in multiple languages.
• For example, to receive response data in British English, Spanish, Arabic, and Chinese, specify the following in your request:

{
    "languages": [
        "en-gb",
        "es",
        "ar",
        "zh-cn"
    ]
}

Redirecting to Booking.com and Affiliate ID tracking

In the Demand API, partners traffic is tracked using the X-Affiliate-Id header instead of the username used in the XML API.

Each car search result includes a link to Booking.com/cars, allowing travellers to complete their booking.

• The URL automatically includes the affiliate ID provided in the request header for reporting and attribution purposes.
• The affiliate ID is appended to the URL as a query parameter (aid).

Example of URL with affiliate ID:

{
  "url": {
    "app": "booking://cars/search?affiliate_id=956509&driver_age=21&do_time=2025-11-09T12:00&pu_time=2025-11-02T12:00&do_loc_iata=CDG&pu_loc_iata=CDG",
    "web": "https://cars.booking.com/search-results?vehicleId=737843316&aid=956509&prefcurrency=EUR&preflang=en"
  }
}

Use of labels

A Label in Demand API is a user-defined string used to:

• Associate a car or accommodation reservation with specific campaign.
• Help with reporting, filtering, and attribution purposes.

It serves as a tracking mechanism, similar to the adplat and adcamp values in the XML API, but instead of those, you must pass the label when creating a reservation.

You can later verify the label (together with the affiliate id) using the /orders/details/cars endpoint.

Error handling

The error handling process has changed between the XML API and the Demand API.

Our Demand API now returns HTTP error status codes (e.g., 4xx for client-side errors, 5xx for server-side errors), along with detailed error messages in the response body.

Example of error response:

{
  "request_id": "01jj6wbtrxge406v4mw5jmj42f",
  "errors": [
    {
      "id": "invalid_parameter",
      "message": "Parameter 'pickup.datetime' is invalid. 'pickup.datetime' must be before 'dropoff.datetime'."
    }
  ]
}

Designing your integration

The new Demand API Car Rental endpoints and the legacy XML API have significant design differences.

• You should not assume a one-to-one mapping between input parameters or output fields.

• You will now need to call multiple endpoints to gather the information that was previously returned in a single search request. However, by caching static data from these endpoints, you can improve response times.

Endpoint structure comparison

Mapping information

The data you previously received in the SearchRS of the XML API is now returned as a combination of static and dynamic data.

Refer to the tabs below to understand the migration path for your integration.

Car details

<MatchList>
  <Match>
    <Vehicle 
      id="728723191" 
      propositionType="BR" 
      automatic="Manual" 
      aircon="Yes" 
      airbag="true" 
      petrol="N/A" 
      group="MBMR" 
      doors="2" 
      seats="4" 
      bigSuitcase="1" 
      smallSuitcase="1" 
      suitcases="N/A" 
      fuelPolicy="1" 
      cmaCompliant="true" 
      insurancePkg="I" 
      display="true" 
      order="0" 
      freeCancellation="true" 
      unlimitedMileage="false">
      
      <Name>Fiat 500</Name>
      <ImageURL>https://cdn.rcstatic.com/images/car_images/web/fiat/500_lrg.jpg</ImageURL>
      <LargeImageURL>https://cdn.rcstatic.com/images/car_images/web/fiat/500_lrg.jpg</LargeImageURL>
    </Vehicle>
  </Match>
</MatchList>

Deposit fees

</Vehicle>
<Fees>
  <DepositExcessFees>
    <TheftExcess 
      amount="1500.0" 
      currency="GBP" 
      taxIncluded="true" />
    <DamageExcess 
      amount="1500.0" 
      currency="GBP" 
      taxIncluded="true" />
    <Deposit 
      amount="1500.0" 
     

Fuel and mileage policies

<FuelPolicy type="RETURN_SAME" />
<KnownFees>
  <Fee 
    feeTypeName="MILEAGE" 
    alwaysPayable="false" 
    amount="0.5" 
    currency="GBP" 
    taxIncluded="true" 
    perDuration="rental" 
    feeDistance="1.0" 
    distance="700.0" 
    iskM="false" 
    unlimited="false" />
</KnownFees>
</Fees>

Total price and currency

<Price 
  currency="EUR" 
  baseCurrency="GBP" 
  basePrice="465.8" 
  commission="0.00" 
  discount="0.00" 
  driveAwayPrice="563.92" 
  quoteAllowed="yes" 
  creditCardRequired="false">
  563.92
</Price>

Depot

<Route>
  <PickUp>
    <Location 
      id="4608557" 
      locationId="37766" 
      locCode="LHR" 
      locName="London Heathrow Airport" 
      onAirport="no" />
  </PickUp>
  <DropOff>
    <Location 
      id="4608557" 
      locationId="37766" 
      locCode="LHR" 
      locName="London Heathrow Airport" 
      onAirport="no" />
  </DropOff>
</Route>

Supplier

<Supplier 
  long="-0.39796924" 
  lat="51.47040086" 
  dropOffLong="-0.39796924" 
  dropOffLat="51.47040086" 
  address="Vista Centre Salisbury Road, Cranford, Hounslow, London, UK, TW4 6JQ" 
  dropOffAddress="Vista Centre Salisbury Road, Cranford, Hounslow, London, UK, TW4 6JQ&quot;" 
  small_logo="https://cdn2.rcstatic.com/images/suppliers/wrp/flat/1463_logo_lrg.gif" 
  locType="Off Airport - Shuttle Service" 
  supplierName="Surprice" 
  pickUpInstructions="Please call 00443300949033 on arrival to arrange the shuttle service. Then, follow the signs to the Short Stay Car Park and wait at the corresponding level. T2: Level 4, lift area near row H. T3: Level 3, lift area near row A. T4: Level 2, lift area near row E. T5: Level 1, lift area near row R." 
  dropOffInstructions="Please call 00443300949033 on arrival to arrange the shuttle service. Then, follow the signs to the Short Stay Car Park and wait at the corresponding level. T2: Level 4, lift area near row H. T3: Level 3, lift area near row A. T4: Level 2, lift area near row E. T5: Level 1, lift area near row R." />

Scores

<![CDATA[Surprice (Flex)]]>
</Supplier>

<Ratings>
  <Average>7.1</Average>
  <AverageText>Very good</AverageText>
  <NumRatings>126</NumRatings>
  <ValForMoney>6.7</ValForMoney>
  <Efficiency>7.8</Efficiency>
  <CollectTime>7.3</CollectTime>
  <DropOffTime>8.2</DropOffTime>
  <Cleanliness>7.5</Cleanliness>
  <Condition>5.8</Condition>
  <Locating>7.5</Locating>
</Ratings>

URL

<ForwardURL>https:/rentalcars.com/SearchResults.do......</ForwardURL>

By following these guidelines and making the necessary adjustments, you can smoothly transition to the new Demand API and continue to offer an efficient Car Rental search experience to your customers.