Send bookings

To create a new booking in apaleo, all you need to do is send 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.

You must specify the 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 a ‘multi-room reservation’. Other systems call those differently: booking.com 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 use the PCI proxy from DataTrans AG in Switzerland to receive 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 https://distribution.apaleo.com, but you need to use https://secure-distribution.apaleo.com as a base-url whenever you send real credit card data to apaleo in production mode. For creating a booking with real credit card data, you would have to call

POST https://secure-distribution.apaleo.com/v1/bookings

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 use the following API:

POST https://distribution.apaleo.com/v1/bookings

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 share this information with us during the property activationTime.

Channel and sources

apaleo currently supports the following channels: BookingCom, Expedia, Homelike, HRS, IBE, AltoVita, DesVu and ChannelManager. BookingCom, Expedia, HRS, IBE, Homelike, AltoVita and DesVu 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 contacting us at api@apaleo.com.

https://api.apaleo.com/booking/v1/types/sources

External ID, your ID, apaleo ID

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

This can be achieved by using the externalId field of a reservation. The externalId is the field a channel connector can use to store their unique id in order to identify the reservation. It should contain the provider confirmation ID (internal code of the customer-facing entity, e.g., travel agency; a booking reference the guest receives). We search by startsWith in the externald field.

An additional (optional) way is using dedicated fields in ExternalReferences to add any other booking references or PNR (Passenger Name Record, also known as Record Locator) you’ve received from the booking provider or any intermediary systems. The available fields are globalDistributionSystemId, onlineTravelAgencyId, onlineBookingToolId, and channelManagerId. We search by exact match in those fields. Connected check-in apps like kiosks do not rely on the externalReferences alone, as they are optional, but they use it as a secondary option to find reservations.

You probably also store those reservations and allow the channels 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 our booking IDs need to be 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.