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.

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.

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

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

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.

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

The following table summarises the main migration impact.

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

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

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

Before:

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

After:

{
  "sort": {
    "by": "price"
  }
}

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

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.

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

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

to:

{
  "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.

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

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

Before:

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

After:

{
  "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.

The partial online payment value changes from pay_partial_online_now to pay_partially_online.

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.

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.

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.

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.

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.

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.

Use this checklist when upgrading to v3.3.

• 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.

• 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.

• 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.

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

• 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.

• 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.

• 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.

• 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.