POS Integration Guide

 In Miscellaneous

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.

Point of sales integration APIs

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

GET /booking/v1/reservations

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

GET /finance/v1/folios

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

POST /finance/v1/folio-actions/{folioId}/charges
POST /finance/v1/folio-actions/{folioId}/transitory-charges
POST /finance/v1/folio-actions/{folioId}/payments

The payment endpoint is neat, if the hotel is using the POS as a cash register.

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

Recommended Posts