Implementing pricing types

Booking.com supports multiple pricing types for properties to choose from depending on their business needs and inventory setup. For an introduction to the supported pricing types and to help you identify a suitable pricing type for your properties, see Identifying the right pricing type.

Use this section to understand:

The effect of changing the pricing type on the pricing of existing room inventory.
The rules to create room inventory based on a particular pricing type.

For more information on how to set and view pricing types, see Configuring and retrieving pricing types.

Effects of changing the pricing type

The following table captures the pricing changes that is applied to the existing inventory when you change the pricing type at the property level.

Exercise caution before changing the pricing type

Changing a property's pricing type after creating roomrates and inventory/rates can result in unintentional pricing changes to your existing inventory. Make sure to review your inventory immediately after the change.

Changing from standard pricing

The following table shows the pricing changes to the existing inventory when you change the property's pricing type from standard to any available pricing type option.

To review the definition of standard price and base price, see the Pricing definitions section.

Current pricing type	New pricing type	How do prices change
Standard pricing	Derived pricing	Standard price becomes base occupancy price. Prices for other occupancies need to be defined.
Standard pricing	Occupancy-based pricing	Standard price becomes maximum occupancy price. Prices for other occupancies need to be defined. Closed dates, restrictions and inventory also need to be checked and redefined, if required.
Standard pricing	Length of stay pricing	Standard price and single occupancy price (if any) are lost. All prices need to be redefined. Closed dates, restrictions and inventory also need to be checked and redefined, if required.

Changing from derived pricing

The following table shows the pricing changes to the existing inventory when you change the property's pricing type from derived pricing to any available pricing type option.

To review the definition of standard price and base price, see the Pricing definitions section.

Current pricing type	New pricing type	How do prices change
Derived pricing	Standard pricing	Base occupancy price becomes standard price.
Derived pricing	Occupancy-based pricing	Base occupancy price becomes maximum occupancy price. Prices for other occupancies need to be defined. Closed dates, restrictions and inventory also need to be checked and redefined, if required.
Derived pricing	Length of stay pricing	Base occupancy price is lost. All prices need to be redefined. Closed dates, restrictions and inventory also need to be checked and redefined, if required.

Changing from occupancy-based pricing (OBP) or length of stay pricing (LOS)

When changing from occupancy-based pricing or length of stay pricing to any other pricing types, you have to specify prices, closed dates, restrictions and inventory again.

To review the definition of standard price and base price, see the Pricing definitions section.

Current pricing type	New pricing type	How do prices change
Occupancy-based pricing/ Length of stay pricing	Standard pricing/ Derived pricing/ occupancy-based pricing/ length of stay pricing	All prices need to be redefined. Closed dates, restrictions and inventory also need to be checked and redefined, if required.

Understanding pricing types with examples

This section contains additional information to implement pricing types with code examples.

Although you set the pricing type at the property level, you specify price(s) for a combination of room type, roomrate and date while creating inventory.

Pricing values should match the pricing type

When creating an inventory, make sure to specify pricing values specific to the pricing type assigned to the roomrate. For example, you cannot set a fixed price for a single guest using the <price1> element if the pricing type assigned to the roomrate is RLO. Instead you must specify pricing offsets per occupancy level following RLO specifications.

Standard pricing type

Under the standard pricing type, you must specify two prices, except for rooms created with RoomType=10 (Single room):

A default price for the maximum number of adult guests.
A price for a single adult guest.

For single rooms, where single occupancy and maximum occupancy are the same, you can only specify a price for maximum occupancy.

To update maximum adult/child occupancy for a room type, use the [OTA_HotelInvNotif endpoint.] managing-room-types

→ You can also use the OTA_HotelProductNotif endpoint to specify the maximum adult occupancy for a room, but note that doing so changes the roomrate's pricing type to RLO.

You can specify an inventory and pricing using one of the following endpoints:

Setting standard pricing type using B.XML

