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

Comparison table (v3.1 → v3.2)

Request examples

{
  "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"]
  }
}

Response examples

cars/search responses

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

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

Deprecations

The following fields are deprecated in v3.2 and should be replaced with their updated equivalents.

Migration checklist

What´s next