Create or update derived pricing rates

Use the derivedprices endpoint to specify derived(RLO) pricing for specific room/rate products. While creating derived pricing you must:

Set a leading occupancy for that room/rate. For example 2 persons.
Set derived pricing rules for other possible occupancies that this room/rate can accommodate. For example, price for 3 persons is 50% more.

This means that, whenever a price is set for a specific room, rate and date combination, the price is for the leading occupancy. However, the derived pricing rules determine the prices for the same room, rate and date combination, but for different occupancy sizes.

This endpoint converts room rates to RLO pricing type

Make sure you understand pricing models before using this endpoint. Check Understanding pricing models.

Endpoint

POST https://supply-xml.booking.com/hotels/xml/derivedprices

Request

Headers

Header	Description	Type	Required	Notes
`Accept-Version`	Specify the version number to get the API functionality specific to that version.	string	Required	Supports the following values: - 1.1: Default version
`Content-Type`	Request content type	string	Required	Must be `application/xml`

Request body

Element	Attribute	Description	Type	Required	Notes
`request`		Root element of every derivedprices call.	object	Required	-
> `rooms`		Structural element which contains the set of rooms which are to be updated.	object	Required	-
>> `room`		Element describing a specific room which will be updated.	object	Required	Multiple rooms allowed (1..X)
	`id`	The Booking.com system numeric identifier of the room.	integer	Required	-
>>> `rates`		Structural element which contains the set of rates, for the specified room, whose corresponding room/rate products are to be updated.	object	Required	-
>>>> `rate`		Element describing a specific rate which will be updated.	object	Required	Multiple rates allowed (1..X)
	`id`	The Booking.com system numeric identifier of the rate.	integer	Required	-
	`leading_occupancy`	The room/rate standard occupancy to which all further price specifications will be applied.	integer	Required	Must be a positive number that does not exceed the room's maximum adult occupancy.
