# Cars search – Migrating to v3.2 **A detailed guide for updating cars/search integrations to Demand API v3.2.** ## Introduction This guide summarises changes between /cars/search v3.1 and v3.2 and explains what you need to update to maintain correct functionality. ## Breaking changes v3.2 Breaking changes These changes **require updates to client logic, data models, or UI** to avoid errors or misinterpretation. ### Key field changes (v3.1 → v3.2) Breaking changes | Field | Change | Why it’s breaking | | --- | --- | --- | | `policies.damage_excess` | Number → Object `{ amount, currency }` | Integrations expecting a numeric value will fail. Requires schema update. | | `policies.deposit` | Number → Object `{ amount, currency }` | Integrations expecting a numeric value will fail. Requires schema update. | | `policies.theft_excess` | Number → Object `{ amount, currency }` | Integrations expecting a numeric value will fail. Requires schema update. | | `policies.mileage.amount` | Number → Object `{ amount, currency }` | Integrations expecting a numeric value will fail. Requires schema update. | | `policies.payment.timing` | Enum values replaced: `pay_now`, `part_pay`, `pay_local` → `pay_online_now`, `pay_partial_online_now`, `pay_at_pickup` | UI logic and enum mapping must be updated. | | `car` | Updated semantics: now corresponds to **specific car model + supplier** | Caching or matching logic based on older IDs may fail. | | `categories` | The type of car is now in the response. | Caching or matching logic based on older IDs may fail. | ### Comparison table (v3.1 → v3.2) | v3.1 | v3.2 | Impact | Notes / migration action | | --- | --- | --- | --- | | `car` | `car` (Now includes the fleet and car model) | Search matching | Now corresponds to a specific car model + supplier. Use /cars/details endpoint to store data keyed by this ID. | | N/A | `offer` (NEW) | Search / Availability | **New field**. Include when calling /cars/availability to match the offer. | | `policies.damage_excess` | Object `{ amount, currency }` | Pricing / Validation | Previously a number. Update client model to handle currency. | | `policies.deposit` | Object `{ amount, currency }` | Pricing / Validation | Previously a number. Update client model to handle currency. | | `policies.theft_excess` | Object `{ amount, currency }` | Pricing / Validation | Previously a number. Update client model to handle currency. | | `policies.mileage.amount` | Object `{ amount, currency }` | Pricing / Validation | Updated to object. Required fields: `fee` and `type`. Adjust client logic. | | `policies.payment.timing` | Enum values updated: `pay_online_now`, `pay_partial_online_now`, `pay_at_pickup` | Payment handling | Map old values (`pay_now`, `part_pay`, `pay_local`) to new ones. | | `deal` | Same | Pricing | No changes. | | `price` | Same | Pricing | No changes. | | `url` | Same | Links / Navigation | No changes. | | `request_id`, `metadata`, `search_token` | Same | Logging / Pagination | No changes. | ## Request examples v3.1 request **3.1 request example:** ```json { "booker": { "country": "nl" }, "currency": "EUR", "driver": { "age": 36 }, "filters": { "transmission_type": "automatic", "mileage_type": "limited", "depot_location_type": "in_terminal" }, "route": { "pickup": { "datetime": "2025-11-05T11:05:00", "location": { "airport": "AMS" } }, "dropoff": { "datetime": "2025-11-10T11:05:00", "location": { "airport": "AMS" } } }, "payment": { "timings": ["pay_now"] } } ``` v3.2 request **v3.2 with new payment timing:** ```json { "booker": { "country": "nl" }, "currency": "EUR", "driver": { "age": 36 }, "filters": { "transmission_type": "automatic", "mileage_type": "limited", "depot_location_type": "in_terminal" }, "route": { "pickup": { "datetime": "2025-11-05T11:05:00", "location": { "airport": "AMS" } }, "dropoff": { "datetime": "2025-11-10T11:05:00", "location": { "airport": "AMS" } } }, "payment": { "timings": ["pay_online_now"] } } ``` ## Response examples ### cars/search responses v3.1 response **3.1 response example:** ```json { "request_id": "01h00fr9y7qkbxtc6kyv97j49z", "data": [ { "car": 122655, "policies": { "cancellation": { "type": "free_cancellation", "details": { "context": "before_pickup", "duration": "P7D" } }, "damage_excess": 3000, "deposit": 1500, "insurance_package": "basic", "fuel": "return_same", "mileage": { "distance": 200, "distance_unit": "kilometers", "amount": 12.54, "type": "limited" }, "payment": { "timing": "pay_now" }, "theft_excess": 3000 }, "price": { "total": "121.90", "currency": "EUR", "extra_charges": [ { "charge": "aged_fee", "total_amount": 21.9 }, { "charge": "one_way_fee", "total_amount": 50 } ] }, "route": { "dropoff": { "depot": 112314, "depot_location_type": "airport_hotel" }, "pickup": { "depot": 112314, "depot_location_type": "airport_hotel" } }, "supplier": 7455, "url": { "app": "booking://page", "web": "https://example.com" } } ], "metadata": { "next_page": "eyJhbGciOiJIUzI1NiJ9.eyJwIjp7Im1heGltdW1fcmVzdWx0cyI6MTAsIm9mZnNldCI6MTB9LCJhdWQiOiJDQVJTX1NVUFBMSUVSUyIsImV4cCI6MTY4MzY0NzMwNX0.y7NmH48mm7lImd2WxsHdotj6n-dVQAzJCGCnIJCKy3A", "total_results": 122 }, "search_token": "eyJhbGciOiJIUzI1NiJ9.eyJwIjp7ImJvb2tlciI6eyJjb3VudHJ5IjoidXMifX0sImF1ZCI6Ii9ob3RlbHMvc2VhcmNoIiwiZXhwIjoxNzUwMDAwMDAwfQ.XYZ123AbcDefGHIjklMNOpqrsTUVwxYZ456789" } ``` v3.2 response **New structure example (v3.2):** ```json { "request_id": "string", "data": [ { "car": 12345, "offer": 67890, // NEW in v3.2: required for /cars/availability "categories": [ // NEW "large", "suvs" ], "deal": { "discount_percentage": 10, "public_price": 200.0, "tags": ["black_friday"] }, "policies": { "cancellation": { "type": "free_cancellation", "details": { "context": "BEFORE_PICKUP", "duration": "PT48H" } }, "damage_excess": { // CHANGED: now object with amount + currency "amount": 500.0, "currency": "EUR" }, "deposit": { // CHANGED: now object with amount + currency "amount": 100.0, "currency": "EUR" }, "theft_excess": { // CHANGED: now object with amount + currency "amount": 1000.0, "currency": "EUR" }, "insurance_package": "inclusive", "fuel": "return_same", "mileage": { // CHANGED: amount now object with currency "type": "limited", "distance": 500, "distance_unit": "kilometers", "amount": 50.0, "currency": "EUR" }, "payment": { "timing": "pay_online_now" // UPDATED enum } }, "price": { "currency": "EUR", "extra_charges": [ { "charge": "age_fee", "total_amount": 10.0 } ], "total": 210.0 }, "route": { "pickup": { "depot": 5944 // depot_location_type REMOVED in v3.2 }, "dropoff": { "depot": 5944 // depot_location_type REMOVED in v3.2 } }, "supplier": 9876, "url": { "app": "https://app.booking.com/cars/123", "web": "https://cars.booking.com/123" } } ], "metadata": { "next_page": null, "total_results": 1 }, "search_token": "encoded_string_here" } ``` Note: The `search_token` expires after 90 mins. ### ✅ Key developer actions for migration 1. Update models for `damage_excess`, `deposit`, `theft_excess`, and `mileage.amount` to include both amount and currency. 2. Add the new offer field and use it in /cars/availability. 3. Update `payment.timing` enum values. ## Migration steps ### 1. Inventory & schema discovery - Pull the current v3.2 OpenAPI schema for `/cars/search` - Inspect the `data[]` object for: * `car` ID (fleet + model) updated car semantics. * `offer` ID (new) * policies with monetary objects (`damage_excess`, `deposit`, `theft_excess`, `mileage.amount`). * `payment.timing` enum. ### 2. Update models * Update models to parse policies as objects: `"damage_excess": { "amount": 3000, "currency": "EUR" }` * Handle `mileage` object with required fields `fee` and `type`. * Implement `offer` field parsing for availability checks (/cars/availability). * Map updated payment timing enums: * pay_now → `pay_online_now` → online full payment. * part_pay → `pay_partial_online_now` → partial online. * pay_local → `pay_at_pickup` → payment at depot. ### 3. UI & Business logic * Ensure policies display amounts and currencies correctly. * Update filtering and sorting logic for route, filters, and payment timings. * Adjust any calculations for extra charges (`price.extra_charges`). * Update analytics pipelines if using `label` for tracking or attribution. - Ensure any filters relying on old enum values are updated to match v3.2. ### 6. Testing * Validate parsing of new object structures. * Test missing optional fields. * Verify correct display and calculations. ### 7. Rollout * Deploy with both old and new parsing temporarily. * Once stable, remove deprecated logic. ## Non-breaking improvements These add new fields or extend existing behaviour without breaking existing responses. | Field | Change | Why it's non-breaking | | --- | --- | --- | | `offer` | New field | Optional. Existing partners can ignore it safely. | | `deal`, `price`, `url`, `request_id`, `metadata`, `search_token` | No changes | Backward-compatible. | ## Deprecations The following fields are deprecated in **v3.2** and should be replaced with their updated equivalents. | Deprecated/ Removed | Replacement | Impact | Migration action | | --- | --- | --- | --- | | `policies.damage_excess` (number) | Object `{ amount, currency }` | Pricing / Validation | Update client models to handle the new object structure. | | `policies.deposit` (number) | Object `{ amount, currency }` | Pricing / Validation | Update client models to handle the new object structure. | | `policies.theft_excess` (number) | Object `{ amount, currency }` | Pricing / Validation | Update client models to handle the new object structure. | | `policies.mileage.amount` (number) | Object `{ amount, currency }` (required fields: `fee` and `type`) | Pricing / Validation | Update client logic to handle new object structure and required fields. | | `policies.payment.timing` old enum: `pay_now`, `part_pay`, `pay_local` | New enum: `pay_online_now`, `pay_partial_online_now`, `pay_at_pickup` | Payment handling | Map old values to new ones in your integration. | | `car` (semantics changed) | Still `car`, but now corresponds to car model + supplier; cache via /cars/details | Search matching | Update client logic to cache details by car ID. | Recommended alternative Switch immediately to the new structured objects. If you still receive deprecated fields, treat them as termporary fallback values only while you migrate. ## Migration checklist Required: * Update client models for monetary policy objects (damage_excess, deposit, theft_excess, mileage.amount). * Implement support for `offer` IDs in availability/booking flows. * Update `payment.timing` enum handling. * Validate display and calculations of price.total and extra_charges. ## What´s next * Explore the [Car rental section](/demand/docs/cars/overview) * Use the [Quick guide](/demand/docs/cars/cars-quick-guide) to try v3.2 endpoints. * Test v3.2 endpoints using the [Car rental API reference](/demand/docs/open-api/3.2/demand-api/cars)