Retrieving promotion details

Business booker rates has been sunset

Booking.com has sunset Business booker rates since September 16, 2022 and is therefore no longer usable.

Use getpromotions endpoint to retrieve promotions by:

ID,
Promotion name, and/or,
Active status.

The endpoint returns the details of the most recent update for promotions with multiple updates. The response includes statistics like total revenue, number of nights reserved, total bookings, and total cancellations.

Promotion statistics available up to the last 12 months

Booking.com will start retaining promotion statistics for 12 months, effective on September 15, 2024. The getpromotions endpoint will thereby return promotion statistics up to 12 months.

For more information on how to create and manage promotions, see Managing promotions.

URL

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

Sample request

You can use the id value of the existing promotion in the id request parameter.

<request>
    <hotel_id>1234</hotel_id>
    <id>TB1596220037234</id>
    <active>1</active>
    <name>Summer Deal</name>
</request>

Request body

Field	Description	Type	Occurrences	Notes
`request`	Root element.	object	1..1	-
`hotel_id`	The ID of the property for which you want to retrieve promotions.	integer	1..1	-
`id`	Specifies an (optional) promotion ID (`id`) by which to filter the response.	string	0..1	-
`active`	Specifies an (optional) promotion status (active/deactivated) by which to filter the response.	boolean	0..1	Accepts: `1` (active), `0` (deactivated).
`name`	Specifies an (optional) promotion name by which to filter the response.	string	0..1	-

Sample response

This example contains all possible fields that can be included in the response.

<promotions>
  <promotion id="TB12345596220037" name="Summer Deal" type="basic" target_channel="public" min_stay_through="2" non_refundable="-1" min_booked_nights="2" no_cc_promotion="0" active="1">
    <last_minute unit="-1" value="-1"></last_minute>
    <early_booker value="-1"></early_booker>
    <book_date start="-1" end="-1"></book_date>
    <book_time start="-1" end="-1"></book_time>
    <stay_date start="2024-08-20" end="2024-08-30">
      <active_weekdays>
        <active_weekday>Mon</active_weekday>
        <active_weekday>Tue</active_weekday>
        <active_weekday>wed</active_weekday>
        <active_weekday>Thu</active_weekday>
        <active_weekday>Fri</active_weekday>
        <active_weekday>Sat</active_weekday>
        <active_weekday>Sun</active_weekday>
      </active_weekdays>
      <excluded_dates>
        <excluded_date>2024-08-22</excluded_date>
      </excluded_dates>
    </stay_date>
    <additional_dates>
      <additional_date>2023-09-01</additional_date>
      <additional_date>2023-08-31</additional_date>
    </additional_dates>
    <rooms>
      <room id="12223"></room>
      <room id="12345"></room>
    </rooms>
    <parent_rates>
      <parent_rate id="435345"></parent_rate>
    </parent_rates>
    <discount value="5"></discount>
  </promotion>
  <promotion id="TB34234596220037" name="Lastminute hurry" type="last_minute" target_channel="public" min_stay_through="0" non_refundable="-1" min_booked_nights="0" no_cc_promotion="0" active="1">
    <last_minute unit="hour" value="8"></last_minute>
    <early_booker value="-1"></early_booker>
    <book_date start="-1" end="-1"></book_date>
    <book_time start="-1" end="-1"></book_time>
    <stay_date start="2023-06-10" end="2023-06-10">
      <active_weekdays>
        <active_weekday>Fri</active_weekday>
      </active_weekdays>
      <excluded_dates></excluded_dates>
    </stay_date>
    <additional_dates></additional_dates>
    <rooms>
      <room id="1000419"></room>
    </rooms>
    <parent_rates>
      <parent_rate id="12345"></parent_rate>
      <parent_rate id="47568"></parent_rate>
    </parent_rates>
    <discount value="10"></discount>
    <stats>
      <total_revenue value="418.95" currency="EUR"></total_revenue>
      <nr_room_nights>1</nr_room_nights>
      <nr_bookings>1</nr_bookings>
      <nr_cancellations>0</nr_cancellations>
    </stats>
  </promotion>
</promotions>
<!-- RUID: [...] -->

Response body parameters

This table provides more details about some of the fields in the response.

Note

Not all fields are relevant for all response types. A value of -1 indicates that the current field is not relevant for the current response type.

Element	Attribute	Description	Type	Notes
`promotions`		Root element.	array of `promotion`
> `promotion`		Promotion details.	object
	`id`	The most recently generated promotion ID.	string
	`name`	Name of the promotion.	string
>> `stats`		Includes statistical details	object
	`target_channel`	Name of the promotion channel.	string
	`min_stay_through`	Specifies the minimum number of stay nights that the guests should book to qualify for the promotion.	string
	`non_refundable`	Specifies whether the stays booked through this promotion are refundable.	boolean
	`min_booked_nights`	Specifies the minimum number of stay nights that the guests should book to qualify for the promotion.	string
	`no_cc_promotion`		string
	`active`	Specifies whether the promotion is active.	boolean
	`total_revenue`	The total revenue from all bookings with this promotion, in the property's default currency.	integer	-
	`nr_room_nights`	The total number of room nights booked with this promotion.	integer	-
	`nr_bookings`	The total number of bookings with this promotion.	integer	-
	`nr_cancellations`	The total number of cancellations with this promotion.	integer	-

Errors

Schema validation errors

HTTP/1.1 400 Bad Request

<?xml version='1.0' standalone='yes'?>
<getpromotions>
  <fault code="400">
    <string>code= 1824 level= 2 message= Element 'hotel_id': 'test hotel' is not a valid value of the atomic type 'xs:integer'.
</string>
  </fault>
</getpromotions>
<!-- RUID: [...] -->

Invalid ID errors

HTTP/1.1 403 Forbidden

<?xml version='1.0' standalone='yes'?>
<getpromotions>
  <fault code="1009">
    <string>Access denied for hotel '234324'</string>
  </fault>
</getpromotions>
<!-- RUID: [...] -->

HTTP/1.1 400 Bad Request

<?xml version='1.0' standalone='yes'?>
<getpromotions>
  <fault code="400">
    <string>Invalid promotion ID= 12559622003775278</string>
  </fault>
</getpromotions>
<!-- RUID: [...] -->