Frequently asked questions about the Promotions API

This page answers some common questions about the Promotions API.

Why does the API return 403 – Forbidden?

Sample error response

<?xml version='1.0' standalone='yes'?>
<promotions>
    <fault code="403"
         string="Forbidden" />
</promotions>

Answer

If the API returns the above for every promotions or getpromotions call, your machine account may lack the necessary permissions. Follow these steps:

  1. Send an email to connectivity@booking.com in which you explain your issue and give the names of the affected machine accounts.
  2. Wait for us to confirm (via email) that we have enabled the correct permissions on your accounts.
  3. Retry the request that resulted in a 403 response before.

When two promotions overlap, do guests get a discount from both?

No. If multiple promotions apply during a given time period, we only show the promotion with the highest discount percentage to guests. Any guests who book get the discount from the "cheapest" promotion only.

Why does the API return 400 - Invalid Rate id when I create a promotion?

Sample error response

<?xml version='1.0' standalone='yes'?>
<promotions>
  <fault code="400">
    <string>Invalid Rate id= 9711390</string>
  </fault>
</promotions>

Answer

If the API returns code 400 when you try to create a promotion, even though your request contains a valid room type and rate plan, check that the following is true:

  • Every rate plan in the request is linked to at least one room type in the request via an existing product.
  • The status of the rate plan from the error response is active. (Check the status with a rates call.)

Why don't I see tags for all promotions on the Booking.com website/app?

We only show visual tags for Last minute promotions. Other types of promotions (Basic, Early booker) appear on the website, but not with a special tag.

How does the API handle conflicting restrictions between parent rates and promotions?

Here are examples to illustrate the above:

  1. If the parent rate has a minimum length of stay (LOS) of 3, and the promotion has a minimum LOS of 5, then the LOS of 5 applies.
  2. If the parent rate has a release time of 1 day, and no release time is specified on the promotion, the promotion inherits the release time of the parent rate.
  3. If the parent rate has a closed date, the promotion inherits that closed date.
  4. If the promotion is active and the parent rate is open, the promotion is open for that date.

Why does the API return 401 when I create a Secret Deal?

Sample error response

<?xml version='1.0' standalone='yes'?>
<promotions>
    <fault code="401"
    string="Authorization Required" />
</promotions>

Answer

To receive the additional benefits of a Secret Deal, properties need to configure a minimum discount of 10%. Check that the value of discount[@value] is at least 10.

How does creating promotions with multiple rates and rooms work?

When you pass multiple rates and rooms in a promotions request, the API will create promotions for all valid combinations of rates and rooms. "Valid" in this context means: any combination of room and rate for which a product exists.

For example, the following request can result in the creation of 4 new promotions:

<rooms>
  <room id="1423432"/>
  <room id="325436"/>
</rooms>
<parent_rates>
  <parent_rate id="756878"/>
  <parent_rate id="543754"/>
</parent_rates>

The number of resulting promotions depends on the number of valid combinations. The maximum is 4, because 2 rooms x 2 rates = 4 promotions.