# Car rentals migration to Demand API v3.3

**Review the changes introduced in Demand API v3.3 Car rentals and update the endpoints, fields, objects, enum values, and integration behaviour affected by the release.**

## Introduction

Demand API v3.3 consolidates the car rental search, availability, booking, and post-booking capabilities introduced across previous Demand API versions and makes them available as stable functionality.

Several capabilities previously introduced in v3.2 Beta are now available as stable functionality in both v3.2 and v3.3.

Version 3.3 also introduces car invoicing and changes to the post-booking flow.

Use this guide to:

* Identify the changes that affect your integration;
* Review the changes relevant to integrations migrating from XML, v3.1, v3.2 stable, or v3.2 Beta;
* Update request fields, response objects, and enum values;
* Adopt the v3.3 post-booking and invoicing flows;
* Avoid relying on fields that are removed or no longer returned by a particular endpoint.


## Car rental integration flow availability

The following integration flows are available for car rentals in each Demand API version.

| Integration flow | Availability |
|  --- | --- |
| [Content only](/demand/docs/development-guide/application-flows/content-only) | 3.1 3.2 3.3 |
| [Search, look and redirect](/demand/docs/development-guide/application-flows/search-look-redirect) | 3.1 3.2 3.3 |
| [Search, look and book](/demand/docs/development-guide/application-flows/search-look-book) | 3.2 3.3 |
| [Post-booking management](/demand/docs/development-guide/application-flows/post-booking) | 3.2 3.3 |
| [Reporting and reconciliation](/demand/docs/development-guide/application-flows/reporting) | 3.1 3.2 3.3 |


## Car rental availability after the v3.3 launch

The following table shows the availability of the main car rental capabilities after the v3.3 launch.

| Capability | v3.2 stable | v3.3 stable | Notes |
|  --- | --- | --- | --- |
| Car search | ✅ Available | ✅ Available | Use /cars/search to retrieve car rental offers. |
| Availability validation | ✅ Available | ✅ Available | /cars/availability is available as stable functionality in both versions. |
| Search, look and book | ✅ Available | ✅ Available | The complete native booking flow is available in both versions. |
| Insurance | ✅ Available | ✅ Available | Insurance can be selected during the car order flow where it is available for the offer and partner configuration. |
| Terms and conditions | ✅ Available | ✅ Available | Pre-booking and post-booking terms and conditions are available in both versions. |
| FAQs and live post-booking details | ✅ Available | ✅ Available | In v3.3, use /orders/details/cars for  post-booking reservation details. |
| Car invoicing | ❌ Not available | ✅ Available | Retrieve invoices through /orders/details/cars by setting `extras.include_invoice` to true. |


## Capabilities promoted to stable

The following car rental capabilities were previously available in v3.2 Beta and are now available as stable functionality in Demand API v3.2 and v3.3.

| Capability | Endpoint | Availability | Purpose | Related guide |
|  --- | --- | --- | --- | --- |
| Availability validation | /cars/availability | 3.2 3.3 | Validate the availability and latest pricing of a selected car offer before booking. | [Check car availability guide](/demand/docs/cars/3.2/check-cars-availability) |
| Pre-booking terms and conditions | /cars/terms-and-conditions | 3.2 3.3 | Retrieve the legal terms and conditions for a selected car offer before booking. | [Pre-booking terms and conditions guide](/demand/docs/cars/3.2/pre-booking-terms-and-cond) |
| Post-booking terms and conditions | /orders/details/cars/terms-and-conditions | 3.2 3.3 | Retrieve the terms and conditions associated with a confirmed car rental order. | [Post-booking terms and conditions guide](/demand/docs/cars/3.2/post-booking-terms-and-cond) |
| Car rental FAQs | /orders/details/cars/faq | 3.2 3.3 | Retrieve booking-related FAQs to support traveller self-service experiences. | [Car rental FAQs API reference](/demand/docs/open-api/3.3/demand-api/orders/cars/faqs) |


### Live post-booking details

The live post-booking details endpoint has a different path in each stable version.

| Version | Endpoint | Purpose |
|  --- | --- | --- |
| v3.2 | /orders/details/cars/live | Retrieve the latest live details for a car reservation. |
| v3.3 | /orders/details/cars | Retrieve the latest live details for a car reservation and, optionally, invoice documents. |


## What changes in v3.3

The following table summarises the main migration impact.

