Managing promotions

Use the Promotions API to create and manage promotions for an individual property.

Use the promotions endpoint to:

• Create a promotion by choosing from different promotion types
• Update a promotion to make changes to an existing promotion
• Activate a promotion that was previously deactivated. Newly created and updated promotions are active by default
• Deactivate a promotion if you no longer want it to be bookable

What are promotion types?

Each promotion type has a distinct way to attract customers and drive occupancy and revenue, by allowing you to be more price competitive on Booking.com for specific audiences and periods.

• Basic deal: Fully customisable to suit your specific needs

• Last-minute deal: A discount only available when booked closer to check-in – to help fill any empty rooms you have left

• Early booker deal: A discount only available when booking long before check-in – to be better prepared with more bookings made earlier

• Campaign deal: A seasonal sales event, with fixed bookable dates and stay dates. Properties offer a minimum discount (or more) and in exchange receive extra visibility from emails, push notifications, affiliate sites, graphics and landing pages on Booking.com and more, for the duration of the promotion

• Country rate: A discount only available to customers booking from a specific country or region. Booking.com supports a list of predefined geolocations

• Mobile rate: A device-specific discount only available to customers booking from a mobile device (mobile web or the Booking.com app)

Promotion details

Depending on the promotion type, you can select (among other things):

• Dates the promotion can be booked
• Specific time of day the promotion can be booked
• Stay dates
• Room types
• Rate plans the promotion will base its discount on
• How many days (or hours) before check-in a guest can receive a last-minute discount
• How many days in advance a guest must book to receive an early booker discount
• Specific regions and countries you offer the discount to
• Mobile device-specific discounts

