# Migrate from XML to Demand API v3.2 **Use this guide to migrate your existing Rentalcars XML API integration to Demand API v3.2. Review the main architecture, authentication, data, endpoint, and integration-flow changes required for your migration.** ## Migration overview Migrating from the Rentalcars XML API to Demand API v3.2 requires changes to how your application authenticates, retrieves and stores data, processes responses, and implements traveller flows. Key migration changes include: * Replacing XML requests and responses with JSON. * Moving from a single XML service to specialised Demand API endpoints. * Replacing XML credentials with Bearer token authentication and an affiliate ID. * Storing and refreshing static resources such as car, supplier, and depot data. * Updating redirect, attribution, and tracking logic. * Updating error handling to use HTTP status codes and structured JSON errors. * Optionally extending your integration with direct booking and selected post-booking capabilities available in Beta. Direct car rental booking and selected post-booking capabilities are currently available in Beta only. ## Supported integration flows The functionality available to your integration depends on whether you use Demand API v3.2 or Beta. | Integration flow | Availability | | --- | --- | | [Content-only](/demand/docs/development-guide/application-flows/content-only) | v3.2 | | [Search, look, and redirect](/demand/docs/development-guide/application-flows/search-look-redirect) | v3.2 | | [Search, look and book](/demand/docs/development-guide/application-flows/search-look-book) | Beta | | [Post-booking management](/demand/docs/development-guide/application-flows/post-booking) | Beta | | [Reporting and reconciliation](/demand/docs/development-guide/application-flows/reporting) | v3.2 | Demand API v3.2 support end-to-end booking flows only in Beta. ## Compare XML and Demand API v3.2 Demand API uses a different architecture, authentication model, and data format from the legacy XML API. | | Feature | XML | Demand API v3.2 | | **Protocol** | HTTPS | HTTPS | | **Production endpoint** | https://xml.rentalcars.com/service/ServiceRequest.do | https://demandapi.booking.com/3.2/search | | **Testing environment** | Dedicated XML sandbox: https://xmlsandbox.rentalcars.com/service/ServiceRequest.do | No dedicated car rental sandbox | | **Authentication** | Affiliate code (username) and password | Bearer token + `X-Affiliate-Id` | | **Request method** | POST | POST | | **Data format** | XML | JSON | | **Data model** | Multiple types of information returned through XML service responses. | Specialised endpoints for search, content, availability, booking, and supporting data. | ## Migrate your integration Follow these steps to migrate the main components of your XML integration. ### 1. Update authentication XML API credentials are not compatible with Demand API. Each Demand API request must include: * A valid API token in the Authorization header. * Your affiliate ID in the X-Affiliate-Id header. For example: ```json curl -i -X POST \ https://demandapi.booking.com/3.2/cars/search \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -H 'X-Affiliate-Id: ' \ -d // data here ``` Important XML API credentials are not compatible with Demand API. You must generate new credentials before migrating and include them in every request.[See the Authentication guide](/demand/docs/development-guide/authentication) for information about generating credentials and authenticating requests. ### 2. Replace XML with JSON Demand API uses JSON request and response payloads instead of XML. Update your integration to: * Generate JSON request bodies. * Parse JSON responses. * Map XML fields to their Demand API equivalents. * Handle the nested objects and arrays used by Demand API schemas. For field-level mappings, see the XML to Demand API mapping reference. ### 3. Adapt to specialised endpoints The XML API can return different types of car rental information through the same service interface. Demand API separates this information across specialised endpoints. Depending on your integration flow, you may use: * /cars/search * /cars/details * /cars/availability * /cars/depots * /cars/suppliers * /cars/constants * /cars/depots/reviews/scores If you implement a direct booking flow in Beta, you can additionally use endpoints such as: * /cars/availability * /orders/preview This separation allows your application to retrieve dynamic and static information independently. ### 4. Store static data Some information previously retrieved through XML responses is available through dedicated static-data endpoints. Store the static data required by your application locally and refresh it according to the recommended refresh frequency. Typical static resources include: * Car details. * Suppliers. * Depots. * Constants. * Depot review scores. See the [Car rental static data guide](/demand/docs/cars/cars-static-data) for the recommended storage and refresh strategy. ### 5. Update language handling Demand API uses a `languages` array instead of the XML `preflang` field: You can request content in multiple supported languages in the same request. For example: ```json { "languages": [ "en-gb", "es", "ar", "zh-cn" ] } ``` Use the /common/languages endpoint to retrieve the supported language codes. ### 6. Update attribution and tracking Demand API uses the `X-Affiliate-Id` header for partner attribution instead of the XML API `username`. For Search, look and redirect integrations, /cars/search returns redirect URLs that you can use to send travellers to Booking.com/cars to complete their booking. The affiliate ID is included in the redirect URL as the `aid` query parameter. Example: ```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 your XML integration uses tracking values such as `adplat` or `adcamp`, review how they map to Demand API labels. A label is a partner-defined tracking value that can support: * Campaign attribution. * Reporting. * Filtering. * Analytics. See the [Labels and attribution guide](/demand/docs/orders-api/labels-attributions) for examples and implementation guidance. ### 7. Update error handling Demand API uses standard HTTP status codes and structured JSON error responses. In general: * 4xx responses indicate request or client-side errors. * 5xx responses indicate server-side errors. For example: ```json { "request_id": "01jj6wbtrxge406v4mw5jmj42f", "errors": [ { "id": "invalid_parameter", "message": "Parameter 'pickup.datetime' is invalid. 'pickup.datetime' must be before 'dropoff.datetime'." } ] } ``` See the Error handling section for additional examples and troubleshooting guidance. ## Search context and search token Demand API uses the `search_token` returned by /cars/search to preserve the context of a search. The search context can include information such as: * Route. * Filters. * Booker country. * Search configuration. For Beta booking flows, pass the relevant `search_token` to subsequent endpoints such as: * /cars/availability * /orders/preview * /orders/create The token reduces the need to submit the complete search criteria again as the traveller progresses through the flow. Store the `search_token` for the duration of the relevant search and booking flow and account for its expiry when implementing subsequent requests. ## Extend your integration with Beta booking capabilities Migrating an XML Search, look and redirect integration to v3.2 does not require you to implement direct booking. If you want travellers to complete their booking directly within your experience, Demand API Beta supports the Search, look and book flow. A typical booking flow is: 1. Search for car rental offers using /cars/search. 2. Validate the selected offer and retrieve its latest availability using /cars/availability. 3. Preview the order using /orders/preview. 4. Create the order using /orders/create. The booking flow now uses the Orders API collection together with Car rentals endpoints. ### Availability and ancillary services Use /cars/availability to retrieve the latest information for the selected offer before continuing with the booking. Depending on the offer, the response can include information such as: * Latest pricing. * Policies. * Payment requirements. * Optional products. * Availability information. This allows you to build a dedicated vehicle details or checkout page before booking. ### Payments Car rental booking flows use the Orders API collection together with the Demand API payment model. Payment requirements depend on the selected offer and the amount payable online. See the [Payments documentation](/demand/docs/payments/overview) for payment methods and card-handling requirements. Direct car rental booking is currently available in Beta only. ## Post-booking capabilities in Beta Selected post-booking capabilities are available in Beta and can be used to build traveller-facing order management experiences. Car rental post-booking flows are supported in Beta version. ### Common post-booking capabilities | Capability | Endpoint | | --- | --- | | Retrieve the latest car rental reservation details | [/orders/details/cars/live](/demand/docs/open-api/3.2-beta/demand-api/orders/details/cars/live) | | Cancel an order | [/orders/cancel](/demand/docs/open-api/3.2-beta/demand-api/orders/orders/cancel) | | Retrieve Terms and conditions | [/orders/details/cars/terms-and-conditions](/demand/docs/open-api/3.2-beta/demand-api/orders/cars-terms-and-conditions) | | Retrieve booking-related FAQs | [/orders/details/cars/faq](/demand/docs/open-api/3.2-beta/demand-api/orders/cars/faqs) | Use the returned information to support experiences such as: * Displaying the latest booking details. * Providing traveller self-service information. * Displaying terms and conditions. * Providing booking-related FAQs. * Supporting confirmation and post-booking communications. See the [Car rental post-booking guide](/demand/docs/cars/3.2/post-booking-live-order-details) for implementation guidance. ## Test your migration A dedicated sandbox environment **is not currently available for car rental integrations**. When validating your migration, follow the approved testing process for your integration and coordinate with your Account Manager where required. Make sure you validate: * Authentication and authorisation. * JSON request and response parsing. * XML-to-Demand API field mappings. * Static-data storage and refresh. * Search and redirect behaviour. * Attribution and labels. * Error handling. * Beta booking and post-booking flows, if applicable. ## Migration Checklist | Checklist | | --- | | ☑ | Generate your Demand API credentials and identify your affiliate ID. | | ☑ | Replace XML authentication with Bearer token authentication and X-Affiliate-Id. | | ☑ | Replace XML request and response handling with JSON. | | ☑ | Map the XML fields used by your integration to their Demand API equivalents. | | ☑ | Integrate the Cars endpoints required by your application flow. | | ☑ | Implement the required static-data storage and refresh strategy. | | ☑ | Update language handling. | | ☑ | Update redirect, attribution, and label handling. | | ☑ | Update error handling to use HTTP status codes and structured JSON errors. | | ☑ | Validate your migrated integration end to end. | | ☑ | Implement Beta booking and post-booking capabilities, if required. | ## Next steps For detailed mappings between the legacy XML API and Demand API, continue with the XML to Demand API mapping reference. You can also: * Review the [Car rentals quick guide](/demand/docs/cars/cars-quick-guide) to make your first Demand API car rental requests. * Explore the [Car rentals documentation](/demand/docs/cars/overview) for supported integration flows and implementation guidance. * Use the [Demand API v3.2 Cars API reference](/demand/docs/open-api/3.2/demand-api/cars) and [Beta version Cars API reference](/demand/docs/open-api/3.2-beta/demand-api/cars) for complete endpoint schemas.