Last updated

Managing promotions

Business booker rates has been sunset

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

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

Use the promotions endpoint to:

Active promotions with book/stay dates in the past

Promotions with stay dates in the past are active, but no longer bookable. However, you can update the promotion with future dates to make it bookable again.

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.

All newly created or updated promotions are marked as active

A promotion is marked active whenever it is created or updated irrespective of whether the bookable/stay dates are current or in the past.

Creating a basic promotion

China channel has been sunset

Booking.com has sunset the China channel for promotions on December 7, 2022. It is therefore no longer available or usable.

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

ElementAttributeDescriptionTypeOccurrencesNotes
requestRoot elementobject1..1-
hotel_idThe ID of the property to which the promotion applies.integer1..1You must have permission to edit the property.
promotion-object1..1-
promotionnameThe name of the promotion. This name is only for you: it does not appear on Booking.com.string1..1Must be 20 characters or less. This includes spaces.
promotiontypeThe type of promotion.string1..1Accepts: basic, last_minute, early_booker.
promotiontarget_channelDetermines who can see the promotion.string0..1Accepts: public, subscribers. Default: public
promotionmin_stay_throughThe minimum number of nights a guest must stay to be eligible for the promotion.integer0..1Possible values are 0-7. Be aware that 0 means that the promotion follows the minimum length of stay (MLOS) of the chosen parent rate plan. 1 means that there is no MLOS required for this promotion. 2-7 refers to the actual minimum number of days for MLOS.
promotionnon_refundableSpecifies if the promotion is non-refundable.boolean0..1Accepts: 1 (non-refundable), 0 (refundable). Default: 0
book_dateSpecifies the date range during which the promotion appears on Booking.com.-0..1If you specify neither book_date[@start] nor book_date[@end], then the promotion has no date restrictions.
book_datestartSpecifies the date from which the promotion is available.date (YYYY-MM-DD)0..1Default: empty. book_date[@start] must be before book_date[@end]. You should provide also book_date[@end]
book_dateendSpecifies the date up to which the promotion is available.date (YYYY-MM-DD)0..1book_date[@end] must be after book_date[@start]. book_date[@end] must be on or before stay_date[@end]. You should provide also book_date[@start]
book_timeSpecifies the time window during which the promotion appears on Booking.com.object0..1If you specify neither book_time[@start] nor book_time[@end], then the promotion has no time restrictions.
book_timestartSpecifies the hour from which the promotion appears on Booking.com, in 24-hour time, in the property's timezone.integer0..1Accepts: 024.
book_timeendDefines the hour after which the promotion no longer appears on Booking.com, in 24-hour time, in the property's timezone.integer0..1Accepts: 024.
stay_dateSpecifies the date range in which the stay must take place in order for the promotion to apply.object1..1-
stay_datestartDefines the start of the stay days which the promotion will be applied ondate (YYYY-MM-DD)1..1Must be less than or equal to stay_date[@end].
stay_dateendDefines the end of the stay days which the promotion will be applied untildate (YYYY-MM-DD)1..1Must be greater than or equal to stay_date[@start].
active_weekdaysSpecifies the days of the week on which the promotion applies.object0..1If you provide no active_weekday children, then the promotion applies to all days.
active_weekdaySpecifies a day of the week on which the promotion applies.string0..7Accepts: Sat, Sun, Mon, Tue, Wed, Thu, Fri.
excluded_datesSpecifies the date range (within the stay_date range) to which the promotion does not apply.object0..1Number of days in the date range should not exceed 30 days.
excluded_datesstartSpecifies the first date of the date range (within the stay_date range) to which the promotion does not apply.date (YYYY-MM-DD)0..1If you include this attribute, you must also include excluded_dates[@end].
excluded_datesendSpecifies the last date of the date range (within the stay_date range) to which the promotion does not apply.date (YYYY-MM-DD)0..1If you include this attribute, you must also include excluded_dates[@start].
excluded_dateSpecifies an individual date (within the stay_date range) on which the promotion does not apply.date (YYYY-MM-DD)0..*-
additional_datesSpecifies the date range (outside the stay_date range) to which the promotion applies.object0..1Number of days in the date range should not exceed 30 days.
additional_datesstartSpecifies the first date of the date range (outside the stay_date range) on which the promotion applies.date (YYYY-MM-DD)0..1If you include this attribute, you must also include additional_dates[@end].
additional_datesendSpecifies the last date of the date range (outside the stay_date range) on which the promotion applies.date (YYYY-MM-DD)0..1If you include this attribute, you must also include additional_dates[@start].
additional_dateSpecifies an individual date outside the stay_date range on which the promotion applies.date (YYYY-MM-DD)0..*-
rooms-object1..1-
room-object1..*-
roomidSpecifies a room to which the promotion applies.integer1..1The rooms must belong to the property you specified in hotel_id.
parent_rates-array of parent_rate1..1Important: See the note about parent_rates.
parent_rate-object1..*-
parent_rateidSpecifies the rate to which the promotion must be applied.integer1..1The rate must be active, and must belong to the property in hotel_id. Important: See the note about parent_rates.
discount-object1..1-
discountvalueThe percentage that will be deducted from the room price.integer1..1Accepts: 199.

Target promotions to specific audience

China channel has been sunset

