Orders details – Migrating to v3.2

Learn how to update your integration to support /orders/details in Demand API v3.2. This guide explains breaking changes, new nested structures, and recommended migration practices.

Summary of key impacts

• Multi-currency support: currencies.booker and currencies.productreplace the flat currency field.
• Commission and price fields are now structured objects.
• New nested objects introduced for accommodations, attractions, cars, and flights.
• Deprecated fields are now removed (price.total, commission.actual_amount, etc.).
• Label and date range fields added for attribution and filtering.

Breaking changes

Quick migration summary

Top changes in v3.2:

✅ Recommended: Switch immediately to the new structured objects; treat deprecated fields only as fallback temporarily.

Deprecated fields

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

Quick migration checklist

Example - orders/details response (simplified)

{
  "request_id": "01fr9ez700exycb98w90w5r9sh",
  "data": [
    {
      "id": "509430129718799",
      "accommodations": {
        "inventory": {
          "third_party": false,
          "type": "sell"
        },
        "reservation": 12345677
      },
      "affiliate": 111111,
      "booker": {
        "address": { "city": "Amsterdam", "country": "nl" },
        "email": "johndoe@booking.com",
        "language": "en-gb",
        "name": { "first_name": "john", "last_name": "doe" },
        "platform": "mobile",
        "telephone": "+100000000",
        "travel_purpose": "business"
      },
      "commission": {
        "actual_amount": 17.5,
        "estimated_amount": null
      },
      "currency": "EUR",
      "created": "2025-07-28T02:00:00+00:00",
      "price": {
        "commissionable": 160,
        "total": 170.01
      },
      "status": "booked",
      "updated": "2025-07-28T02:00:00+00:00"
    }
  ],
  "metadata": { "next_page": null, "total_results": 1 }
}

Migration guide – Steps

1. Inventory & schema discovery

• Pull the current v3.2 OpenAPI schemafor /orders/details and inspect the data[] object.

2. Backend parsing

• Implement parsing for currencies, commission.*_commission_amount, and price.*_price.
• Add fallbacks logic for deprecated fields temporarily (Example: commission.actual_amount).
• Add support for accommodations.location and cars/attractions objects where relevant.

3. UI update

• Replace any direct reads of price.total with price.total_price.booker_currency.
• Where you show amounts to users, prefer currencies.booker values.

4. Business logic & reporting

• Update billing/commission calculations to use actual_commission_amount.product_currency for product-level accounting and booker_currency for user-facing reporting.

5. Analytics and attributions

• Track label, start / end dates, and new objects.

6. Testing

• Run integration tests with sample v3.2 responses (include edge cases: missing estimated_commission_amount, null stay_probability, missing label).
• Use test hotels and sandbox environment for the accommodation implementation.
• Validate monetary rounding rules when converting between currencies.

7. Rollout

• Release with both new and deprecated parsing for a short transition window; after verifying data is correct, remove deprecated-path code.

Other services details

Refer to each endpoint migration guide for details:

What's next