| Area | Change in v3.3 | Action |
|  --- | --- | --- |
| Availability | Car availability validation is available as stable functionality. | Continue using /cars/availability. No Beta-to-stable endpoint migration is required. |
| Booking | The Search, look and book flow is available as stable functionality. | Remove Beta-only feature flags or routing logic where they are no longer required. |
| Live post-booking details | /orders/details/cars/live is not available in v3.3. Its functionality is provided by /orders/details/cars. | Replace /orders/details/cars/live with /orders/details/cars. |
| Reporting order details | /orders/details/cars returns live post-booking details in v3.3 instead of the previous v3.2 reporting response. | Use /orders/details for reporting, commission, and order-level financial information. |
| Invoicing | Car invoice and credit-document retrieval is available in v3.3. | Request invoices explicitly and download temporary document URLs immediately. |
| Terms and conditions | The high-level response object changes from `key_info` to `terms_summary`. | Update response parsing for /cars/terms-and-conditions. |
| Post-booking terms | The request field `orders` is renamed to `reservations`. | Update requests sent to /orders/details/cars/terms-and-conditions. |
| Payment timing | The partial online payment value changes from `pay_partial_online_now` to `pay_partially_online`. | Update field mappings and enum validation throughout the car rental integration. |
| Search sorting | `sort.direction` is removed from the car search schema. | Keep `sort.by` and remove `sort.direction` from requests. |
| Depot reviews | `breakdown.likeliness_rent_again` is removed. | Remove the field from response models and presentation logic. |
| Depot information | `depot_type` is renamed to `depot_description` in /orders/details/cars. | Update response parsing for pickup and drop-off details. |


Car rental search, availability, booking, and post-booking management are available as stable functionality in Demand API v3.2 and v3.3. Car invoicing is available only in v3.3.

## Recommended v3.3 car rental booking flow

Use the following sequence for the native car rental booking flow:

![Car rental Search, look and book flow](/assets/cars-search-book-flow.7c15c0f59f3ee45462c54eb1157e98d294f233655d3f14c147123843f67e0b69.7633397c.png)

## Endpoint changes

| v3.2 endpoint | v3.3 endpoint | Migration action |
|  --- | --- | --- |
| `/cars/search` | `/cars/search` | Continue using the endpoint. Remove `sort.direction` from requests. |
| `/cars/availability` | `/cars/availability` | Continue using the endpoint. It is now available as a stable capability. |
| `/orders/create` | `/orders/create` | Continue using the endpoint. Use the v3.3 car-specific request schema and payment values. |
| `/orders/details/cars/live` | `/orders/details/cars` | Replace the endpoint path. The v3.3 endpoint returns the live post-booking response. |
| `/orders/details/cars` | `/orders/details` | Use `/orders/details` when you need reporting details, commission, or order-level financial information. |
| `/orders/details/cars/terms-and-conditions` | `/orders/details/cars/terms-and-conditions` | Rename the request field `orders` to `reservations`. |
| `/cars/terms-and-conditions` | `/cars/terms-and-conditions` | Rename the response object `key_info` to `terms_summary`. |
| `/orders/details/cars/faq` | `/orders/details/cars/faq` | No endpoint change is required. |


## Breaking changes Breaking change

The following changes require code updates when migrating to v3.3.

| Area | v3.2 | v3.3 | Required action |
|  --- | --- | --- | --- |
| Car order creation identifier | `reservation_id` | `reservation` | Rename the response property and update stored identifiers. |
| Car order creation status | `Processing` | `processing` | Update enum validation and status comparisons. |
| Car live details endpoint | /orders/details/cars/live | /orders/details/cars | Replace the endpoint and update request and response handling. |
| Car depot field | `depot_type` | `depot_descriptions` | Rename the response field. |
| Car terms request field | `orders` | `reservations` | Rename the request field in /orders/details/cars/terms-and-conditions. |
| Car payment timing | `pay_partial_online_now` | `pay_partially_online` | Update enum mappings and stored values. |


### Remove `sort.direction` from car search

In v3.2, car search requests could contain `sort.direction`. In v3.3, the car search sorting object uses `sort.by` only.

Before:

```json
{
  "sort": {
    "by": "price",
    "direction": "ascending"
  }
}
```

After:

```json
{
  "sort": {
    "by": "price"
  }
}
```

