Accommodation order details – Migrating to v3.2

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

Summary of key impacts

Request shape is unchanged — clients can keep sending the same payload to /orders/details/accommodations.
Response-only changes in v3.2 may require updates to parsers and downstream logic that read room IDs, price breakdowns and key-collection enums.

The most important changes to handle are:

products.room changes from number → string (room identifier).
products.price structure changed: extra_charges.conditional / non_conditional → unified charges array, plus a new display price.
credit_slip (deprecated earlier) has been removed — continue using credit_slip_number.

No change to commission, cancellation, traveller / guest structures or top-level fields — most integrations will only need a few targeted fixes.

Breaking changes

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

Field / Feature	v3.1	v3.2	Impact / Action Required
`products.room`	Number	String	Update parsing logic and any internal DB/model fields; old numeric assumptions will fail.
`products.price.extra_charges.conditional` / `non_conditional`	Conditional and non-conditional arrays	Single `products.price.charges` array, includes display price.	Refactor price parsing logic; map conditional vs non-conditional charges into charges array. Handle display field.
`credit_slip`	Integer (deprecated in v3.1)	Removed	Stop using `credit_slip`; migrate to `credit_slip_number.`
`products.room_details.name`	Room name as per product (no other changes)	No structural changes, only linked to `products.room` string.	Verify client code using room as identifier, since ID type changed.

Deprecated fields

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

Deprecated field	Status	Replacement
`credit_slip`	❌ Removed	✅ `credit_slip_number`

Recommended alternative

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

Quick migration summary

Top changes in v3.2:

Change	Impact	Notes
No change to requests (orders or reservations + currency + extras)	None	Existing requests will continue to work without modification.
`products.room` now returned as string	Parsing logic must be updated	Old numeric assumptions will fail; update any internal DB/model fields using room ID.
`products.price.extra_charges.conditional` / `non_conditional` replaced by `products.price.charges`	Parsing logic must be updated	Refactor code to consume the new `charges` array; prefer `display` for traveller-facing amounts.
`products.price.display` for traveller-facing amounts	Minor logic update	Ensure UI or reports use `display` where applicable.
`credit_slip` removed, use `credit_slip_number`	Update logic to rely on new field	Stop using deprecated `credit_slip`.
Money calculations / totals semantics changed	Verify totals	Display + charges semantics may affect presentation; compare sample orders to validate.

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

Quick migration checklist

Checklist
☑	Update parsing for `products.room` (type changed from number → string) and adjust any DB or internal model fields accordingly.
☑	Update `products.price` parsing: replace `extra_charges.conditional` / `non_conditional` with `charges` array and include handling for display price.
☑	Update `commission.*_commission_amount` objects and remove deprecated `credit_slip` fields; continue using `credit_slip_number`.
☑	Run integration tests to validate parsing, totals, room IDs, cancellation flows, and traveller-facing price displays.

Example - orders/details/accommodations response (simplified)


{
  "request_id": "req_abc",
  "data": [
    {
      "id": "ORD-123",
      "accommodation": 98765,
      "reservation": 2321873123,
      "pin_code": "A1B2C3",
      "price": {
        "base": {
          "accommodation_currency": 120.00,
          "booker_currency": 120.00
        },
        "extra_charges": {
          "conditional": [
            {
              "charge": 1,
              "condition": 10,
              "mode": "percentage",
              "percentage": 10.00,
              "total_amount": {
                "accommodation_currency": 12.00,
                "booker_currency": 12.00
              }
            }
          ],
          "non_conditional": [
            {
              "charge": 2,
              "mode": "calculated_amount",
              "total_amount": {
                "accommodation_currency": 5.00,
                "booker_currency": 5.00
              }
            }
          ]
        },
        "total": {
          "accommodation_currency": 137.00,
          "booker_currency": 137.00
        }
      },
      "products": [
        {
          "room": 112233,
          "room_details": { "name": "Double Room" },
          "price": {
            "base": { "accommodation_currency": 120.00, "booker_currency": 120.00 },
            "extra_charges": {
              "conditional": [ /* ... */ ],
              "non_conditional": [ /* ... */ ]
            },
            "total": { "accommodation_currency": 137.00, "booker_currency": 137.00 }
          }
        }
      ],
      "key_collection_information": [
        { "key_location": "key_location_at_the_property" }
      ],
      "credit_slip": 123456789
    }
  ]
}

Try v3.2 yourself!

Migration guide – Steps

1. Audit current code

Pull the current v3.2 OpenAPI schemafor /orders/details/accommodations and inspect the data[] object.
Find all locations that parse /orders/details/accommodations responses.
Note any assumptions about products.room being numeric and any code that accesses extra_charges.conditional or non_conditional.

2. Update models

Change room field type to string in DTOs / schemas / database columns.
Update price model to accept charges (array) and display (optional).

3. Update parsing logic

Replace extra_charges.conditional / non_conditional handling with:
- Iterate products.price.charges and group/filter/aggregate by included_in.display or condition as appropriate.
Use display for traveller-facing price display when present; fallback to base + charges if display not provide.

4. Update enum mappings

Map legacy key locations:
- key_location_at_the_property → at_the_property
- key_location_different_place → different_place

5. Remove deprecated usage

Delete references to credit_slip and update any reports/DB fields to use credit_slip_number.

6. Testing

Run integration tests with sample v3.2 responses (include edge cases`).
Use test hotels and sandbox environment for the testing.

7. Rollout

Monitor errors related to JSON parsing, type coercion, currency totals and enum mapping.
Keep logs for mismatches and reconcile with Booking.com support if necessary (use request_id).

What's next

Review the /orders/details migration guide.
Check the v3.2 Orders API reference for details in fields.
Contact your Booking.com technical account manager for migration support.