If you're using the /xml/availability endpoint, use price to specify the price for maximum occupancy, and price1 to specify the price for single occupancy:

<request>
  <version>1.0</version>
  <room id="1000202">
    <date value="2018-08-28">
      <rate id="12345"/>
      <price>150.00</price>
      <!-- <price> is the default price for maximum occupancy. -->
      <price1>135.00</price1>
      <!-- <price1> is the price for one adult. -->
    </date>
  </room>
</request>

For field details and more elaborate samples, see the /xml/availability page.

Setting standard pricing type using OTA XML

If you're using the /ota/OTA_HotelRateAmountNotif endpoint, specify the prices inside BaseByGuestAmt elements:

<!-- This is an excerpt and not a working sample request. -->
<Rates>
  <Rate>
    <BaseByGuestAmts>
      <BaseByGuestAmt
        AmountAfterTax="4500"
        DecimalPlaces="2"/>
        <!-- A <BaseByGuestAmt/> element without a @NumberOfGuests
             attribute specifies the default price for maximum occupancy. -->
      <BaseByGuestAmt
        AmountAfterTax="3800"
        DecimalPlaces="2"
        NumberOfGuests="1"/>
        <!-- A <BaseByGuestAmt/> element with @NumberOfGuests="1"
             specifies the price for one adult. -->
    </BaseByGuestAmts>
  </Rate>
</Rates>
<!-- End of excerpt. -->

For more elaborate examples, see /ota/OTA_HotelRateAmountNotif.

Cannot set single occupancy price without activating the rate

The API returns the following error response when you try to set a single occupancy price for a room that does not have the single occupancy rate activated.
"Error code= OBP_PRICING_PASSED_FOR_DEFAULT_RATE" ShortText="BaseByGuestAmt (NumberOfGuests="1"): supplied number of guests '1' doesn't match"....
To resolve the error, you can either avoid specifying a single occupancy price for the room or activate the single use feature flag. To learn more on how to activate the feature, the property can contact their local support office using the contact details on the Inbox tab under Booking.com Messages in the extranet.

Derived pricing type

Using the derived pricing type, you can specify a price for a standard occupancy count (base occupancy), and one or more pricing offsets to derive prices for other occupancy sizes. An offset can be a percentage of the base price or a fixed amount.

To specify derived pricing, you must use two endpoints:

Specify base occupancy price using one of the following endpoints:
- B.XML endpoint: inventory
- OTA XML endpoint: OTA_HotelRateAmountNotif
Specify pricing offsets using derivedprices

Step 1 — Specify standard price

Use the b_xml-availability endpoint to set a price for maximum occupancy like you would set for the standard pricing type. However, you cannot set single occupancy price for a single adult using this endpoint when the roomrate pricing type is RLO.

After specifying prices for your rooms, you can specify the desired offsets.

Step 2 — Specify offsets

The following request to /xml/derivedprices specifies that:

the standard price applies when 2 people stay in the room.
when 1 person stays in the room, the price is 20% lower than the price for 2 people.
when 3 people stay in the room, the price is 20% higher than the price for 2 people.

<request>
  <rooms>
    <room id="1000202">
      <rates>
        <rate id="12345" leading_occupancy="2">
          <occupancy persons="1" percentage="-20" />
          <occupancy persons="3" percentage="20" />
        </rate>
      </rates>
    </room>
  </rooms>
</request>

For details about these fields and others, see the /xml/derivedprices page.

Occupancy-based Pricing (OBP)

To create inventory using occupancy-based pricing (OBP), you must specify a price for every combination of room type, roomrate, date, and number of occupants. Unlike the derived pricing type, you cannot specify offsets based on a base price. Instead, you must specify an absolute amount for each number of occupants.