Update request builders, validation rules, stored request templates, and any tests that include `sort.direction`.

### Remove `breakdown.likeliness_rent_again`

The deprecated `breakdown.likeliness_rent_again` field is removed from car depot review scores.

Remove the field from:

* response models;
* review-score mapping logic;
* UI components;
* analytics and ranking logic;
* generated API clients that still expose the property.


Do not treat the absence of this field as a failed response. The remaining review breakdown fields are still returned where available.

### Rename `key_info` to `terms_summary`

The response from `/cars/terms-and-conditions` changes from:

```json
{
  "data": {
    "key_info": {
      "common": {},
      "damage_excess": {},
      "deposit": {}
    }
  }
}
```

to:

```json
{
  "data": {
    "terms_summary": {
      "common": {},
      "damage_excess": {},
      "deposit": {}
    }
  }
}
```

The contents of the high-level summary remain conceptually the same. Update the object name in:

* response deserialisers;
* typed models;
* transformation layers;
* traveller-facing terms summaries;
* contract and snapshot tests.


The detailed hierarchical terms remain under `data.terms`.

### Rename `orders` to `reservations` for post-booking terms

The request to `/orders/details/cars/terms-and-conditions` uses reservation IDs.

In v3.3, the request field is therefore named `reservations`.

Before:

```json
{
  "booker": {
    "country": "gb"
  },
  "orders": [
    "765255700"
  ],
  "language": "en-gb"
}
```

After:

```json
{
  "booker": {
    "country": "gb"
  },
  "reservations": [
    "765255700"
  ],
  "language": "en-gb"
}
```

The response remains a map keyed by reservation ID.

Update the request model and do not rename reservation IDs to order IDs in your application domain.

### Rename payment timing

The partial online payment value changes from `pay_partial_online_now` to `pay_partially_online`.

| v3.2 value | v3.3 value | Meaning |
|  --- | --- | --- |
| `pay_online_now` | `pay_online_now` | The traveller pays online at the time of booking. |
| `pay_partial_online_now` | `pay_partially_online` | Part of the payment is made online and the remaining amount is paid at pick-up. |
| `pay_at_pickup` | `pay_at_pickup` | The traveller pays at the car rental pick-up location. |


Use `pay_partially_online` wherever the v3.3 car rental schema defines the partial online payment value. Update all affected car rental objects consistently.

### Rename `depot_type` to `depot_description`

In v3.3, the response from /orders/details/cars uses `depot_description` instead of `depot_type` for pickup and drop-off locations.

Update your response models and parsing logic to read `pickup.depot_description` and `dropoff.depot_description`. Remove dependencies on `depot_type`.

### Live post-booking details

In v3.3, replace `/orders/details/cars/live` with `/orders/details/cars`.

* The v3.3 endpoint returns live post-booking details for a specific car reservation, including the current status, vehicle, supplier, pricing, policies, insurance, and optional invoices.
* If your v3.2 integration used `/orders/details/cars` for reporting or commission information, migrate that use case to `/orders/details`.
* The v3.3 `/orders/details/cars` response is a live post-booking response and does not contain the previous reporting structure.


For request and response examples, pricing structures, status handling, and invoice retrieval, see the dedicated [car order details](/demand/docs/orders-api/order-details-cars) and [post-booking guides](/demand/docs/orders-api/post-booking-overview).

### Pricing structure changes

The v3.3 live car response separates display amounts from payment amounts:

* Use `display` for traveller-facing prices;
* Use `pay` for actual payment amounts;
* Use `price.total[].pay.timing` to distinguish payment timings;
* Do not multiply product prices by rental duration or quantity.


See the dedicated [Pricing guide](/demand/docs/cars/3.2/cars-pricing) for the complete v3.3 pricing model.

## Car invoicing New in v3.3

Car invoicing is available in v3.3 stable and is not available in v3.2.

To retrieve invoice documents, call /orders/details/cars with `extras.include_invoice` set to `true`.

If your integration retrieves car order details, update it to:

* Support the optional `extras.include_invoice` request field;
* Parse the `invoices` response array;
* Handle invoice and credit documents;
* Handle documents that are available, temporarily unavailable, or unavailable;
* Download temporary document URLs immediately and avoid caching them.


Invoice generation and document availability can be asynchronous.

See the dedicated car invoicing guide for the complete request and response examples, invoice document model, URL validity, and retry behaviour.

