Blog Detail Title

Short Content Here

by Author Name

Date Published


Corporate Rates, Surcharges, and more API Updates

Andrea Stubbe October 25, 2017

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 If you now call the endpoints


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


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": 2, "type": "Absolute", "value": 0},
    {"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": "Percent", "value": 10},
    {"persons": 3, "type": "Percent", "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

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, 2018, as a no-op field - and then remove it.

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


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

Andrea Stubbe

Posted by

Andrea Stubbe
Andrea started coding as a kid, paused that for some years trying to find more interesting things, but then ended up doing that for a living. After working as a freelancer, researcher, teacher, and a normal employee in small and giant corporations, she fulfilled her childhood dream and co-founded a company a year ago. Being a fan of microservices since before she knew that term, she’s still contemplating how and if to use them in micro-sized companies.


by Benjamin Schmid


IBE Integration Guide

Let's talk Internet Booking Engines (IBEs). They work best when directly connected to the PMS, without any intermediaries that might get in the way with delays ...

by Andrea Stubbe


Digital guest journey with apaleo

apaleo is building software for hotels, and our users are people that work at hotels. To create amazing guest experiences we need you, creators of guest facing ...

by Andrea Stubbe


Push it! Webhooks in apaleo

The notification service allows you to build or set up apps which subscribe to certain events on apaleo (webhooks). When an event is triggered, we send an HTTP ...


Subscribe to our a-list for all the fun:

  • Keep up to date with hotel trends
  • Understand what matters most to hotel clients
  • Sweet gifs and special offers

Get it in your inbox every Monday ;)

By entering your email you expressly consent to receive our newsletter every week and other material related to...