Create/update a promotion – promotions (B.XML)

Use this endpoint to create, activate, update, or deactivate a promotion for a property.

URL

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

Promotion types

You can see all promotion types in Extranet. The API currently supports these promotion types:

  • Basic
  • Last minute
  • Early booker
  • Business booker (beta)
  • Geo rate (beta)

You can also choose whether a promotion is available to all guests, or only certain guests.

Basic promotion

This is an easy and fully customisable promotion, which will give the guest a discount on selected rooms and rates.

Sample request

This request creates a basic promotion:

<request>
   <hotel_id>12312</hotel_id>
    <promotion
        name="Dummy Promotion"
        type="basic"
        target_channel="public"
        min_stay_through="3"
        non_refundable="0"
        no_cc_promotion="1">
        <book_date start="2017-05-14" end="2017-07-31" />
        <book_time start="11" end="13" />
        <stay_date start="2017-06-06" end="2017-06-29">
            <active_weekdays>
               <active_weekday>Thu</active_weekday>
           </active_weekdays>
            <excluded_dates>
                <excluded_date>2017-06-15</excluded_date>
                <excluded_date>2017-06-16</excluded_date>
            </excluded_dates>
        </stay_date>
        <additional_dates>
            <additional_date>2017-07-18</additional_date>
            <additional_date>2017-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

Field Description Type Occurrences Notes
request Root element object 1..1 -
hotel_id The ID of the property to which the promotion applies. integer 1..1 You must have permission to edit the property.
promotion - object 1..1 -
promotion[@name] The name of the promotion. This name is only for you: it does not appear on Booking.com. string 1..1 Must be 20 characters or less.
promotion[@type] The type of promotion. string 1..1 Accepts: basic, last_minute, early_booker.
promotion[@target_channel] Determines who can see the promotion. string 0..1 Accepts: public, subscribers , china. Default: public
promotion[@min_stay_through] The minimum number of nights a guest must stay to be eligible for the promotion. integer 0..1 Any number between 0-7. Default: empty (all stay lengths are eligible)
promotion[@non_refundable] Specifies if the promotion is non-refundable. boolean 0..1 Accepts: 1 (non-refundable), 0 (refundable). Default: 0
promotion[@no_cc_promotion] Specifies if guests can book this promotion without a credit card. boolean 0..1 Accepts: 1 (no credit card required), 0 (credit card required). Default: 0.
book_date Specifies the date range during which the promotion appears on Booking.com. - 0..1 If you specify neither book_date[@start] nor book_date[@end], then the promotion has no date restrictions.
book_date[@start] Specifies the date from which the promotion is available. date (YYYY-MM-DD) 0..1 Default: empty. book_date[@start] must be before book_date[@end]. You should provide also book_date[@end]
book_date[@end] Specifies the date up to which the promotion is available. date (YYYY-MM-DD) 0..1 book_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_time Specifies the time window during which the promotion appears on Booking.com. object 0..1 If you specify neither book_time[@start] nor book_time[@end], then the promotion has no time restrictions.
book_time[@start] Specifies the hour from which the promotion appears on Booking.com, in 24-hour time, in the property's timezone. integer 0..1 Accepts: 024. book_time[@start] must be on or before book_time[@end].
book_time[@end] Defines the hour after which the promotion no longer appears on Booking.com, in 24-hour time, in the property's timezone. integer 0..1 Accepts: 024. book_time[@end] must be after or on book_time[@start].
stay_date Specifies the date range in which the stay must take place in order for the promotion to apply. object 1..1 -
stay_date[@start] Defines the start of the stay days which the promotion will be applied on date (YYYY-MM-DD) 1..1 Must be less than or equal to stay_date[@end].
stay_date[@end] Defines the end of the stay days which the promotion will be applied until date (YYYY-MM-DD) 1..1 Must be greater than or equal to stay_date[@start].
active_weekdays Specifies the days of the week on which the promotion applies. object 0..1 If you provide no active_weekday children, then the promotion applies to all days.
active_weekday Specifies a day of the week on which the promotion applies. string 0..7 Accepts: Sat, Sun, Mon, Tue, Wed, Thu, Fri.
excluded_dates Specifies the date range (within the stay_date range) to which the promotion does not apply. object 0..1 Number of days in the date range should not exceed 30 days.
excluded_dates[@start] Specifies the first date of the date range (within the stay_date range) to which the promotion does not apply. date (YYYY-MM-DD) 0..1 If you include this attribute, you must also include excluded_dates[@end].
excluded_dates[@end] Specifies the last date of the date range (within the stay_date range) to which the promotion does not apply. date (YYYY-MM-DD) 0..1 If you include this attribute, you must also include excluded_dates[@start].
excluded_date Specifies an individual date (within the stay_date range) on which the promotion does not apply. date (YYYY-MM-DD) 0..* -
additional_dates Specifies the date range (outside the stay_date range) to which the promotion applies. object 0..1 Number of days in the date range should not exceed 30 days.
additional_dates[@start] Specifies the first date of the date range (outside the stay_date range) on which the promotion applies. date (YYYY-MM-DD) 0..1 If you include this attribute, you must also include additional_dates[@end].
additional_dates[@end] Specifies the last date of the date range (outside the stay_date range) on which the promotion applies. date (YYYY-MM-DD) 0..1 If you include this attribute, you must also include additional_dates[@start].
additional_date Specifies an individual date outside the stay_date range on which the promotion applies. date (YYYY-MM-DD) 0..* -
rooms - object 1..1 -
room - object 1..* -
room[@id] Specifies a room to which the promotion applies. integer 1..1 The rooms must belong to the property you specified in hotel_id.
parent_rates - array of parent_rate 1..1 Important: See note about parent_rates, below.
parent_rate - object 1..* -
parent_rate[@id] Specifies the rate to which the promotion must be applied. integer 1..1 The rate must be active, and must belong to the property in hotel_id. Important: See note about parent_rates, below.
discount - object 1..1 -
discount[@value] The percentage that will be deducted from the room price. integer 1..1 Accepts: 0100.