## Booking and cancellation status

Car order creation and cancellation can be processed asynchronously.

When migrating to v3.3:

* Replace `/orders/details/cars/live` with `/orders/details/cars`;
* Store the reservation ID returned by `/orders/create`;
* Do not repeat an order request only because processing is still in progress;
* Retrieve the latest status after creating or cancelling an order;
* Do not present an order as cancelled until the live details response confirms the cancellation.


For the complete status model and post-booking polling guidance, see the [Car post-booking management guide](/demand/docs/orders-api/order-details-cars) and [Cancellations guide](/demand/docs/orders-api/cancel-order#cancellation-processing-behaviour).

## Insurance

Car rental insurance capabilities introduced in v3.2 Beta are available in both v3.2 stable and v3.3 stable.

No separate v3.3 insurance migration is required. Continue using the insurance object returned during availability and booking flows.

For the complete insurance flow, including quote references, document handling, booking, and post-booking insurance status, see the [Car rental insurance guide](/demand/docs/cars/3.2/cars-insurance-guide).

## Migration checklist

Use this checklist when upgrading to v3.3.

### Request changes

* Remove `sort.direction` from `/cars/search`.
* Rename `orders` to `reservations` in `/orders/details/cars/terms-and-conditions`.
* Replace `/orders/details/cars/live` with `/orders/details/cars`.
* Add the required `booker` object when requesting live car order details.
* Use `extras.include_invoice` only when invoice documents are required.
* Update payment timing mappings to use `pay_partially_online` where defined by the v3.3 car schemas.


### Response changes

* Rename `/cars/terms-and-conditions` response object `key_info` to `terms_summary`.
* Update live car order parsing to the `carsPostbookOutput` structure.
* Replace legacy monetary objects with `display`, `pay`, and payment-timing totals.
* Rename `depot_type` to `depot_description` in pickup and drop-off details.
* Remove dependencies on reporting fields from live car details.
* Add support for the `invoices` array and invoice document statuses.
* Remove `breakdown.likeliness_rent_again`.
* Handle asynchronous booking and cancellation statuses.


### Integration behaviour

* Do not retry `/orders/create` solely because the response status is processing.
* Poll `/orders/details/cars` for the current post-booking state.
* Use `/orders/details` for reporting and commission information.
* Do not multiply product prices by rental duration or quantity.
* Do not add payment totals with different payment timings together.
* Download temporary document URLs immediately.
* Treat unknown enum values and unavailable documents safely.


## Testing recommendations

Test the complete flow in the environment available for your partner configuration.

Car rental orders are not available in the dedicated sandbox environment. Test car booking and post-booking flows in the environment provided for your partner configuration.

### Search and availability

* Search with and without sorting.
* Confirm that requests no longer send `sort.direction`.
* Validate the selected offer with `/cars/availability`.
* Test each supported payment timing.
* Verify that display and payment currencies are handled separately.
* Confirm that payment totals are grouped by timing.


### Booking

* Create orders for online payment, partial online payment, and payment at pick-up where available.
* Confirm that the returned reservation ID is stored.
* Verify that processing orders are polled rather than recreated.
* Test insurance selection and expired insurance quote references.
* Test both successful and unsuccessful booking outcomes.


### Post-booking management

* Retrieve live details through `/orders/details/cars`.
* Confirm that `/orders/details/cars/live` is no longer called.
* Verify that the current status is refreshed after create and cancel operations.
* Retrieve reporting data separately through `/orders/details`.
* Request live details with and without `include_invoice`.
* Test available, temporarily unavailable, and unavailable invoice documents.
* Confirm that temporary invoice URLs are not cached.


### Terms and conditions

* Update consumers from `key_info` to `terms_summary`.
* Submit post-booking terms requests with `reservations`.
* Test invalid reservation IDs and null response values.
* Test the `voucher` filter where only voucher-required terms are needed.


## What’s next

* [Version 3.3 Cars API reference](/demand/docs/open-api/3.3/demand-api/cars) - For full schema, examples and descriptions.
* [Car rental Search, look, and book tutorial](/demand/docs/cars/3.2/cars-tutorial) - For instructions on the full booking flow.
* [Orders documentation](/demand/docs/orders-api/overview) for reporting, cancellation, and post-booking status handling.
* [Error handling guide](/demand/docs/support/error-handling/about-errors) - For common errors and solutions.