Book a demo


Blog Detail Title

Short Content Here

by Author Name

Date Published


Channel Integration Guide

Andrea Stubbe May 24, 2018

apaleo's distribution API lets you subscribe for updates on availability, rates and inventory (ARI), create new bookings and modify existing bookings. We built this to make channel manager integrations easy, but it turned out to be neat for reporting applications or revenue management, too.

Before you start, we recommend to check out the end user guide for rate plans.

The basics

Get your test account and check out this guide to learn how you can connect to the apaleo APIs.

You can find the swagger documentation on

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.

Setup and configuration

Once a hotel successfully connected apaleo the rate plans from apaleo need to be mapped to the ones on your side. We do not store an external rate plan ID, so all the mapping is on your side. One way to simplify this mapping, is to load all rate plans from apaleo, and then make those available when creating or mapping to existing rate plans. That way nobody has to copy-paste any IDs between systems. Neat, right?

You should only load rate plans from apaleo that are mapped to the channel you are using (ChannelManager, BookingCom, Expedia, etc.). Note that we do not support day use rate plan in the distribution APIs.

A rate plan in apaleo is always bound to exactly one unit group (= room category). Each rate plan has a unique ID. When you receive ARI data or when you create a reservation you have to use this unique apaleo rate plan ID. This requires you to map the combination of a rate code and a room code on your side to this ID. See the following example for a simple hotel with 2 room categories and 2 rate codes:

If hotels are very careful with the definition of the rate codes it can seem as if the rate plan IDs have a meaning. Don't rely on it and start to parse them. They are really just IDs. Yes, they are constructed out of the property ID and the rate plan code, but the rate plan code is chosen by humans, and does not necessarily have a meaning or is consistent throughout all rates and all properties.

Once this is done, you can subscribe to availability, rates and inventory (ARI) updates for those rate plans.

POST /v1/subscriptions/

Check the documentation in Swagger for the full model, and an example of what to pass. The key field is the endpoint URL. This is the URL we call to deliver the ARI data. Make sure you protect this endpoint well, as an unprotected endpoint would allow everyone to set prices or availabilities for the hotels. Sounds like trouble. We require https with a valid certificate and some sort of token. The URL also needs to be reachable from If you're not sure, check with your security or ops team, if any firewalls prevent incoming traffic on (usually) port 443. If so ask to whitelist us.

Our outbound IP addresses are:


As a result, you'll get an ID back. Be sure to store this, as you'll need it later on for updating or deleting the subscription. The main reason to update is after a new rate plan is added, and needs to be synchronised.

PUT /v1/subscriptions/

Subscriptions are tied to an API client, so that other applications used by the same apaleo account cannot accidentally interfere with your subscriptions. Again, trouble.

Getting ARI data

Full Push

After you created and enabled the subscription, apaleo will push a full update of all the ARI data to the configured endpoint URL. To make sure there are no discrepancies, apaleo will do the full push once a day.

It is important that you immediately acknowledge the ARI push and return successful response. Don't try to process ARI data before you acknowledge, this can lead to time outs.

This is how an example entry looks like:

"accountId": "XYZX",
"propertyId": "MUC",
"timeSlices": [ {
"from": "2018-11-17T09:00:00+02:00",
"to": "2018-11-18T08:00:00+02:00",
"ratePlanId": "MUC-NONREF_DBL",
"unitGroupId": "MUC-DBL",
"available": 23,
"prices": [
"adults": 1,
"price": {
"grossAmount": 123,
"beforeTax": 114.95,
"afterTax": 129.84,
"taxes": {
"vat": 8.05,
"cityTax": 6.84
"currency": "EUR"
"adults": 2,
"price": {
"grossAmount": 170,
"beforeTax": 158.88,
"afterTax": 179.45,
"taxes": {
"vat": 11.12,
"cityTax": 9.45
"currency": "EUR"
"restrictions": {
"minAdvanceBookingPeriod": "P1M",
"maxAdvanceBookingPeriod": "P1M14DT12H",
"closed": true,
"closedOnArrival": false,
"closedOnDeparture": false,
"minLengthOfStay": 2,
"maxLengthOfStay": 8
Fields Mandatory Description
accountId and propertyId yes The account ID identifies an apaleo customer. The propertyId is only unique within one apaleo account. The combination of accountId and propertyId is globally unique.
timeSlices yes List of time periods for one rate plan and unit group combination with availability, prices and restrictions. You will at least receive one time slice always.
from and to yes For standard overnight hotel business this defines the time range for the night. In the example above, it would be the night from November 17th to November 18th. Most channels consider this the night of November 17th.
ratePlanId yes The ID of the rate plan in apaleo, which is unique per account.
unitGroupId yes The ID of the unit group in apaleo, which is unique per account. The equivalent for the apaleo unit group in channels can be room type, room category or inventory type.
available yes Number of units available for the unit group during this night. apaleo has shared inventory, so all rate plans selling this unit group on that night will have the same number.
prices no

List of prices including all service fees for breakfast etc. You will receive one price for each allowed occupancy. apaleo currently does not push special prices for children. The prices field will not be set, if:

  • no rate is set for this night
  • the rate is closed
  • the rate plan is not bookable because of its booking period restrictions
  • the rate plan is not available on the requested channel (typically, ChannelManager)

We send the price in different variants. It is up to you to pick the values that you want to process, show to bookers or forward to distribution channels.

  • grossAmount: Net price plus VAT, but excluding any other fees or taxes
  • beforeTax: Net price. No VAT, no other taxes
  • afterTax: Net price plus VAT plus city tax.

Find the details about taxes in taxes. VAT contains all of the VAT, for rooms, extra services and other fees and taxes. That means the VAT percent applied can be a mix of different VATs (for example 7% on the room price and 19% on breakfast).

Read the city tax guide for more information.

restrictions yes Restrictions set for this night. The 'length of stay' restrictions are arrival-based and they are optional. The closed restrictions will always be send. If no rate is set for this night in apaleo the 'master closed' restriction will be set.

Delta Push

apaleo also keeps track of the data already sent to you for a subscription, calculates the diff and sends the data which changed since the last successful update. You will receive delta push as soon as the data was changed (minor delays are possible).

To know if an update was successful, we rely on you: Acknowledge successful receptions with a 2xx status code. If you don't, things will get messy, as your truth and our truth will diverge. There's always the full sync to recover from chaos, but better try avoiding it. You can also request a full push, whenever you need it.

PUT /v1/subscriptions/{id}/trigger-full-sync

The delta is calculated for the following fields:

Field Description
available Only if the number of available units for this night changed it will be send.
prices If one out of the prices changed you will again receive the whole list of prices.
restrictions If one of the restrictions changed you will receive the whole set of current restrictions. If a rate in apaleo was removed and a certain night was made unsellable, you will not receive prices, but the master closed restriction.

Send Bookings

To create a new booking in apaleo all you need to do is send the the details you have to the Distribution API.

POST /v1/bookings

Each booking will be accepted and confirmed by apaleo. If we cannot process the booking, we will show the failed booking to the hotelier on the user interface and allow the hotelier to resolve the problems. You do not need to worry about errors on our side as long as you ensure the format and URL of your request is correct.

It is important that you specify correct prices for each stay date. By default the total amount should include accommodation, VAT and all included/additional services (e.g. breakfast, cleaning fee, etc.). Depending on pricing type (BeforeTaxesWithVat, BeforeTaxes or AfterTaxes) the total amount may or may not include VAT or taxes (e.g. city tax).

Booking vs. Reservation

In apaleo, the booking is a container for one or more reservations. One reservation is for one room, making a booking basically a 'multi room reservation'. Other systems call those differently: for example sends multiple rooms as 'room stay elements' in one reservation. You could combine all of them in one booking to apaleo.

Payment Information

apaleo is certified to be compliant with the PCI-DSS standard and we assume you are as well. To achieve compliance, we are using the PCI proxy from DataTrans AG in Switzerland for receiving raw credit card data. For processing payments we are using Adyen N.V. from The Netherlands.

You have two options to pass in payment data into apaleo, which depend on the use case:

1. You receive raw credit card data from a channel. Then just forward this information as credit card with the booking. During implementation you can send test credit cards directly to but you need to use as a base-url whenever you send real credit card data to apaleo in produciton mode. For creating a booking with real credit card data, you would have to call


2. You have your own booking engine and want to run customers through 3DS for Strong Customer Authentication to help your hotels to benefit from the liability shifting back to the card issuing bank. Then you can use the payment widget on your IBE and forward the card token and transaction details as payment account alongside the booking. Read more about the integration of the payment widget in the IBE Integration Guide. In this case you can the following API:


Some OTAs collect the money for the hotels or allow other payment methods and then issue a virtual credit card for the hotel to use collecting the money. To allow us to process those cards correctly, please mark virtual credit cards accordingly. Just set the isVirtual property of the credit card or payment account to true. For some channels you might even get told on which day the virtual card will be activated, so please also share this information with us in the property activationTime.

Channel and Sources

apaleo currently supports three channels: BookingCom, Expedia and ChannelManager. 'BookingCom' and 'Expedia' should only be used if your application is  directly connecting those channels to apaleo. Most likely, you are connecting multiple travel agents or a Central Reservation System (CRS), and should use ChannelManager. When setting ChannelManager as the channel, you have to specify more details in the source. The list of allowed sources you can define right now can be retrieved using the apaleo Booking API. You need to map your sources to the sources allowed in apaleo. You can use the source 'Other' as a fallback, but if you are missing a source in apaleo's list, then please let us know by opening an issue in

You need to map your sources to the sources allowed in apaleo. You can use the source 'Other' as a fallback, but if you are missing a source in apaleo's list, then please let us know by opening an issue in

External ID, your ID, apaleo ID

Distribution channels do have their own booking codes they use to confirm the booking with the guest. Guests use these codes or IDs when they arrive at the hotel, want to check in online or call the hotel. Therefore, this information also needs to be forwarded to apaleo, using the externalId field of a reservation. It is important to make the externalId unique per apaleo account. Would be a bad identifier, if it would not be unique. A simple way to achieve this is appending an incremental number.

You probably also store those reservations, and provide the channels out there and your users to modify and see them. Lastly, apaleo has an ID too, which is generated when a reservation is created in our system. When you create a booking, we return the booking ID, and an ID for every single reservation in it. Your IDs and ours need to mapped, similar to how it is for rate plans. That way you know how to forward modification or cancellation requests to apaleo.

Travel agent commission

You can set the travel agent commission for every reservation in the booking.

"commission": {
"commissionAmount": {
"amount": 10,
"currency": "EUR"
"beforeCommissionAmount": {
"amount": 120,
"currency": "EUR"

When setting the `commission`, the `commissionAmount` is required while the `beforeCommissionAmount` is optional.
The `commissionAmount` indicates the amount that needs to be paid for the reservation. The `beforeCommissionAmount` indicates the amount of the reservation excluding the commission amount.

Modify Bookings

The request model for modifications is very similar to the one for creating bookings. Call the following, and pass the apaleo booking ID:

PUT /bookings/{id}
PUT /reservations/{id}/cancel

To make the API easier to use, we decided to deviate from how PUT normally works in two areas:

Undeletable first level objects

The PUT requests basically is a “create or update” request. If you omit one of the fields on the first level, or send an empty object, we will not remove it or cancel it, but pretend you sent the exact data we already have stored. The first level fields are:

  • Credit Card
  • Booker
  • Comment
  • Booker Comment
  • List of Reservations

This allows you to add a reservation to an existing booking by just sending the new reservation without always having to repeat the data for the booker, the credit card or all the other rooms.

Reservations are identified by the apaleo reservation ID. Reservations without this ID are considered to be new and will be added to the booking. Reservations with an ID will be updated based on the provided information. The API behaves like a “create or update” request.

Merging of guest and booker data

OTAs often do not provide a rich set of data, and a lot of guest-related data is collected by the hotel and put to the guest profile in the property management system (like, apaleo). To not accidentally lose this information we only allow you to override the following fields:

  • Guest Data
  • Booker Data
  • Travel Purpose

If you omit these fields or do send some of their properties empty or not at all, we will not remove it, we will just leave it untouched.

Get certified

When you're done with the integration, we'd like to have a look at it to see all is working okay. We're more strict here than with other integrations, as the impact of having something wrong here is much higher than, say, a housekeeping app, or concierge services. Those are the points we'll check:


  • How is the flow when connecting a new customer?
  • How do you map rate plans?


  • Change Prices, Restrictions and Availability in apaleo and verify the data is received by you. Ensure prices with decimal are received correctly
  • Are changes to surcharges for extra adults transmitted correctly?
  • How are prices for additional services like breakfast synchronised? (if applicable)
  • Is information about taxes (afterTax, beforeTax) relevant for you? If yes, how do you use it?


  • Book a rate plan with an included service
  • Book multiple rooms in one booking (e.g. for reservations with all room stays)
  • Test reservations with prices that have decimal places to ensure they are handled correctly
  • Test reservations with different pricing types (BeforeTaxesWithVat, BeforeTaxes or AfterTaxes)
  • Change arrival and departure
  • Add rooms to a booking or cancel rooms
  • Change guest data for the primary and for additional guests
  • Receiving proper number of adults and / or children per room
  • Cancel a booking
  • Add and remove extras on a reservation
  • How do you handle credit cards, including transmission of virtual cards?
  • How do you treat exceptions if e.g. you cannot deliver a reservation?
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...