promotion[@target_channel]

This attribute determines who can see the promotion. You can target your promotion to a certain set of guests.

Value Description
public All guests can see the promotion.
subscribers Only guests who subscribed to the Booking.com newsletter can see the promotion.
china Only guests from China.

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 products. It will not create new products 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 A Product B
Room IDs 0 0
1
Rate IDs 10 11
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>VR210380280</id></promotions>
<!-- RUID: [...] -->

If your request is successful, the API returns the ID of the newly created promotion. Store this ID! You need it to perform future operations on the promotion.

Last minute promotion

Sell leftover rooms, max out your occupancy, increase your visibilty on mobile devices, and attract last-minute bookers.

Sample request

This request creates a Last minute promotion:

<request>
   <hotel_id>12312</hotel_id>
    <promotion
        name="Dummy 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="2017-06-06" end="2017-06-29">
            <active_weekdays>
               <active_weekday>Thu</active_weekday>
           </active_weekdays>
            <excluded_dates>
                <excluded_date>2017-06-15</excluded_date>
                <excluded_date>2017-06-16</excluded_date>
            </excluded_dates>
        </stay_date>
        <additional_dates>
            <additional_date>2017-07-18</additional_date>
            <additional_date>2017-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 a Last minute promotion are the same as for a Basic promotion, except for the following:

Field Description Type Occurrences Notes
promotion[@type] The type of promotion. string 1..1 Should be last_minute.
last_minute Specifies how much time before the check-in date the promotion applies. object 1..1 See example, below.
last_minute[@unit] The unit of time for last_minute[@value]. string 1..1 Accepts: hour, day.
last_minute[@value] The amount of time before the check-in date during which the promotion applies. integer 1..1 Accepts: 0 and higher.
book_date - object 0..0 This field is not relevant to this promotion type.

last_minute example

For a Last minute promotion that gives guests a discount if they book 2 days or less before their intended check-in date, use these values:

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

Sample response

See sample response for Basic promotion.

Early booker promotion

Get a head start, attract eager bookers and fill your low-season rooms early.

Sample request

This request creates an Early booker promotion:

<request>
   <hotel_id>12312</hotel_id>
    <promotion
        name="Dummy Promotion"
        type="early_booker"
        target_channel="public"
        min_stay_through="3"
        non_refundable="0"
        no_cc_promotion="1">
        <early_booker value="5" />
        <book_time start="11" end="13" />
        <stay_date start="2017-06-06" end="2017-06-29">
            <active_weekdays>
               <active_weekday>Thu</active_weekday>
           </active_weekdays>
            <excluded_dates>
                <excluded_date>2017-06-15</excluded_date>
                <excluded_date>2017-06-16</excluded_date>
            </excluded_dates>
        </stay_date>
        <additional_dates>
            <additional_date>2017-07-18</additional_date>
            <additional_date>2017-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:

Field Description Type Occurrences Notes
promotion[@type] Type of the promotion. string 1..1 Should be early_booker.
early_booker - object 1..1 -
early_booker[@value] The number of days guests must book in advance to get the discount from this promotion. integer 1..1 -
book_date - object 0..0 This field is not relevant to this promotion type.

Business Booker promotion

Closed beta

