The basics

If you are developing point of sale applications, you probably are an expert in this, but here’s a short introduction to key concepts and how they are implemented in apaleo.

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 as follows:

As explained above, the API you need to call depends very much on the hotel’s setup and wishes. We recommend building an integration for the two prominent cases and letting the hotel configure how things work in your application.

Next to consider is on which folio charges and payments are posted. It depends on how much of the POS charges and payments should be reflected in apaleo. Is it only the consumption a guest is allowed to post on its reservation and pay later? Or should the POS be reflected in apaleo?

You can post directly on a guest folio, but 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 the POS should be reflected in total, it is recommended that the POS outlet is created as separate property so that it is easy to separate POS revenue and payments from the core operations.

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.

In that case you recognize revenue in apaleo by creating an external folio on the property where all the aggregated charges and payments can be posted at the end of the day or shift. If one of those charges is put on the room, you can post a payment using the “Other” payment method with the comment “paid by reservation ABCD-1”, and you post a transitory charge on the folio of the reservation ABCD-1.

In summary, hotel needs to decide how much of the POS should be reflected in apaleo, how POS charges allocated to a guest reservation are recorded (revenue vs. transitory) and how tip is handled.

Prerequisites for connecting your POS to apaleo

You need yo create a basic structure for connecting your POS to apaleo. This includes:

• Creating sub-accounts
• Mapping services
• Creating a POS outlet (optional)

POS are owned by either hotels or they are third-party POS like flower shop. If the hotel owns the POS then the charges and tips are posted to the guest reservation. For third-party POS transitory charges and tips are posted to the guest reservation.

The hotel decides how charges to the guest reservation should be reflected. If a revenue charge is posted on the room, then it is excluded on the PO external folio. If POS takes care of the POS revenue independently, then transitory charge is posted on the guest reservation.

Creating sub-accounts

In your POS app, you have a (detailed) set of goods and services. You can assign each type of product a category. Then, you can map these categories to custom sub-accounts in apaleo. The sub-accounts will be reflected in accounting, detailing the revenues.

Sub-accounts allow you to better understand and structure your revenues. For example, in a restaurant, you can have the following items:

• Food

• Alcoholic drinks

• Non-alcoholic drinks

As hotels can turn sub-accounts on and off, the schema might include sub-accounts or not. You can overwrite this by specifying the accountingSchema. The simple schema always excludes sub-accounts, and the extended schema always includes them. For example,

Simple: Revenues -> RevenueOther -> RevenueOther_Normal

Extended: Revenues -> RevenueOther -> RevenueOther-Spa -> RevenueOther-Spa_Normal

Use GET /settings/v1/features/{propertyId} to know if sub-accounts are enabled in a property. Retrieve the hotel’s schema by querying:

GET /finance/v1/accounts/schema

To create, modify, and retrieve sub-accounts access the Settings API.

GET /settings/v1/sub-accounts

Each sub-account has a unique code within one property (and a unique ID within an apaleo account) and belongs to exactly one revenue type. Sub-accounts do not exist for transitory charges, as those are not revenue.

Mapping services

Next, you map specific items and services for sale through the POS to apaleo sub-accounts using the Finance API. When the mapping is completed, items sent to apaleo from the POS are automatically reported correctly.

GET /finance/v1/types/service-types

{
  "serviceTypes": [
    "Other",
    "Accommodation",
    "FoodAndBeverages",
    "CancellationFees",
    "NoShow",
    "CityTax"
  ]
}

The service types that are of interest are FoodAndBeverages and Other. Each of these has sub-accounts for each VAT type that exists in the hotel’s country.

To understand where a charge will end up in accounting, you need:

• VAT type
• Service type
• [Optional] sub-account id

Creating a POS outlet (property)

Hotel needs to decide if the POS revenue should be reflected internally, then we have non-room charges and those are posted to external folios – and second decision is - is it external folios on hotel property or a POS property. If the hotel wants to keep the revenue sources separate from the hotel accommodation then it can create a POS property and direct all POS revenue to the external folio of the POS property.