Latest

Blog Detail Title

Short Content Here

by Author Name

Date Published

Developer

POS Integration Guide

Andrea Stubbe November 13, 2018

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.

 

swagger

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.

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:

GET /finance/v1/accounts/schema

You can specify the sub-account when posting charges. There are no sub-accounts for transitory charges.

Non-reservation postings

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

GET /finance/v1/folios/{propertyId}

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.

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.
Comments

RECENT ARTICLES

by Andrea Stubbe

06/13/2019

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

05/02/2019

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

by Benjamin Schmid

01/20/2019

Upsell Integration Guide

This guide explains how you can connect your upselling application, and offer extra services or room upgrades to guests. If you are new to apaleo APIs, head ...

WANT MORE AMAZING THINGS?

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