Frequently asked questions about the Promotions API

This page answers some common questions about the Promotions API.

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

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 Support 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.

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.

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

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:

• The status of the rate plan from the error response is inactive. (Check the status with a rates call.)

[TODO: Pretty sure we no longer reject promotions for those reasons]

We only show visual tags for certain promotion types:

• Black Friday Deal
• Early Year Deal
• Getaway Deal
• Late Escape Deal
• Mobile rate

Other types of promotions appear on the website and do display visuals such as strikethrough pricing and discount percentages, but they don't receive a special tag.

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.

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

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.

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.

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

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.

If this happens, check your password. And double check whether you allow special characters.

Alternatively you can use basic authentication. To use this authentication method, you need to provide an authentication header. For more information, see Authentication.