Setup and configuration

This page covers everything you need to configure before your POS integration can post charges and payments to Apaleo.

The folio model

The key entity to interact with Apaleo’s financial 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”) as well as all payments.

Charges can be one of two types:

Charge Description
Standard Delivered by the hotel, recorded as revenue and VAT.
Transitory A charge posted on the guest’s folio without counting as revenue of the property. It is mostly used to record tips.

Set up your POS structure

Before you can post a single charge, you need two things in place: sub-accounts and service mapping.

Select the sub-accounts to map

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

Sub-accounts help you better understand and structure your revenues. For example, in a restaurant you might have:

  • Food
  • Alcoholic drinks
  • Non-alcoholic drinks

To retrieve sub-accounts available on the property, use 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 don’t exist for transitory charges, since those aren’t revenue.

Map your services

Next, map the specific items and services sold through the POS to Apaleo sub-accounts, using the Finance API. Once mapping is complete, items sent from the POS are automatically reported correctly.

GET /finance/v1/types/service-types

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

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

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

  • VAT type
  • Service type
  • [Optional] Sub-account ID

Map allowed payment methods

Properties can restrict which payment methods a POS is allowed to use when posting payments. Before your POS posts a payment, retrieve the list of payment methods enabled for the property:

GET /settings/v0-nsfw/properties/{id}/payment-methods

Map your POS’s own payment methods to the values returned by this endpoint, and only use enabled methods when posting.

Important: any payment submitted with a method not enabled for the property will be rejected. This applies wherever your POS posts payments — including POST /finance/v1/folios/{folioId}/payments.

Next step

Once setup is complete, move on to posting charges — either to a guest reservation or as non-reservation charges.