# 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.product`replace 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

Breaking changes

The following v3.1 fields are deprecated or replaced in v3.2. Update your integration to avoid disruption.

| v3.1 | v3.2 replacement | Impact | Notes / migration action |
|  --- | --- | --- | --- |
| `currency` | `currencies.booker / currencies.product` | UI / Reporting | Replace flat currency with multi-currency object. Use `booker` for display, `product` for accounting. |
| `commission.actual_amount` | `commission.actual_commission_amount.booker_currency` | Reporting | Migrate numeric to structured object. Implement fallback to deprecated field temporarily. |
| `commission.estimated_amount` | `commission.estimated_commission_amount.booker_currency` | Reporting | Same as above. |
| `price.commissionable` | `price.commissionable_price.booker_currency` | UI / Calculations | Update calculations and UI to use `booker_currency`. |
| `price.total` | `price.total_price.booker_currency` | UI / Calculations | Same as above. |
| – | `accommodations.location`, `name`, `number_of_guests`, `stay_probability` | UI / Analytics | Update parsers for new structure. |
| – | `cars.pickup_location / dropoff_location` | UI / Analytics | New nested structure for cars in the response. |
| – | `attractions` | UI / Filtering / Calculations | New nested structure for attractions in the response. |
| – | `flights.itineraries` | UI / Analytics | Parse array of itineraries. |
| – | `label` | Reporting / Attribution | Capture partner attribution. |
| – | `start / end` | UI / Filtering | Handle travel window dates where needed. |


## Quick migration summary

Top changes in v3.2:

| Change | Impact | Notes |
|  --- | --- | --- |
| `currency` → `currencies.booker / currencies.product` | UI / Accounting | Use `booker` for display, `product` for accounting. Deprecated field removed. |
| `commission.actual_amount` → `commission.actual_commission_amount.booker_currency` | Reporting | Structured object replaces numeric value. |
| `commission.estimated_amount` → `commission.estimated_commission_amount.booker_currency` | Reporting | Same as above. |
| `price.total` / `price.commissionable` → `price.total_price` / `price.commissionable_price` | UI / Calculations | Update parsing and UI logic. |
| New nested objects | Analytics / UI | `accommodations.location`, `cars`, `attractions`, `flights.itineraries` |
| `label` | Attribution | Optional partner-defined field for tracking campaigns. |
| `start` / `end` | Filtering | Travel window dates for filtering/reporting. |


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

| Deprecated field | Status | Replacement |
|  --- | --- | --- |
| `commission.actual_amount` | ❌ Removed | ✅ `commission.actual_commission_amount` |
| `commission.estimated_amount` | ❌ Removed | ✅ `commission.estimated_commission_amount` |
| `currency` | ❌ Removed | ✅ `currencies.booker` / `currencies.product` |
| `price.total` | ❌ Removed | ✅ `price.total_price` |
| `price.commissionable` | ❌ Removed | ✅ `commissionable_price` |


Recommended alternative
Switch immediately to the new structured objects. Use deprecated fields only as fallback while migrating.

## Quick migration checklist

| Checklist |  |
|  --- | --- |
| ☑ | Update parsing for `currencies.booker` / `currencies.product`. |
| ☑ | Update `commission.*_commission_amount` objects and remove deprecated fields. |
| ☑ | Replace `price.total` / `price.commissionable` with `price.total_price` / `price.commissionable_price`. |
| ☑ | Add handling for `accommodations.location`, `name`, `number_of_guests`, `stay_probability`. |
| ☑ | Add handling for `cars` (`pickup_location`, `dropoff_location`) and `attractions`. |
| ☑ | Add support for `flights.itineraries` if flights are booked. |
| ☑ | Support `label` for partner attribution. |
| ☑ | Add handling for `start` / `end` travel dates. |
| ☑ | Run integration tests with v3.2 sample payloads (include edge cases: null `stay_probability`, missing `label`, partial online payments). |


### Example - orders/details response (simplified)

v3.1 response 

```json

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

v3.2 response
Response with attractions and cars in the order:


```json

{
  "request_id": "01fr9ez700exycb98w90w5r9sh",
  "data": [
    {
      "id": "509430129718800",
      "accommodations": {
        "inventory": {
          "third_party": false,
          "type": "sell"
        },
        "location": { "address": "222 Sunset Blvd", "city": 10012345, "country": "us" },
        "name": "Sunset Hotel",
        "number_of_guests": 2,
        "reservation": 12345678,
        "stay_probability": 0.85
      },
      "affiliate": 111111,
      "booker": {
        "address": { "city": "London", "country": "gb" },
        "email": "janedoe@booking.com",
        "language": "en-gb",
        "name": { "first_name": "Jane", "last_name": "Doe" },
        "platform": "desktop",
        "telephone": "+440000000000",
        "travel_purpose": "leisure"
      },
      "commission": {
        "actual_commission_amount": { "booker_currency": 25.0, "product_currency": 30.0 },
        "actual_percentage": 10,
        "estimated_commission_amount": { "booker_currency": null, "product_currency": null }
      },
      "currencies": { "booker": "GBP", "product": "USD" },
      "currency": "GBP",
      "start": "2026-05-01T14:00:00+00:00",
      "end": "2026-05-07T11:00:00+00:00",
      "label": "SummerPromo-UK-Desktop",
      "flights": null,
      "attractions": {
        "name": "Eiffel Tower Guided Tour",
        "location": { "city": "Paris", "country": "fr" },
        "reservation": 9876543
      },
      "cars": {
        "reservation": 555001,
        "pickup_location": { "city": "Paris", "country": "fr" },
        "dropoff_location": { "city": "Versailles", "country": "fr" }
      },
      "loyalty_reward": [
        {
          "amount": 20,
          "currency": "GBP",
          "eligible": true,
          "fulfillment_at": "2026-05-01",
          "fulfillment_by": "partner",
          "loyalty_data": [
            { "name": "Email Id", "value": "janedoe@booking.com" },
            { "name": "Loyalty ID", "value": "20202020" }
          ],
          "type": "point"
        }
      ],
      "price": {
        "commissionable_price": { "booker_currency": 500, "product_currency": 580 },
        "total": 550,
        "total_price": { "booker_currency": 550, "product_currency": 638 }
      },
      "status": "booked",
      "updated": "2026-04-12T15:00:00+00:00"
    }
  ],
  "metadata": { "next_page": null, "total_results": 1 }
}
```

[Try it yourself!](/demand/docs/open-api/3.2/demand-api/orders/orders/details)

## Migration guide – Steps

### 1. Inventory & schema discovery

* Pull the current [v3.2 OpenAPI schema](/demand/docs/open-api/3.2/demand-api) for /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

* Check the [v3.2 Orders API reference](/demand/docs/open-api/3.2/demand-api) for details in fields.
* Try the new version in this portal console.
* Contact your Booking.com technical account manager for migration support.