processBooking - V3 migration guide

In V2, you can use the processBooking endpoint to book products previously selected from the hotelAvailability and/or blockAvailability endpoints.

For V3 we have split the V2 processBooking functionality into two endpoints to provide a more streamlined, transparent and efficient booking process.

For more information, see /orders/preview and /orders/create.

Use /orders/preview to obtain final price information and payment details for an order, so that the traveller can confirm the details before placing the order.

The /orders/preview response also returns an order token, the token contains encapsulated details about the order, which you will pass to the /orders/create request.
Using this token reduces the risk of data mismatch errors and provides a more efficient booking experience.

Use /orders/create to book the requested products and process payment for the order.

Use the following tables to identify how to migrate request query parameters and response fields from a V2 processBooking call to the appropriate V3 equivalent.

Attention

Do not assume that mapped parameters or fields work in exactly the same way in V3 as they did in V2.

V3 is a significant redesign of the Demand API and some things work very differently. Use this documentation, the API Reference, and your own experimentation and testing to make sure that you migrate each V2 call correctly.

Request parameter mappings

The following tables show:

parameter mappings to the /orders/preview endpoint.
parameter mappings to the /orders/create endpoint.
parameters that have no equivalent mapping in V3.

/orders/preview mappings

V2 - processBooking: query parameter	Maps to V3 - /orders/preview: request body field
`block_ids,` `block_quantities`	`accommodation.products.id` Note: In V3, you do not specify a quantity for multiple `products`. Instead, you specify each instance as a separate item in the `products` array, using the same `id`.
`booker_country`, `booker_ip`	`booker.country`
`checkin`	`accommodation.checkin`
`checkout`	`accommodation.checkout`
`guest_quantities`	`accommodation.products.allocation`
`hotel_id`	`accommodation.id`
`currency`	`currency`
`user_platform`	`booker.platform`
`room1`	`products.allocation`
`travel_purpose`	`booker.travel_purpose`

/orders/create mappings

V2 - processBooking: query parameter	Maps to V3 - /orders/create: request body field
`affiliate_label`	`accommodation.label`
`booker_country`, `booker_ip`	`booker.address.country`
`booker_telephone`	`booker.telephone`
`booker_address`	`booker.address`
`booker_city`	`booker.address.city`
`booker_company`	`booker.company`
`booker_firstname`	`booker.name.first_name`
`booker_language`	`booker.language`
`booker_lastname`	`booker.name.last_name`
`booker_zip`	`booker.address.post_code`
`cc_cardholder`	`payment.card.cardholder`
`cc_cvc`	`payment.card.cvc`
`cc_expiration_date`	`payment.card.expiry_date`
`cc_number`	`payment.card.number`
`comments`	`accommodation.remarks:` > `special_requests`
`extras=auth_form_url`	`payment.business_information:` > `authorisation_form`
`extras=receipt_url`	`payment.include_receipt`
`guest_emails`	`products.guests.email`
`guest_names`	`products.guests.name`
`hour_of_arrival`	`accommodation.remarks:` > `estimated_arrival_time`
`pay_now`, `payment_timing`	`payment.timing` Note: V3 handles payments differently to V2.
`payment_method`	`payment.method` Note: V3 handles payments differently to V2.
`vc_company_for_auth_form`	`payment.business_information:` > `company`
`vc_company_vat_number_for_invoices`	`payment.business_information:` > `billing.vat`
`vc_invoice_email`	`payment.business_information:` > `billing.email`
`vc_itemised_charges`	`payment.business_information:` > `authorisation_form.chargeble_items`

Parameters with no V3 equivalent

V2 - processBooking: query parameter	No V3 equivalent:
`affiliate_id`	You must include the affiliate id in the `X-Affiliate-Id` header of each /orders/preview or /orders/create request. For more information, see Authentication and authorisation.
`addon_prices`	Not available
`bed_preferences`, `bedtype_preferences`	You can specify the `id` of the preferred bed configuration in `/orders/create`, in the `accommodation.products.bed_configuration` request field. (You can obtain the available `bed_configuration` ids from `/accommodations/details`.)
`cc_type`	Not available
`extras=hotel_contact_info`	You can obtain this information from `/accommodations/details`.
`forwarded_user_agent`	Not available
`guest_cc`	Not available. Use `booker.country` in `/orders/preview` instead.
`incremental_prices`	Not required
`next_trips`	Not available
`options=allow_past`	Not required
`options=booker_mailinglist_signup`	Not available
`request_id`	Not available
`show_test`, `test_mode`	Not available Use the Demand API sandbox server (https://demandapi-sandbox.booking.com) for testing.
`smoking_preferences`	Not available
`vc_invoice`, `vc_invoice_to_guest`	Not required. Use `payment.business_information.billing.email` to specify where to send the invoice.
`vc_itemised_charge_breakfast` `vc_itemised_charge_food_beverage` `vc_itemised_charge_internet` `vc_itemised_charge_parking` `vc_itemised_charge_phone` `vc_itemised_charge_taxes` `vc_itemised_charge_total`	Not available
`vc_phones_for_auth_form_pin`	Not available

Important

In V2 there are multiple endpoints (canChangeRoomReservation, changeHotelReservation and changeRoomReservation) to modify reservation details such as arrival date, departure, credit card details, etc.

Note there are currently no equivalents for those in V3 (This is subject to 2025 roadmap planning).

Response schema mappings

This section contains the following tables:

/orders/preview response mappings
/orders/create response mappings
/accommodations/details response mappings
Fields with no V3 equivalent

/orders/preview response mappings

No fields from the V2 processBooking response map to the V3 /orders/preview response.

/orders/create response mappings

V2 - processBooking: response field	V3 - /orders/create: response field
`pincode`	`accommodation.pincode`
`receipt_url`	`payment.receipt_url`
`reservation_id`	`accommodation.reservation` An `order` id is also returned. See Reservation ids and order ids

/accommodations/details response mappings

V2 - processBooking: response field	V3 - /accommodations/details: response field
`hotel_contact_info:` > `hotel_telephone`	`contacts:` > `general.telephone` > `reservation.telephone`

Fields with no V3 equivalent

V2 - processBooking: response field	No V3 equivalent: notes
`auth_form_url`	Not available
`gmaps_url`	Not available
`next_trips:` > `name` > `id`	Not available