Booking.com has sunset the China channel for promotions on December 7, 2022. It is therefore no longer available or usable.

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:

TypeValueDescription
One of the following:
basic, last_minute, early_booker
publicAll guests can see the promotion.
One of the following:
basic, last_minute, early_booker
subscribersOnly guests who subscribed to the Booking.com newsletter can see the promotion.

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:

Product AProduct B
Room IDs00
1
Rate IDs1011
12

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

ElementAttributeDescriptionTypeNotes
idThe updated promotion ID.stringDuring subsequent updates the id keeps changing.

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:

ElementAttributeDescriptionTypeOccurrencesNotes
promotiontypeThe type of promotion.string1..1Should be last_minute.
last_minuteSpecifies the unit and value of time before guests check-in during which the promotion applies.object1..1See the example below.
last_minuteunitThe unit of time specified in days or hours.string1..1Accepts: hour, day. To create promotions that are available only at the very last hour, use the hour value.
last_minutevalueThe amount of time (in days or hours) before guests check-in during which the promotion applies.integer1..1Specify: 1 and higher.
If the value is set to 0, irrespective of the value set in unit, the API creates a last minimum promotion effective 3 days and fewer.
book_date-object0..0This field is not relevant to this promotion type.

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

ElementAttributeDescriptionTypeNotes
idThe promotion ID.stringWhen you create a promotion for the first time, the API generates a promotion id. During subsequent updates the id keeps changing.

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:

ElementAttributeDescriptionTypeOccurrencesNotes
promotiontypeType of the promotion.string1..1Should be early_booker.
early_booker-object1..1-
early_bookervalueThe number of days guests must book in advance to get the discount from this promotion.integer1..1-
book_date-object0..0This field is not relevant to this promotion type.
Promotion cannot start in the past.

The early_booker[@value] number counts backwards, in days, from the stay_date start. Ensure the number you specify is not larger than the difference between stay_date start and the day you created the promotion.
For example, creating an early booker promotion for stay_date start="2021-06-01" on 2021-05-17 with early_booker value="20" returns an error, because counting backwards from stay_date start with that number of days passes the creation date.

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

ElementAttributeDescriptionTypeOccurrencesNotes
promotiontypeType of the promotion.string1..1Should be geo_rate.
promotiontarget_channelDetermines who can see the promotion.string0..1To get a list of target_channel values, use the /xml/getpromotionchannels endpoint. Not all properties are eligible to use all target channels.
discount-object1..1-
discountvalueThe percentage that will be deducted from the room price.integer1..1Accepts: 530.
excluded_datesSpecifies the date range to which the promotion does not apply.object0..1Number of days in the date range should not exceed 30 days.
excluded_datesstartSpecifies the first date of the date range to which the promotion does not apply.date (YYYY-MM-DD)0..1If you include this attribute, you must also include excluded_dates[@end].
excluded_datesendSpecifies the last date of the date range to which the promotion does not apply.date (YYYY-MM-DD)0..1If you include this attribute, you must also include excluded_dates[@start].
excluded_dateSpecifies an individual date on which the promotion does not apply.date (YYYY-MM-DD)0..*-

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

ElementAttributeDescriptionTypeOccurrencesNotes
promotiontypeType of the promotion.string1..1You must specify mobile_rate here.
promotiontarget_channelDetermines the platform from which the user can see the promotion.string0..1Accepts: app, all.
'all' means app + mobile + tablet browser. For example, all includes guests who book through the Booking.com website using their mobile browser.
discount-object1..1-
discountvalueThe percentage that will be deducted from the room price.integer1..1Accepts: 1080. This means that you cannot send discounts less than 10% and more than 80%.
excluded_datesSpecifies the date range to which the promotion does not apply.object0..1Number of days in the date range should not exceed 30 days.
excluded_datesstartSpecifies the first date of the date range to which the promotion does not apply.date (YYYY-MM-DD)0..1If you include this attribute, you must also include excluded_dates[@end].
excluded_datesendSpecifies the last date of the date range to which the promotion does not apply.date (YYYY-MM-DD)0..1If you include this attribute, you must also include excluded_dates[@start].
excluded_dateSpecifies an individual date on which the promotion does not apply.date (YYYY-MM-DD)0..*-

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.

Every update returns the same promotion ID

Every successful promotion update returns the same promotion ID. You can use the same id in the subsequent calls.

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.

All newly created or updated promotions are marked as active

Whenever you create or update a promotion, by default, the API marks the promotion as active irrespective of whether the bookable/stay dates are current or in the past. To make a promotion unavailable for guest's use, make sure to deactivate the 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

The sample response returns the id generated during the promotion creation or the latest update.

<promotions>
    <id>TB210459622003754585</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.

After a successful promotion update, the promotion is marked as active

Irrespective of the promotion's active status, after a successful update, the API marks the promotion as active by default.

Query parameters

ElementDescriptionTypeRequired/OptionalNotes
idSpecify the promotion ID to deactivate.stringrequiredTo get a list of promotions along with their IDs, see Retrieve details about existing promotions.
hotel_idSpecify the ID of the property to which the promotion applies.stringrequiredYou must have permission to edit the property.

Sample response

The sample response returns the id generated during the promotion creation.

<promotions>
    <id>TB259622003710454585</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: [...] -->