Create or update derived pricing rates

Use the derivedprices endpoint to specify derived 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.

Setting the same value for both occupancy (in the persons attribute) and the leading_occupancy returns an OCCUPANCY_INVALID error with the following message: Occupancy should be positive, different than leading_occupancy, and lower than the room's capacity. Make sure to specify an occupancy value which is different from the leading_occupancy value.

Header parameter

Header	Description	Type	Required/ Optional	Notes
`Accept-Version`	Specify the version number to get the API functionality specific to that version.	string	optional	Supports the following values: - 1.1: New version. - 1.0: Sunset version. If used, the endpoint returns a 400 Not acceptable error.

Sample header

POST 'https://supply-xml.booking.com/hotels/xml/derivedprices' \
--header 'Accept-Version: 1.1' \
--header 'Authorization: Basic THVjLVNhbXVlbMblmRAdlOCghQ29qaU9pNmxlWSpIWXU9OigvS2meQpQ12puj' \
--header 'Content-Type: application/xml'

HTTP request

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

Request body

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

Response body

<ok></ok>
<!-- RUID: [UmFuZG9tSVYkc2RlIyh9YWDBx32oy3x3Ccs+urTlxzG2rsOzD1t9dXjyrNEjkjXKN0kEqyEPcel6V+ZiSJd0BvJNx9uCzmGE] -->

The above example will do the following: For the room/rate product of room with ID 1000202 (<room id="1000202">) and rate with ID 12345, the leading occupancy will be set to 2 persons (<rate id="12345" leading_occupancy="2">). This means that, every time a price is set for a room/rate/date product of room/rate ID's 1000202/12345, that price will correspond to a 2-persons booking. The following <occupancy> elements set the derived pricing rules for other occupancies of the same room/rate: For a 3-persons booking, the price will correspond to 25% more, always rounded down to 0 decimal places: <occupancy persons="3" percentage="25" round="1" />. For a 4-persons booking, the price will correspond to an additional amount of 10 in the currency set: <occupancy persons="4" additional="10" />. For a 5-persons booking, the price will correspond to 15% less: <occupancy persons="5" percentage="-15" />. For a 6-persons booking, the price will correspond to an amount decreased by 5, in the currency set, never rounded down: <occupancy persons="6" additional="-5" round="0" />.

Request fields

request

Mandatory: Yes

Content type: (none)

Parent node: (none)

Multiplicity: 1

Attributes: (none)

Constraints: (none)

Description: This is the root element of every derivedprices call.

Syntax example: <request></request>

username

Mandatory: Yes

Content type: String

Parent node: request

Multiplicity: 1

Attributes: (none)

Constraints: (none)

Description: This is the username of the machine account being used to connect.

Syntax example: <username>xml_username</username>

password

Mandatory: Yes

Content type: String

Parent node: request

Multiplicity: 1

Attributes: (none)

Constraints: (none)

Description: This is the password of the machine account being used to connect.

Syntax example: <password>xml_password</password>

rooms

Mandatory: Yes

Content type: (none)

Parent node: request

Multiplicity: 1

Attributes: (none)

Constraints: (none)

Description: This is the structural element which contains the set of rooms which are to be updated with this call.

Syntax example: <rooms></rooms>

room

Mandatory: Yes

Content type: (none)

Parent node: rooms

Multiplicity: 1..X

Attributes: id (integer)

Constraints: Attribute 'id' is mandatory.

Description: This is the element describing a specific room which will be updated with this call. The 'id' attribute is the Booking.com system numeric identifier of the room.

Syntax example: <room id="1000202"></room>

rates

Mandatory: Yes

Content type: (none)

Parent node: room

Multiplicity: 1

Attributes: (none)

Constraints: (none)

Description: This is the structural element which contains the set of rates, for the specified room, whose corresponding room/rate products are to be updated with this call.

Syntax example: <rates></rates>

rate

Mandatory: Yes

Content type: (none)

Parent node: rates

Multiplicity: 1..X

Attributes: id (integer), leading_occupancy (integer)

Constraints: Attributes 'id' and 'leading_occupancy' are mandatory.

Description: This is the element describing a specific rate which will be updated with this call. The 'id' attribute is the Booking.com system numeric identifier of the rate. The 'leading_occupancy' attribute is the room/rate standard occupancy to which all further price specifications will be applied.

Syntax example: <rate id="12345" leading_occupancy="2"></rate>

occupancy

Mandatory: Yes

Content type: (none)

Parent node: rate

Multiplicity: 1..X

Attributes: persons (integer), percentage (integer), additional (integer), round (boolean)

Constraints: Attribute 'persons' is mandatory. Attributes 'percentage' and 'additional' cannot be both set, just one.

Description: This is the element describing a derived pricing rule for a specific occupancy, in which the 'persons' attribute states the number of persons of the occupancy. The derived pricing rule can be set by either the 'percentage' attribute, which states the increase or decrease in price compared to the leading occupancy percentage-wise, or the 'additional' attribute, which states by how much more (or less) does the price increase (or decrease) compared to the leading occupancy in terms of actual currency amount. An optional 'round' boolean attribute states whether this derived price should always be rounded down (round="1") or not (round="0") . The default value for 'percentage', 'additional', and 'round' is 0.

Syntax example: <occupancy persons="3" percentage="25" round="1" />

Response fields

On success, the response will consist exclusively on an <ok></ok> element, as well as the RUID string as comment, which is used by the Booking.com staff to trace back any updates made before, as well as for debugging purposes.

Syntax example:

<ok></ok>
<!-- RUID: [UmFuZG9tSVYkc2RlIyh9YWDBx32oy3x3Ccs+urTlxzG2rsOzD1t9dXjyrNEjkjXKN0kEqyEPcel6V+ZiSJd0BvJNx9uCzmGE] -->

To remove a previously-set price for a specific occupancy, specify a price or percentage of 0.

Troubleshooting errors

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

Error codes

The following table summarises the new error codes for the derivedprices endpoint.

Error code	Error message	Notes
`INVALID_INPUT`	Invalid input: Input is invalid. Please refer to the 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_SHOULD_BE_POSITIVE_NUMBER`	Leading occupancy should be a positive number.	You are setting leading occupancy with a negative integer. 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
`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.

HTTP error code behaviour

The derivedprices endpoint standardises the treatment of the HTTP error codes.

If the endpoint encounters, the same value for both occupancy (in the persons attribute) and the leading_occupancy, then the endpoint returns a HTTP 400 error.