Managing promotions

The Promotions API enables you to create and manage promotions for a property.

Use the promotions endpoint to:

• Create a promotion by choosing from six different promotion types.
• Update a promotion to make changes to an existing promotion.
• Activate a promotion that was deactivated by the provider. Any newly created or updated promotion is, by default, marked as active.
• Deactivate an active promotion if you no longer want guests to use the promotion.

What are promotion types?

Promotion types help you create promotions for certain scenarios. Booking.com provides six promotion types, namely:

• Basic: Create a fully customisable promotion.
• Last minute: Promote maximum occupancy by leveraging unbooked rooms.
• Early booker: Attract early bookers.
• Geo rate: Offer special prices for guests from a specific location. Booking.com supports a list of predefined geolocations.
• Mobile rate: Offer special prices to mobile app users.

Promotion details

Depending on the promotion type selected, you can specify (among other parameters) the following:

• Bookable date range or time period when the promotion is available.
• The last minute stay date range within which the guests should book a stay to get a discount.
• The number of days in advance the guests must book to get a discount.
• A geolocation to offer discounts to guests booking from a specific location.
• A discount value as a percentage of the roomrate.

For promotion types other than geo_rate and mobile_rate, you can also choose whether a 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 based on the promotion type. The following subsections help you create promotions using the various promotion types.

• Creating a basic promotion.
• Creating a last minute promotion.
• Creating an early booker promotion.
• Creating a geo rate promotion.
• Creating a mobile rate promotion

Creating a basic promotion

Use this promotion type to create a fully customisable promotion and specify a discount on selected rooms and price/rate attached to a roomrate.

Sample request

The following request creates a basic promotion:

<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 other than geo_rate and mobile_rate, Booking.com supports the following values:

Important note about parent_rates

The API will only apply a promotion to all rooms and rates in your request that are connected through existing roomrates. It will not create a new roomrate if a room isn't connected to every rate, or vice versa.

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 promotion

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

<request>
   <hotel_id>12312</hotel_id>
    <promotion
        name="Winter Promotion"
        type="last_minute"
        target_channel="public"
        min_stay_through="3"
        non_refundable="0"
        no_cc_promotion="1">
        <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 promotion are similar to creating a basic promotion type, except for the following:

Last minute promotion type example

To create a last minute promotion 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 applied only when a guest books a stay two days or fewer before their intended check-in. This promotion is even applicable if a guest books a stay as close as 1 minute prior to their check-in.

Sample response

See sample response for basic promotion.

Response body parameters

Creating an early booker promotion

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

<request>
   <hotel_id>12312</hotel_id>
    <promotion
        name="Off-season Promotion"
        type="early_booker"
        target_channel="public"
        min_stay_through="3"
        non_refundable="0"
        no_cc_promotion="1">
        <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 promotion are the same as for a basic promotion, except for the following:

Creating a geo rate promotion

A geo rate promotion is a special, discounted rate that is only offered to customers from a specific region. Geo rate promotions are available to all customers from certain markets, and apply to all room types, rates and dates except those that were specifically excluded. The lower price and special tag on search results might help increase the property's visibility and ultimately earn more bookings.

Sample request

The following request creates a geo rate promotion:

<request>
   <hotel_id>12312</hotel_id>
    <promotion
        type="geo_rate"
        target_channel="india_pos">
        <stay_date>
            <excluded_dates>
                <excluded_date>2024-06-15</excluded_date>
                <excluded_date>2024-06-16</excluded_date>
            </excluded_dates>
        </stay_date>
        <discount value="15" />
    </promotion>
</request>

Request body

Creating a mobile rate promotion

Use the mobile rate promotion to offer a discounted rate to guests who book through the mobile app, and/or through mobile or tablet browsers.

Properties can choose to provide a discount for guests who book through:

• An app. For example, guests booking (only) through the Booking.com mobile app can get this discount.
• A mobile or tablet browser. For example, guests booking through the Booking.com website using their mobile browser can get this discount.

If you create mobile rate promotions without specifying a target_channel, by default, the API selects the app only option.

Sample request

This request creates a mobile rate promotion:

<request>
   <hotel_id>12312</hotel_id>
    <promotion
        type="mobile_rate"
        target_channel="app">
        <stay_date>
            <excluded_dates>
                <excluded_date>2024-06-15</excluded_date>
                <excluded_date>2024-06-16</excluded_date>
            </excluded_dates>
        </stay_date>
        <discount value="15" />
    </promotion>
</request>

Request body

Sample response

See sample response for basic promotion.

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 though they are still active. However, you can update the promotion with future dates to make it bookable again.

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"
    min_stay_through="0"
    non_refundable="0"
    no_cc_promotion="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: [...] -->

Troubleshooting errors and warnings in response

This section covers the most commonly encountered error and warning responses when calling the Promotions API.

Schema validation errors

HTTP/1.1 400 Bad Request

<promotions>
  <fault code="400">
    <string>code= 1824 level= 2 message= Element 'stay_date', attribute 'start': '2024-06-0' is not a valid value of the atomic type 'xs:date'.
    </string>
    <string>code= 1824 level= 2 message= Element 'promotion', attribute 'id': '2wef' is not a valid value of the atomic type 'xs:integer'.
    </string>
  </fault>
</promotions>
<!-- RUID: [...] -->

Invalid ID

HTTP/1.1 403 Forbidden

<promotions>
  <fault code="1009">
    <string>Access denied for hotel '23543'</string>
  </fault>
</promotions>
<!-- RUID: [...] -->

HTTP/1.1 400 Bad Request

<promotions>
  <fault code="400">
    <string>Invalid Room id= 124324</string>
    <string>Invalid Room id= 34645</string>
  </fault>
</promotions>
<!-- RUID: [...] -->

Warnings

Sometimes a promotion is created even when there is invalid data in the input. The invalid data is filtered and sent back as a warning in the response.

<promotions>
    <id>TB222200159622003729</id>
    <warnings>
        <warning>The promotion could not be applied to these dates: 2024-05-03, 2024-05-04. The reason is that these dates are earlier than book_date[@start] (2024-05-05).</warning>
    </warnings>
</promotions>
<!-- RUID: [...] -->