# Migrate your Car rentals integration **This guide outlines the key architectural, design, and functional differences between the legacy XML API and the new Car Rental API collection in Demand API. Use it to plan and execute your integration 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. If you require full booking functionality through our API, this feature is not yet available. Please contact your Account Manager to express your interest, and we will keep you informed about future developments. ## 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: | Key differences | Description | | --- | --- | | Data format | The Demand API uses JSON instead of XML, and it has a lighter weight and easier parsing for modern systems. | | Separate endpoints | Supplier and depot information is now provided through separate endpoints, rather than being embedded in search results. ✓ This change allows you to access more detailed information upfront, but requires you to refresh the cache daily. * **Supplier IDs**: Each supplier[1](#myfootnote2) now has a unique ID, which was previously unavailable. * **Depot IDs**: The depot ID now specifies the exact location where the vehicle is picked up, e.g. Avis at Manchester Airport. * Previously, location information was provided at a broader level (e.g. Manchester Airport). | | Clickout URL | Your clickout URL now redirects to Booking.com instead of Rentalcars.com. | | Pagination | The results are [paginated](/demand/docs/development-guide/pagination), meaning you may need to perform multiple requests to retrieve all possible results. | 1 Multiple instances of the same supplier may appear if they are registered under different legal entities (e.g. in different regions) but share the same trading name. See an [example of supplier ID differences here](/demand/docs/cars/retrieve-car-details#different-supplier-ids) ### Authentication Following the same authentication strategy as the one applied to the accommodation endpoints, each request to the [Demand API - Car endpoints](/demand/docs/open-api/demand-api/cars) must identify a valid API user. The user authentication is a combination of your affiliate ID and token. Important Please note that your XML API credentials will not be valid for the Demand API, and new credentials will need to be generated. 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 curl --request POST 'https://demandapi.booking.com/3.1/search' \ --header 'X-Affiliate-Id: 123456' \ --header 'Authorization: Bearer xyz.........xyz' \ --data-raw '{ "booker": { "country": "nl" }, ... }' ``` For more details on authentication, see the [Authentication and authorisation](/demand/docs/development-guide/authentication) section. ## 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 store 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: ```json { "languages": [ "en-gb", "es", "ar", "zh-cn" ] } ``` * The /common/languages endpoint provides a list of all supported language codes. * These codes follow the IETF language tag format, which uniquely identifies a language or dialect. ## 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: ```json { "url": { "app": "booking://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" } } ``` If you wish to use a different ID than the one provided in the request, you can modify the affiliate ID in the URL before redirecting it to Booking.com. ### Use of labels A `Label` in Demand API is a user-defined string used to: * Associate a car reservation with a specific campaign. * Together with the affiliate ID it helps 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. Refer to the [Labels and attribution guide](/demand/docs/orders-api/labels-attributions) for examples and best practices. ## 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: ```json { "request_id": "01jj6wbtrxge406v4mw5jmj42f", "errors": [ { "id": "invalid_parameter", "message": "Parameter 'pickup.datetime' is invalid. 'pickup.datetime' must be before 'dropoff.datetime'." } ] } ``` Find in the Error Handling section further examples. ## Designing your integration The new Demand API [Car Rental endpoints](/demand/docs/open-api/demand-api/cars) 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 | | Feature | XML API | Demand API | | **Protocol** | https:// | https:// | | **Production URL** | https://xml.rentalcars.com/service/ServiceRequest.do | https://demandapi.booking.com/3.1/search | | **Testing URL** | https://xmlsandbox.rentalcars.com/service/ServiceRequest.do | N/A | | **Authentication** | Affiliate code (username) and password | Bearer token + affiliate ID | | **Request method** | POST | POST | | **Response format** | XML | JSON | ### 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 XML API ```XML Fiat 500 https://cdn.rcstatic.com/images/car_images/web/fiat/500_lrg.jpg https://cdn.rcstatic.com/images/car_images/web/fiat/500_lrg.jpg ``` Demand API → Use the [car/search endoint](/demand/docs/open-api/demand-api/cars/search) to look for car rental options - The response returns the available car `id`: ```json { "request_id": "01h00fr9y7qkbxtc6kyv97j49z", "data": [ { "car": 122655, "policies": { "cancellation": { "type": "free_cancellation", "details": { "context": "before_pickup", "duration": "P7D" } } } } ] } ``` → Use the [/cars/details endpoint](/demand/docs/open-api/demand-api/cars/details) to return the full car details associated to each car `id`. ```json { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": [ { "id": 122655, "capacity": { "bags": { "large": 1, "small": 1 }, "doors": "4/2", "seats": "4+2" }, "features": [ "air_conditioning", "all_wheel_drive" ], "image": "https://example.com/image.jpg", "make": "hyundai", "model": "elantra", "specification": { "code": "ECAR", "description": "economy", "fuel": "petrol", "transmission": "automatic" }, "supplier": 423 } ], "metadata": { "next_page": null } } ``` #### Deposit and damage excess XML API ```XML ``` Demand API Fuel and mileage policies are returned in [/search](/demand/docs/open-api/demand-api/cars/search) response: ```json { "request_id": "01h00fr9y7qkbxtc6kyv97j49z", "data": [ { "car": 122655, "policies": {...} }, "fuel": "return_same", "mileage": { "distance": 200, "distance_unit": "kilometers", "fee": 12.54, "type": "limited" }, ... ``` #### Total price and currency XML API ```XML <Price currency="EUR" baseCurrency="GBP" basePrice="465.8" commission="0.00" discount="0.00" driveAwayPrice="563.92" quoteAllowed="yes" creditCardRequired="false"> 563.92 </Price> ``` Demand API Total price and currency is returned in [/search](/demand/docs/open-api/demand-api/cars/search) response: ```json { "request_id": "01h00fr9y7qkbxtc6kyv97j49z", "data": [ { "car": 122655, "policies": {...} }, "fuel": "return_same", "mileage": {...}, "payment": {...} }, "price": { "total": "50.00", "currency": "EUR" }, ... ``` #### Depot XML API ```XML <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> ``` Demand API Find the `depot id` within the `route.dropoff` and `route.pickup` fields in the search response: ```json { "request_id": "01h00fr9y7qkbxtc6kyv97j49z", "data": [ { "car": 122655, "policies": {...} }, "fuel": "return_same", "mileage": {...}, "payment": {...} }, "price": {...}, "route": { "dropoff": { "depot": 112314 }, "pickup": { "depot": 112314 } }, ... ``` To retrieve the depot information, you can either: * Query the [/cars/depots endpoint](/demand/docs/open-api/demand-api/cars/depots) passing the depot `id`. * Or retrieve it from your cache. #### Supplier XML API ```XML ``` Demand API Supplier name and logo can be retrieved using the supplier `id` via the [/cars/suppliers](/demand/docs/open-api/demand-api/cars/suppliers) endpoint: ```json { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": [ { "id": 62, "name": "Budget", "logo": "https://example.com/path_to_the_logo.jpeg" } ], "metadata": { "next_page": null, "total_results": 1 } } ``` * The supplier depot's coordinates and instructions are available via the [/cars/depots](/demand/docs/open-api/demand-api/cars/depots) endpoint. #### Scores XML API ```XML 7.1 Very good 126 6.7 7.8 7.3 8.2 7.5 5.8 7.5 ``` Demand API Use the [/cars/depots/reviews/scores endpoint](/demand/docs/open-api/demand-api/cars/depots/reviews/scores) to return the depot score breakdown together with the overall number of reviews and score: ```json { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": [ { "id": 5944, "breakdown": { "cleanliness": { "score": 8.7 }, "condition": { "score": 8.7 }, "drop_off_speed": { "score": 8.7 }, "friendliness": { "score": null }, "likeliness_rent_again": { "score": 8.7 }, "location": { "score": 8.7 }, "pick_up_speed": { "score": 8.7 }, "value_for_money": { "score": 8.7 } }, "number_of_reviews": 105, "score": 9.1 } ], "metadata": { "next_page": null } } ``` #### URL XML API ```XML https:/rentalcars.com/SearchResults.do...... ``` Demand API Find the `url` for both web and app within the [/search endpoint](/demand/docs/open-api/demand-api/cars/search) response: ```json { "url": { "app": "booking://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" } } ``` ## Testing your integration Demand API does not currently offer a dedicated sandbox environment for Car rentals. We recommend using your affiliate credentials in a controlled environment with limited real traffic for initial testing. Contact your Account Manager if you require assistance. ## Migration Checklist | Checklist | | --- | | ☑ | From the [Partner Centre](https://spadmin.booking.com/partner/login-v3.html) you have generated: * A [valid API key](/demand/docs/development-guide/authentication/#api-key-management) that allows you to use the endpoints. * A unique identifier id (`X-Affiliate-Id`) that identifies your requests. | | ☑ | Update authentication mechanism (Bearer + Affiliate ID). | | ☑ | Implement new endpoints (search, details, common/supplier, etc.) | | ☑ | Introduce daily caching for static data. | | ☑ | Update clickout and tracking logic. | | ☑ | Validate label usage and reporting. | | ☑ | Review error handling implementation. | 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. Curious to know more? * Explore the [Try out section](/demand/docs/cars/cars-quick-guide) for a comprehensive, step-by-step guide. * For examples and best practices check the dedicated [cars endpoints section](/demand/docs/cars/retrieve-car-details)