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 rate plans and promotions?

If a room search follows restrictions set by a promotion, the guest sees the room price under the promotion. For restrictions, channel and closed/open dates, the most restrictive condition will be applied.

You can see it as follows: The system always checks first if it can show the promotion room price. If it cannot, it checks if it can show the parent rate plan room price.

For example, you have set a minimum length of stay (MLOS) of 30 for the parent rate plan and 7 for the promotion. If a guest searches for a room for 7 days, it shows the guest the room price under the promotion. Even if it does not follow the MLOS restriction set by the parent rate plan.

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.

Why does the API return 401 – Authorization Required when I create or update promotions?

Sample error response

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

Answer

Sometimes when creating or updating promotions, you might get the following error message: authorization required. This error message appears when you enter an invalid username or password.

We recommend that you check your password, particularly to verify whether you allow special characters.

An alternative approach to access the API is to use basic authentication. To use this authentication method, you need to provide an authentication header. For more information, see Authentication.