Skip to main content

Corporate Rates, Surcharges, and more API Updates

Straight from our laptops to the open hospitality cloud - brand new features and API improvements we built for you last week.

Corporate Rates

Hoteliers want to negotiate and manage special rates for corporations - but others should not see those negotiated rates, or else they might start bargaining and wanting the same deals. To support this use case, we introduced a new field on rate plans, "corporate rate code". Creating a corporate rate plan is simple: just specify a corporateRateCode in the payload. The cool thing is that one corporate code can be used in more than one rate plan. Imagine you set up special rates for Wayne Enterprises, you could all give them the code IAMBATMAN. If you then request offers using this code, the calculations will take all rate plans with this code into account.

To make sure not everyone can see all rate plans and rates, we added a new scope you now call the endpoints
  • GET 
  • GET$count 
  • GET{id} 
  • GET{id}/rates 
  • GET{id}/rates/$count 
we will check if your client has this scope - and then either include the negoiated rate plans and rates, or not.

To see all corporate rate codes, call GET Ironically, this is currently nsfw, 'not safe for work', even though it's a feature to support selling to corporations. Can't get more "for work" than that one - but we wanted to collect some more feedback before declaring this one v1 (read this post on how we deal with versions).

Finally, to get offers for one specific corporate code, simply specify the promoCode in the request. The response will combine all offers for this promo code and all publicly available offers. Think about the case that someone works at a company and wants to book a room on short notice - he might not care whether it's the corporate rate or not, all he wants is a bed to sleep in.

To round out the feature, apaleo now also supports a new guarantee type "company" for rate plans and reservations. It's ranked the same as guaranteed by credit card, but can only be used on corporate rate plans. How else should you know which company is guaranteeing?

