This guide explains how you can connect your point of sales (POS) application to apaleo. If you are new to apaleo APIs, head over to the quick-start guide , and learn how you can implement the apaleo connect flow.
A word on revenue and accounting
If you are developing point of sales applications, you probably are an expert in this, but here's a short introduction to key concepts, and how they are implemented in apaleo.
First of, the key entity to interact with apaleo's financing functionalities is the folio. Each reservation has a main folio, which is where stay-related charges end up by default. It is also possible to add more folios to a reservation. A folio lists all services and goods (the 'charges') which will eventually end up on a guest's invoice, as well as all payments. Charges can be:
- standard charges, delivered by the hotel, recorded as revenue and VAT. The invoice with VAT breakdown is done by the hotel
- transitory, which means they are delivered by a third party, and are recorded as transitory items. The receipt/invoice, including a detailed VAT breakdown for these charges is done by the delivering party.
Why should services and good which are not delivered by the hotel go on the folio anyway, you wonder? The answer is a question, one that every guest keeps asking: "Can you put this on my room?" - and they do not care whether the restaurant serving them breakfast, or the in-house spa is a different entity, with a different tax ID.
When building an integration, they key questions to answer are:
- Is the POS recording revenue for someone else than the hotel, and just adding it to the guest's invoice?
- If it's for the hotel, should all accounting and receipt creation for POS-business be done by the POS, or in apaleo?
If the answers are 'yes', and 'should be done by the POS', then transitory charges are your friend. Otherwise, standard charges will do.
"On the room"
Browse all apaleo APIs on https://api.apaleo.com/. For most POS integrations, the Core APIs are the only ones needed. Switch between different modules using the dropdown in the top right corner.
To find "the room" where charges should be added to, access the Reservation APIs
There are a variety of filters, and which ones you use is up to you. Most likely you will want to limit reservations to be in house, and then search for room number or guest name.
The Finance APIs let you access folios, invoices and the hotel's subledger. The first one you'll need is
Add the reservationId as a query parameter, and either get the main folio, or use any custom logic to find the folio you want to add charges or payments to.
One you identified the folio to use, you can perform different actions. The most useful being
The payment endpoint is neat, if the hotel is using the POS as a cash register.
apaleo comes with standard accounts for revenues, Accommodation, Food and beverages, and Other. It is possible to configure sub-accounts for each of those. Read the sub-ledger schema to see which ones exist:
You can specify the sub-account when posting charges. There are no sub-accounts for transitory charges.
Even though apaleo is not built to be a all-purpose accounting system (we think that you PoS systems out there should proudly own your data, and not become a satellite service to apaleo), some hotels still want it to be the one place where all revenues and payments are stored. There are two workarounds to make this happen:
Post it on the house
Each property in apaleo has its own folio, the "house account". This is an all-purpose dump for things not belonging to a reservation. You can access it calling
It comes with a few limitations: you cannot add prepayments, and you cannot created invoices from it. Unless you need those, we recommend to use this way to post revenues and payments.
Pseudo-rooms / reservations
Hotels can also decide to create "fake reservation", and create a number of folios on those, to mimic non-guest folios. Those folios work the same as normal folios, but there is no safe and standard way to identify them - it requires custom configuration on your side for each hotel, and gets even more complicated if they start having multiple folios.
POS for Pros
As explained above, the API you need to call depends very much on the hotel's setup and wishes. We recommend to build an integration for the two main cases, and let the hotel configure in your application, how things should work. Transitory or not, is the big question.
You can also use the API to add new folios to a reservation - if you want to have a dedicated POS-charge folio. Or, implement routing rules, by having smart logic to determine the folio to use.
If accounting is your strength, you can even access all apaleo accounting transactions, and store them in your system.
Whatever ideas you have - we're pretty sure, apaleo has an API for that. And if not, let us know on https://apaleo.github.com/api.
Posted byAndrea Stubbe