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


  1. 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 four channels: BookingCom, Expedia, Homelike and ChannelManager. BookingCom, Expedia and Homelike 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

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.