>>>>> `occupancy`		Element describing a derived pricing rule for a specific occupancy.	object	Required	Multiple occupancy rules allowed (1..X)
	`persons`	The number of persons for this occupancy.	integer	Required	Must be positive, different from `leading_occupancy`, and lower than or equal to the room's capacity.
	`percentage`	The increase or decrease in price compared to the leading occupancy percentage-wise.	integer	Conditional	Cannot be set together with `additional`. Minimum value: -100. Default: 0
	`additional`	The increase or decrease in price compared to the leading occupancy in terms of actual currency amount.	integer	Conditional	Cannot be set together with `percentage`. Default: 0
	`round`	Whether this derived price should always be rounded down.	boolean	Optional	Accepts: `1` (round down), `0` (don't round). Default: `0`

Request example

The request below sets derived pricing for room type 1000202 with rate 12345:

Leading occupancy is set to 2 persons
For 3 persons: price is 25% more, rounded down
For 4 persons: price increases by 10 (currency units)
For 5 persons: price is 15% less
For 6 persons: price decreases by 5 (currency units), not rounded

<request>
  <username>xml_username</username>
  <password>xml_password</password>
  <rooms>
    <room id="1000202">
      <rates>
        <rate id="12345" leading_occupancy="2">
          <occupancy persons="3" percentage="25" round="1" />
          <occupancy persons="4" additional="10" />
          <occupancy persons="5" percentage="-15" />
          <occupancy persons="6" additional="-5" round="0" />
        </rate>
      </rates>
    </room>
  </rooms>
</request>

Removing derived prices

You can remove derived prices in the following ways:

Remove all derived prices for a room-rate

To remove all derived pricing rules for a specific room-rate combination, provide a <rate> element with no <occupancy> child elements:

<request>
  <username>xml_username</username>
  <password>xml_password</password>
  <rooms>
    <room id="1000202">
      <rates>
        <rate id="12345" leading_occupancy="2">
          <!-- No occupancy elements = removes all derived prices -->
        </rate>
      </rates>
    </room>
  </rooms>
</request>

Remove specific occupancy rules

If you omit any previously configured occupancy from your request, those occupancy rules will be automatically removed. Only the occupancies included in the request will be retained.

Example: If a room-rate previously had derived prices for 3, 4, and 5 persons, but you send a request with only occupancy for 3 persons, the derived prices for 4 and 5 persons will be removed.

<request>
  <username>xml_username</username>
  <password>xml_password</password>
  <rooms>
    <room id="1000202">
      <rates>
        <rate id="12345" leading_occupancy="2">
          <occupancy persons="3" percentage="25" round="1" />
          <!-- Occupancies for 4 and 5 persons will be removed -->
        </rate>
      </rates>
    </room>
  </rooms>
</request>

Partial updates remove unlisted occupancies

This endpoint does not support partial updates. Any occupancy not included in your request will be removed from the room-rate configuration. Always include all occupancy rules you want to maintain.

Response

Response body

Field	Attribute	Description	Type	Notes
> `ok`		Indicates a successful request.	object	Only returned if there are no errors.
> `derivedprices`		Root element for error responses.	object	-
>> `errors`		Groups a list of individual errors.	object	-
>>> `error`		List details of individual errors.	object	-
	`code`	Returns an error code for an error.	string	-
>>>> `message`		Returns a user-friendly error message with a possible resolution to the error.	string	-
>>>> `details`		Contains additional error details.	object	-

Response examples

Success response

<ok></ok>
<!-- RUID: [Example-RUID] -->

Error response (HTTP 400)

<?xml version='1.0' encoding='UTF-8'?>
<derivedprices>
  <errors>
    <error code="OCCUPANCY_INVALID">
      <details>
        <room_ids>1000202</room_ids>
        <occupancy>5</occupancy>
        <rate_ids>12345</rate_ids>
      </details>
      <message>Occupancy should be positive, different than leading_occupancy, and lower than the room's capacity</message>
    </error>
  </errors>
</derivedprices>
<!-- RUID: [Example-RUID] -->

Troubleshooting errors

This section covers the error responses you might encounter when using this endpoint.

Error codes

The following table summarizes the error codes for the derivedprices endpoint:

Error code	Error message	Description
`INVALID_INPUT`	Invalid input: Input is invalid. Please refer to API documentation.	The request contains a field with invalid data type. Review the input fields and make sure they have the correct data type as stated in the documentation.
`LEADING_OCCUPANCY_MISSING`	Leading occupancy is missing.	The `leading_occupancy` attribute is required but was not provided in the `<rate>` element. Specify a positive integer for the `leading_occupancy` attribute.
`LEADING_OCCUPANCY_SHOULD_BE_POSITIVE_NUMBER`	Leading occupancy should be a positive number.	You are setting leading occupancy with a negative integer or zero. Specify a positive integer for the `leading_occupancy` attribute which does not exceed the number of maximum adult occupancy `MaxAdultOccupancy` or `max_adults` in the room. For more information on how to set the maximum adult occupancy in a room, see Managing room types and Managing units.
`OCCUPANCY_ADJUSTMENT_TOO_LOW`	Adjustment amount cannot go lower than -100%.	Specify a value equal to or higher than -100% for the `percentage` attribute. For example, -100%, -50%, 25%.
`OCCUPANCY_INVALID`	Occupancy should be positive, different than leading_occupancy, and lower than the room's capacity.	Specify a value for the `occupancy` attribute, which is: - a positive integer - different from the value of the `leading_occupancy` - less than or equal to the room maximum adult occupancy
`OCCUPANCY_EXCEEDS_MAX_OCCUPANCY`	Occupancy exceeds room capacity.	The occupancy value specified in the `persons` attribute exceeds the room's maximum adult occupancy. Reduce the occupancy value to be within the room's capacity limits.
`RATE_ID_DOESNOT_BELONG_TO_ROOM`	Rate does not belong to room.	There is no existing roomrate with the provided room ID and rate ID. Create a roomrate with the same room ID and rate ID specified in the request. You can use the `OTA_HotelProductNotif` endpoint to create the roomrate.
`RATE_IS_A_SLAVE_RATE`	Cannot edit child rates.	The rate ID provided is configured as a child rate (slave rate). Derived pricing can only be set on parent rates. Use the parent rate ID instead, or convert the child rate to a parent rate.
`ROOM_ID_INVALID`	Room ID '[room_id]' is not valid.	The room ID provided does not exist or does not belong to your property. Verify the room ID is correct and belongs to the property you're updating. You can retrieve valid room IDs using the rooms API.
`ROOM_ID_MISSING`	Room ID is missing.	The `id` attribute is required but was not provided in the `<room>` element. Specify a valid room ID in the request.
`DERIVED_PRICING_PASSED_FOR_LOS_RATE`	Cannot create derived prices for LOS pricing model rate.	The rate is configured with the LOS (Length of Stay) pricing model, which is incompatible with derived pricing. Derived pricing only works with Standard and RLO pricing models. Change the rate's pricing model or use a different rate.
`DERIVED_PRICING_PASSED_FOR_OBP_RATE`	Cannot create derived prices for OBP model rate.	The rate is configured with the OBP (Occupancy-Based Pricing) model, which is incompatible with derived pricing. Derived pricing only works with Standard and RLO pricing models. Change the rate's pricing model or use a different rate.