This API is in closed beta. You can't use it unless you have been invited as a beta tester. You can sign up to be a beta tester using this form

1 in 5 bookings are business related. The discount will only be displayed to verified, logged-in business travelers, and will apply to all your room types, rates and dates except excluded. The lower price and special tag on search results might help increase your visibility and ultimately earn more bookings.

Sample request

This request creates an business booker promotion:

<request>
   <hotel_id>12312</hotel_id>
    <promotion
        type="business_booker">
        <stay_date>
            <excluded_dates>
                <excluded_date>2017-06-15</excluded_date>
                <excluded_date>2017-06-16</excluded_date>
            </excluded_dates>
        </stay_date>
        <discount value="15" />
    </promotion>
</request>

Request body

Field Description Type Occurrences Notes
promotion[@type] Type of the promotion. string 1..1 Should be business_booker.
discount - object 1..1 -
discount[@value] The percentage that will be deducted from the room price. integer 1..1 Accepts: 5100.
excluded_dates Specifies the date range to which the promotion does not apply. object 0..1 Number of days in the date range should not exceed 30 days.
excluded_dates[@start] Specifies the first date of the date range to which the promotion does not apply. date (YYYY-MM-DD) 0..1 If you include this attribute, you must also include excluded_dates[@end].
excluded_dates[@end] Specifies the last date of the date range to which the promotion does not apply. date (YYYY-MM-DD) 0..1 If you include this attribute, you must also include excluded_dates[@start].
excluded_date Specifies an individual date on which the promotion does not apply. date (YYYY-MM-DD) 0..* -

Geo Rate promotion

Closed beta

This API is in closed beta. You can't use it unless you have been invited as a beta tester. You can sign up to be a beta tester using this form

A Public Geo Rate is a special, discounted rate that is only offered to customers from a specific region. Public Geo Rates are available for all customers from a certain markets, and will apply to all your room types, rates and dates except excluded. The lower price and special tag on search results might help increase your visibility and ultimately earn more bookings.

Sample request

This request creates an geo rate promotion:

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

Request body

Field Description Type Occurrences Notes
promotion[@type] Type of the promotion. string 1..1 Should be geo_rate.
promotion[@target_channel] Determines who can see the promotion. string 0..1 Accepts: algeria_pos, argentina_pos , australia_pos, algeria_pos, belarus_pos , brazil_pos, canada_pos, chile_pos , colombia_pos, domestic_pos, eu_pos , hong_kong_pos, india_pos, indonesia_pos , international_pos, iran_pos, israel_pos , japan_pos, kazakhstan_pos, kuwait_pos , malaysia_pos, mexico_pos, argentina_pos , new_zealand_pos, oman_pos, pakistan_pos , peru_pos, philippines_pos, qatar_pos , russia_pos, saudi_arabia_pos, singapore_pos , south_africa_pos, south_korea_pos, switzerland_pos , taiwan_pos, thailand_pos, trinidad_&_tobago_pos , turkey_pos, ukraine_pos, united_arab_emirates_pos , united_states_pos, vietnam_pos. Not all hotels are eligible for all target channels
discount - object 1..1 -
discount[@value] The percentage that will be deducted from the room price. integer 1..1 Accepts: 5100.
excluded_dates Specifies the date range to which the promotion does not apply. object 0..1 Number of days in the date range should not exceed 30 days.
excluded_dates[@start] Specifies the first date of the date range to which the promotion does not apply. date (YYYY-MM-DD) 0..1 If you include this attribute, you must also include excluded_dates[@end].
excluded_dates[@end] Specifies the last date of the date range to which the promotion does not apply. date (YYYY-MM-DD) 0..1 If you include this attribute, you must also include excluded_dates[@start].
excluded_date Specifies an individual date on which the promotion does not apply. date (YYYY-MM-DD) 0..* -

Sample response

See sample response for Basic promotion.

Activate a promotion

Sample request

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

Sample response

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

Update a promotion

You can update a promotion by including the promotion[@id] field in the request body and sending only the fields that need to be updated.

Note

After each update, you receive a new promotion ID. The new ID replaces the old ID, after which the old one no longer exists.

Sample request

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

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

Sample response

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

Note

After each update, you receive a new promotion ID. The new ID replaces the old ID, after which the old one no longer exists.

Sample request

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>

Deactivate a promotion

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

URL

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

Sample response

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

Errors

Schema validation errors

HTTP/1.1 400 Bad Request

<promotions>
  <fault code="400">
    <string>code= 1824 level= 2 message= Element 'stay_date', attribute 'start': '2017-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 promotion is created even when there are some invalid data in the input. The invalid data is filtered and sent back as warning in the response.

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