Retrieving promotion details

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 for 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 you want to retrive promotions for.	integer	1..1	-
`id`	(optional) An ID for the specific promotion.	string	0..1	-
`active`	(optional) The promotion's status (active/deactivated).	boolean	0..1	Accepts: `1` (active), `0` (deactivated).
`name`	(optional) The promotion's name.	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="0" 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 some extra detail 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
`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
	`non_refundable`	Whether or not the guest can receive a refund if they cancel.	boolean
	`total_revenue`	The gross 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 gross bookings with this promotion.	integer
	`nr_cancellations`	The total number of cancellations with this promotion.	integer

Errors

For a complete list of error codes and possible solutions, see Troubleshooting and list of error codes.