Last updated

Self-assessment tutorial: Promotions API

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

  • Create and manage different promotion rates
  • Create Basic, Last Minute, or Early Booker rates
  • Create rates that target a certain audience – public, subscribers
  • Retrieve details from existing promotion rates

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 on 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 Promotion

Send the request with the following method and URL to create a basic promotion:

POST https://supply-xml.booking.com/hotels/xml/promotions
Sample Request body
<request>
   <hotel_id>12312</hotel_id>
    <promotion
        name="Basic Promotion"
        type="basic"
        target_channel="public"
        min_stay_through="3"
        non_refundable="0"
        no_cc_promotion="1">
        <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 need to use the new promotion ID subsequently on future edits or modifications to the promotion.

Step 2 – Create Last Minute Promo

Send the request with the following method and URL to create a last minute promotion:

POST https://supply-xml.booking.com/hotels/xml/promotions
Sample Request body
<request>
   <hotel_id>12312</hotel_id>
    <promotion
        name="Late 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>
Sample Response body
<promotions>
    <id>TB210380285962200370</id>
</promotions>
<!-- RUID: [...] -->

Step 3 – Create Early Booker Promotion

Send the request with the following method and URL to create an early booker promotion:

POST https://supply-xml.booking.com/hotels/xml/promotions
Sample Request body
<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="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 – Update a 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 5 – Retrieve Promotion Details

This endpoint is used to retrieve promotion statistics like total revenue, number of bookings/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 Promo</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="Lastminute hurry" 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 6 - Deactivate a Promotion

Use the following method and URL to deactivate a promotion.

DELETE https://supply xml.booking.com/hotels/xml/promotions?id={promotionID}&hotel_id={hotelID}
Sample Response body
<promotions>
    <id>TB210380259622003723</id>
</promotions>
<!-- RUID: [...] -->
Previous page
Next page