While we built this feature with the use case of selling to corporations and businesses in mind, you can use it for all kinds of 'secret' rates. If you think your app would benefit from getting this information, contact us - but remember, with great power comes great responsibility (random fact: this quote might not come from Spider-Man after all, says

Disclaimer: Wayne Enterprises and Batman are the inventions of DC Comics, just like Spider-Man is owned by Marvel Comics. We obviously don't own the rights for those characters / brands, and use those solely as references to modern day culture. While we love them both, we don't want to imply that they love us as well, or that they would recommend using apaleo.


The second addition to defining rates is having different rates, depending on how many people stay in a room. To not require you to set a gazillion of rates, we started with the possibility to specify a fixed surcharge per number of persons. Let's play this through with some examples:

You already defined a unit group fitting one to four persons - for one or two persons, you want to charge the standard rate (let's say it's 100 Euro for day 1, 130 Euro for day 2, and 140 for day 3), but for the third and forth one you want 10 Euro more. To achieve that, define
"surcharges": [ {"persons": 3, "type": "Absolute", "value": 10},
{"persons": 4, "type": "Absolute", "value": 10}

That results in the following rates:
Day 1: 100 Euro for one or two persons, 110 Euro for three or four
Day 2: 130 Euro for one or two persons, 140 Euro for three or four
Day 3: 140 Euro for one or two persons, 150 Euro for three or four

Or, you want to charge 10% more for two persons, and 15% more for three persons, and 5 Euro less for four persons (that one might be useful in campaigns and special offers):
"surcharges": [ {"persons": 2, "type": "Percentage", "value": 10}, {"persons": 3, "type": "Percentage", "value": 15}, {"persons": 4, "type": "Absolute", "value": -5},

As a result, you get:
Day 1: 100 Euro for one person, 110 Euro for two, 115 Euro for three, and 95 Euro for four
Day 2: 130 Euro for one person, 143 Euro for two, 150 Euro for three (note the rounding up to the next highest full number - to prevent odd fractions), and 125 Euro for four

Day 3: 140 Euro for one person, 154 Euro for two, 161 Euro for three, and 135 Euro for four

And what to do when you want the same price, no matter how many people stay in there? Just don't define any surcharges.

When calculating rates and offers, the surcharges will be added automatically, based on the number of persons you specify in the request. No change here.

To make it super clear for what number of persons the base rate (the one without surcharges) is taken, and because it didn't seem to be an awfully helpful feature, we deprecated the possibility to set the minimum number of people in a unit or unit group. From now on, the minimum number will always default to 1. We'll leave it in the API until November 20, as a no-op field - and then remove it. Please stop using it now, and get in touch with if you want to talk about that.

PATCH Reservations and Cancellation Policies

As the better alternative to updating reservations, we introduced a proper patch method, and recommend you use that one, instead of the old PUT, which we will deprecate soon:

The API now also offers the possibility to change cancellation policies after you created them:

VAT Breakdown in Offers

Just like invoices, offers now also include the VAT breakdown. Nice little feature if you want to display the offer overview to your users. Available now on
GET and GET{id}/alternative-offers

... And More

  • we introduced a new scope reservations.assign-unit, which you'll need to assign units. Previously, this could be done using the reservations.manage scope - but that one's super powerful, and hoteliers might be reluctant giving that to too many apps. If you already had the reservations.manage scope, we added the new one to your clients, and no action is required from your side.
  • we now use the booker instead of the guest to prefill the owner of the folio - which is also the person (or company) receiving the invoice in the end. Don't worry, you can still change it later with a simple PATCH. The booker seems to be the more sensible default, and we hope there's less need for patching things later.
  • when creating an account, setting description and location are now optional, and not mandatory anymore. We did that as a preparation for something new, and big, and awesome... but more on that soon!
We hope you like the new features and changes,

Your apaleo team


Popular posts from this blog

Getting Started with apaleo APIs

Have a look You can find all of apaleo's API on We use Swagger to describe it, and to generate our documentation.

Sign up The first step is to sign up for an account. After you finish signup you will be able to login to our apaleo app and start configuring your properties. Also you can use the same credentials to access our API using Swagger. Get access for app We're still new and want to get in touch with you before we grant you access. Contact us at, to get your very own client credentials that lets you play with the API in our sandbox.
Use it apaleo APIs are protected using OAuth2 - the de-facto standard for API security. Here's a short guide to get you started:

Step 1: To get access to our APIs, you need to use your client id and secret to obtain an access token. Don't have one? Contact us at

Combine your client id and secret into a string, separated by colon yourClientId:YourClientSecret and encode with Base64. This wi…

Connect your app with OAuth 2.0

What is this all about? When you connect your app to apaleo, it can read or modify data, or even trigger entire business flows of a hotel. But before gaining access to any of the resources in the REST API, it must get permission from the hotel. This guide will walk you through the authorization process (described in greater detail by the OAuth 2.0 specification). Note: apaleo's OAuth 2.0 implementation supports the standard authorization code grant type. You should implement the application flow described below to obtain an authorization code and then exchange it for a token. (The implicit grant type is not supported.) Terminology Before learning more about the details of the authorization process, make sure that you are familiar with some of the key terms that are used in this guide: Client: Any application that would like access to a hotel's data. A user (usually the hotel's owner or admin) must grant permission before the client can access any data.API: apaleo REST API. T…

Channel Integration Guide

With the channel integration you can subscribe for availability, rates and inventory (ARI), create new bookings and modify existing bookings. 
The BasicsGet your sandbox account and check out this guide to learn how you can connect to the apaleo APIs.
API Client All apaleo APIs are described as swagger documents. That lets you generate API clients directly from the swagger.json files. There is a large community, providing client generators for almost every language. For example, swagger code generator is a good project, which allows generation of API clients for Java, PHP, C#, NodeJS and more. This gets you up to speed very fast and as a bonus you can access API documentation within the auto-generated methods and models. is our – and your – playground to do first steps with the API, up to your final integration. Use it to interactively explore the API or to learn the apaleo concepts by navigating the user interface.

These are the links you need to know