The OBP model enables you to specify prices for adults and children that are priced as adults in the price[@NumberOfGuests] and the BasedByGuestAmt[@NumberOfGuests] fields. In addition, you can specify occupancy-based prices for children by implementing Flexible children rates. To learn more, see [the Flexible children rates documentation.(/connectivity/docs/flexible-children-rates/managing-flexible-children-rates.md)

Number of guests should not exceed maximum occupancy of the room

When specifying the price for each occupancy-level, ensure that you do not set pricing exceeding the maximum occupancy of that room. To retrieve the maximum occupancy details of the room, you can use one of the following: OTA_HotelDescriptiveInfo endpoint or roomrates endpoint. To set or update the maximum occupancy of a room, use OTA_HotelInvNotif endpoint or OTA_HotelProductNotif endpoint.

With the OBP type, you can use either the B.XML or OTA endpoint.

B.XML Example

This is an excerpt of a request you can send to /xml/availability. You can see the price[@NumberOfGuests] field specifies the prices for one, two, and three occupants (adults and children that are priced as adults):

<?xml version="1.0" encoding="UTF-8"?>
<request>
  <room id="999999999">
    <date from="2019-05-22" to="2019-05-23">
      <price numberofguests="1">100</price>
      <price numberofguests="2">120</price>
      <price numberofguests="3">140</price>
      <rate id="88888888" />
    </date>
  </room>
</request>

OTA Example

This is an excerpt of a request you can send to /ota/OTA_HotelRateAmountNotif. You can see the BasedByGuestAmt[@NumberOfGuests] field specifies the prices for one, two, and three occupants (adults and children that are priced as adults):

      <Rates>
        <Rate>
          <BaseByGuestAmts>
            <BaseByGuestAmt NumberOfGuests="1" AmountBeforeTax="10000" DecimalPlaces="2" />
            <BaseByGuestAmt NumberOfGuests="2" AmountBeforeTax="12000" DecimalPlaces="2" />
            <BaseByGuestAmt NumberOfGuests="3" AmountBeforeTax="14000" DecimalPlaces="2" />
          </BaseByGuestAmts>
        </Rate>
      </Rates>

Length-of-Stay (LOS)

While creating inventory using the LOS pricing type, you must specify the check-in date, the number of occupants, and pricing for a room that corresponds to a particular number of nights. Starting from the day of the request, you can send prices for up to 729 days into the future.
When using the LOS pricing type, you cannot specify inventory restrictions.

You can use either the CSV or OTA endpoint.

CSV example

To send a request to the /csv/los_pricing endpoint, you must use comma-separated values to specify:

Check-in date
Level of occupancy (should not exceed MaxOccupancy)
Room ID
Rate ID
Currency code
Prices list

You must place the preceding elements in the following format:

{check-in date},{number of occupants},{room ID},{rate ID},{currency code},{price for 1 night},{price for 2 nights},{price for 3 nights},...

OTA Example

To send a request to the /ota/OTA_HotelRateAmountNotif endpoint, you must use:

The Rate[@UnitMultiplier] field to specify the length of stay 1-2.
The BasedByGuestAmt[@NumberOfGuests] field to specify the number of occupants 1-2.
The BasedByGuestAmt[@AmountBeforeTax] field to specify the price per night for a specified number of occupants.

In this example the total price for 2 guests staying for 2 nights is (length of stay) * (price per night for 2 guests for length of stay 2) = 2 * 290 = 580.

<!-- This is an excerpt and not a working sample request. -->
      <Rates>
        <Rate RateTimeUnit="Day" UnitMultiplier="1">
         <BaseByGuestAmts>
            <BaseByGuestAmt AmountBeforeTax="300" NumberOfGuests="1" />
            <BaseByGuestAmt AmountBeforeTax="310" NumberOfGuests="2" />
         </BaseByGuestAmts>
        </Rate>
        <Rate RateTimeUnit="Day" UnitMultiplier="2">
         <BaseByGuestAmts>
            <BaseByGuestAmt AmountBeforeTax="280" NumberOfGuests="1" />
            <BaseByGuestAmt AmountBeforeTax="290" NumberOfGuests="2" />
         </BaseByGuestAmts>
        </Rate>
      </Rates>
<!-- End of excerpt. -->