Self-assessment tutorial: Promotions API

In this self-assessment tutorial, you will use the Promotions API to:

Create and manage different promotional rates
Create a basic deal, last-minute deal, or early booker deal
Create a campaign deal
Create a deal for a specific audience – public, members and subscribers
Retrieve details from existing promotions

Who is this for?

This section is suitable if you are:

a developer who works for an existing Connectivity Partner who is certified for Rates & Availability API and is preparing to implement Promotions API
a developer who wants to estimate the time needed to implement the Promotions API
a developer who wants to try out some endpoints of Promotions API in a test environment

Before you start

You will need the following to complete the tutorial:

A test property with the appropriate machine account permissions. Contact your support team if needed to enable necessary permissions.
The test property must have built/active rate plans and room types (works best if there is open availability for the test property).

Step 1 – Create a basic deal

Use the following method and URL to create a basic deal:

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

Sample Request body

<request>
   <hotel_id>12312</hotel_id>
    <promotion
        name="Basic deal"
        type="basic"
        target_channel="public"
        non_refundable="0"
        min_stay_through="3">
        <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>

Sample Response body

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

If the promotion is created successfully, the API returns a new promotion ID. Store this ID number! You'll need it to make any edits in the future.

Step 2 – Create a last-minute deal

Use the following method and URL to create a last-minute deal:

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

Sample Request body

<request>
   <hotel_id>12312</hotel_id>
    <promotion
        name="Last-minute deal"
        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>

Sample Response body

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

Step 3 – Create an early booker deal

Use the following method and URL to create an early booker deal:

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

Sample Request body

<request>
   <hotel_id>12312</hotel_id>
    <promotion
        name="Early booker deal"
        type="early_booker"
        target_channel="public"
        non_refundable="0"
        min_stay_through="3">
        <early_booker 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>

Sample Response body

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

Step 4 – Create a campaign deal

Use the following method and URL to create a campaign deal, in this example a Getaway Deal:

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

Sample Request body

<request>
   <hotel_id>12312</hotel_id>
    <promotion
        name="Getaway Deal"
        type="getaway_campaign">
        <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="30" />
    </promotion>
</request>

Sample Response body

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

Step 5 – Updating an existing promotion

Send the request with the following method and URL to update an existing promotion:

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

Sample Request body

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

Sample Response body

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

Step 6 – Retrieve promotion details

This endpoint is used to retrieve statistics from the promotion such as total revenue, number of bookings or cancellations, and number of nights reserved.

Send the request with the following method and URL to retrieve promotion details:

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

Sample Request Body

<request>
    <hotel_id>1234</hotel_id>
    <id>TB1234596220037</id>
    <active>1</active>
    <name>Basic deal</name>
</request>

Sample Response body (this includes all possible information that can be included)

<promotions>
  <promotion id="TB1234596220037" name="Summer Deal" type="basic" target_channel="public" min_stay_through="2" non_refundable="-1" 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="Last-minute deal ≤8hours" 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: [...] -->

Step 7 - Deactivate a promotion

Use the following method and URL to deactivate a currently active promotion.

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

Sample Response body

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