For promotion types other than geo_rate and mobile_rate, you can also choose whether the promotion is available to [all guests, or only certain guests][#target-promotions-to-specific-audience].

Creating promotions

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

When creating a promotion, the mandatory list of request parameters varies depending on the promotion type. The following subsections help you create promotions using the various promotion types:

• Creating a basic deal.
• Creating a last-minute deal.
• Creating an early booker deal.
• Creating a campaign deal.
• Creating a country rate.
• Creating a mobile rate

Creating a basic deal

Use this promotion type to create a fully customisable promotion and specify a discount on selected rooms and the original rate plan

Sample request

The following request creates a basic deal:

<request>
   <hotel_id>12312</hotel_id>
    <promotion
        name="Summer Promotion"
        type="basic"
        target_channel="public"
        min_stay_through="3"
        non_refundable="0">
        <book_date start="2024-05-14" end="2024-07-31" />
        <book_time start="11" end="13" />
        <stay_date start="2024-06-06" end="2024-06-29">
            <active_weekdays>
               <active_weekday>Thu</active_weekday>
           </active_weekdays>
            <excluded_dates>
                <excluded_date>2024-06-15</excluded_date>
                <excluded_date>2024-06-16</excluded_date>
            </excluded_dates>
        </stay_date>
        <additional_dates>
            <additional_date>2024-07-18</additional_date>
            <additional_date>2024-07-20</additional_date>
        </additional_dates>
        <rooms>
            <room id="1423432"/>
            <room id="325436"/>
        </rooms>
        <parent_rates>
            <parent_rate id="756878"/>
            <parent_rate id="543754"/>
        </parent_rates>
        <discount value="10" />
    </promotion>
</request>

Request body

Target promotions to specific audience

Use the target_channel attribute to specify who can see the promotion. For promotion types basic, last_minute and early_booker, Booking.com supports the following values:

Important note about parent_rates

The Promotions API will apply a promotion to all rooms and rates specified in your request only if all rooms in the request are connected to all rates in the request. It will not create new roomrates.

Take the following example. Earlier, you sent two OTA_HotelProductNotif requests to create products with these room/rate combinations:

Then, you sent a promotions requests containing these lines:

<rooms>
  <room id="0"/>      
  <room id="1"/>    
</rooms>
<parent_rates>
  <parent_rate id="10"/>
  <parent_rate id="11"/>
  <parent_rate id="12"/>
</parent_rates>

The request will be successful, but the API will ignore the combination of room 1 and rate 10, because there is no product connecting them.

Sample response

<promotions>
    <id>TB449324213596220037</id>
</promotions>
<!-- RUID: [...] -->

If your request is successful, the API returns the ID of the newly created promotion. You must specify this ID when editing the promotion.

Response body parameters

Creating a last-minute deal

Use this promotion type to attract last-minute bookers. This promotion type may help sell leftover rooms, max out your occupancy, and increase your visibility on mobile devices.

Sample request

The following request creates a last-minute deal:

<request>
   <hotel_id>12312</hotel_id>
    <promotion
        name="Winter Promotion"
        type="last_minute"
        target_channel="public"
        non_refundable="0"
        min_stay_through="3">
        <last_minute unit="hour" value="5"/>
        <book_time start="11" end="13" />
        <stay_date start="2024-06-06" end="2024-06-29">
            <active_weekdays>
               <active_weekday>Thu</active_weekday>
           </active_weekdays>
            <excluded_dates>
                <excluded_date>2024-06-15</excluded_date>
                <excluded_date>2024-06-16</excluded_date>
            </excluded_dates>
        </stay_date>
        <additional_dates>
            <additional_date>2024-07-18</additional_date>
            <additional_date>2024-07-20</additional_date>
        </additional_dates>
        <rooms>
            <room id="1423432"/>
            <room id="325436"/>
        </rooms>
        <parent_rates>
            <parent_rate id="756878"/>
            <parent_rate id="543754"/>
        </parent_rates>
        <discount value="10" />
    </promotion>
</request>

Request body parameters

The parameters for creating a last-minute deal are similar to creating a basic deal, except for the following:

Last-minute deal type example

To create a last-minute deal for guests booking a stay within 2 days or fewer before their intended check-in, use these values:

<last_minute unit="day" value="2"/>

This promotion is only applied when a guest books two days or fewer before their intended check-in. The promotion is active from 2 days before check-in until 1 minute before check-in.

Sample response

See sample response for basic deal.

Response body parameters

Creating an early booker deal

Use this promotion type to attract early bookers. This promotion may help fill the property's low-season rooms early.

Sample request

The following request creates an early booker deal:

<request>
   <hotel_id>12312</hotel_id>
    <promotion
        name="Off-season Deal"
        type="early_booker"
        target_channel="public"
        non_refundable="0"
        min_stay_through="3">
        <early_booker value="15" />
        <book_time start="11" end="13" />
        <stay_date start="2024-06-06" end="2024-06-29">
            <active_weekdays>
               <active_weekday>Thu</active_weekday>
           </active_weekdays>
            <excluded_dates>
                <excluded_date>2024-06-15</excluded_date>
                <excluded_date>2024-06-16</excluded_date>
            </excluded_dates>
        </stay_date>
        <additional_dates>
            <additional_date>2024-07-18</additional_date>
            <additional_date>2024-07-20</additional_date>
        </additional_dates>
        <rooms>
            <room id="1423432"/>
            <room id="325436"/>
        </rooms>
        <parent_rates>
            <parent_rate id="756878"/>
            <parent_rate id="543754"/>
        </parent_rates>
        <discount value="10" />
    </promotion>
</request>

Request body

The fields for an early booker deal are the same as for a basic deal, except for the following:

Creating a campaign deal

Get extra visibility from emails, push notifications, affiliate websites, visuals on Booking.com and more, for the duration of any campaign you join.

• Black Friday Deal
• Early Year Deal
• Getaway Deal
• Late Escape Deal

Unlike other types of promotions, Marketing Campaigns must respect certain restrictions to be created (otherwise the creation requests will fail) and those restrictions are pertinent to each individual campaign. They are:

One more particularity about the Marketing Campaigns in relation to the other products is that you can only create or activate promotions of those types during the respective campaign sourcing period. It's also not possible to edit restrictions on a marketing campaign promotion once it's created (but you can always deactivate undesired promotions and create new ones).

Sample request

The following request creates a campaign deal for a specific campaign — in this example, a Black Friday Deal:

<request>
   <hotel_id>12312</hotel_id>
    <promotion
        name="Black Friday Deal"
        type="campaign_black_friday">
        <stay_date start="2025-08-16" end="2026-08-16">
            <active_weekdays>
               <active_weekday>Mon</active_weekday>
               <active_weekday>Tue</active_weekday>
               <active_weekday>Wed</active_weekday>
               <active_weekday>Thu</active_weekday>
           </active_weekdays>
            <excluded_dates>
                <excluded_date>2025-08-20</excluded_date>
                <excluded_date>2025-08-21</excluded_date>
            </excluded_dates>
        </stay_date>
        <additional_dates>
            <additional_date>2026-08-20</additional_date>
            <additional_date>2026-08-21</additional_date>
        </additional_dates>
        <rooms>
            <room id="1423432"/>
            <room id="325436"/>
        </rooms>
        <parent_rates>
            <parent_rate id="756878"/>
            <parent_rate id="543754"/>
        </parent_rates>
        <discount value="30" />
    </promotion>
</request>

Request body parameters

The parameters for creating a campaign deal are similar to creating a basic deal, except for the following:

Sample response

See sample response for basic deal.

Response body parameters

Creating a country rate

A country rate is a special, discounted rate that is only offered to customers from a specific region.

They are available to all customers from included regions, and apply to all room types, rates and dates except any which are specifically excluded. The discounted price can help to reach customers and increase revenue and bookings from a specific location.

Sample request

The following request creates a country rate promotion:

<request>
    <hotel_id>12312</hotel_id>
    <promotion
        type="geo_rate"
        target_channel="india_pos"
        min_stay_through="3">
        <stay_date>
            <excluded_dates>
                <excluded_date>2024-06-15</excluded_date>
                <excluded_date>2024-06-16</excluded_date>
            </excluded_dates>
        </stay_date>
        <parent_rates>
            <parent_rate id="756878"/>
            <parent_rate id="543754"/>
        </parent_rates>
        <early_booker value="15" />
        <discount value="15" />
    </promotion>
</request>

Request body

Creating a mobile rate:

Use a mobile rate to offer a discounted price to guests who book through the Booking.com Android or iOS mobile app, or from a mobile phone or tablet browser.

Using the target_channel app means guests booking (only) through the Booking.com mobile app can get this discount.

Using the target_channel all means guests booking through the Booking.com mobile app as well as guests booking through the Booking.com website using a mobile device can get this discount.

If you create mobile rates without specifying target_channel, by default, the API selects the app option.

Sample request

This request creates an app-only mobile rate:

<request>
    <hotel_id>12312</hotel_id>
    <promotion
        type="mobile_rate"
        target_channel="app"
        min_stay_through="3">
        <stay_date>
            <excluded_dates>
                <excluded_date>2024-06-15</excluded_date>
                <excluded_date>2024-06-16</excluded_date>
            </excluded_dates>
        </stay_date>
        <parent_rates>
            <parent_rate id="756878"/>
            <parent_rate id="543754"/>
        </parent_rates>
        <last_minute unit="day" value="5"/>
        <discount value="15" />
    </promotion>
</request>

Request body

Sample response

See sample response for basic deal.

Updating a promotion

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

You can update a promotion by including the promotion id in the request body and specifying only the fields that need to be updated.

On successful update, the promotion is marked as active irrespective of the previous status.

💡 Remember that promotions with stay dates in the past are not bookable, even if they are still active. Update the promotion and add stay dates in the future to make it bookable.

Sample request 1

The following example shows how to update the min_stay_through field for an existing promotion.

<request>
  <hotel_id>12312</hotel_id>
  <promotion
    id="TB210380259622003780"
    min_stay_through="3">
  </promotion>
</request>

Sample response 1

<promotions>
    <id>TB210454585596220037</id>
</promotions>
<!-- RUID: [...] -->

Sample request 2

The following example shows how to remove optional fields like (book_date, book_time, active_weekdays, excluded_dates, ....)

<request>
  ...
  <promotion
    ...
    target_channel="public"
    non_refundable="0"
    min_stay_through="0">
    <book_date/>
    <book_time/>
    <active_weekdays/>
    <excluded_dates/>
    <additional_dates/>
    ...
  </promotion>
</request>

Activating a promotion

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

Use this section to activate a deactivated promotion.

Sample request

The following request uses the promotion's id to activate the promotion.

<request>
    <hotel_id>12312</hotel_id>
     <promotion 
         id="TB210454585">
     </promotion>
 </request>

Sample response

<promotions>
    <id>TB210454585</id>
</promotions>
<!-- RUID: [...] -->

Deactivating a promotion

DELETE 
https://supply-xml.booking.com/hotels/xml/promotions?id={promotionID}&hotel_id={hotelID}

To deactivate a promotion, send a DELETE request including the promotion ID and property ID.

Query parameters

Sample response

<promotions>
    <id>TB210454585</id>
</promotions>
<!-- RUID: [...] -->

Errors

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