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. If you have a high number of promotions (100s or more) or the API is timing out, you can also paginate results by using the optional paginated and cursor request fields.
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.
This topic also provides the UI/UX recommendations for the getpromotions endpoint.
POST
https://supply-xml.booking.com/hotels/xml/getpromotionsYou 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>Example of a paginated request:
<request>
<hotel_id>1234</hotel_id>
<active>1</active>
<paginated>1</paginated>
<cursor>opaque-cursor-token</cursor>
</request>| 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 | Not supported when using pagination |
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 | Not supported when using pagination |
paginated | (optional) Whether to return a paginated response. | boolean | 0..1 | Accepts: 1 (paginated), 0 (non-paginated). |
cursor | (optional) The opaque pagination cursor returned in the next_cursor value. | string | 0..1 | Use this to request the next page when has_more=true. |
This example contains all possible fields that can be included in the response.
<promotions has_more="true" next_cursor="opaque-next-cursor">
<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: [...] -->This table provides some extra detail about some of the fields in the response.
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 | ||
has_more | Indicates whether there are more results available. | boolean | Optional. | |
next_cursor | The opaque cursor to include in the next request to retrieve the next page of results. | string | Optional. Returned only when more results are available. | |
> 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 |
We recommend displaying all of a property’s promotions in a single table with expandable rows for each promotion. As properties can often have a large number of promotions we also recommend adding some basic filters such as promotion status and type, as well as sorting for the table columns. Below we have provided an example implementation:
When expanding one of the promotion rows each promotion may have different information available. We recommend providing all relevant available information in this expanded view while still keeping the order of elements as consistent as possible.
Remember that not all promotion types can be edited and may require different CTAs in the detailed view.
For a complete list of error codes and possible solutions, see Troubleshooting and list of error codes.