Non-reservation charge postings

Apaleo uses external folios to record all POS transactions that aren’t added to a guest reservation. For example, suppose someone orders drinks and food at the bar and settles immediately by cash or card, rather than adding it to their reservation, or someone who isn’t staying at your hotel orders a drink at the bar. In that case, these charges and payments are added to the external folio.

External folios

Create the external folio

Name the external folio so it’s easy to identify later — for example, “SDXE-SKYBAR-20260526” for a specific outlet and date.

External folios work the same as folios for reservations. Create one by calling:

POST /finance/v1/folios

and specifying external as the type, adding your custom code so it’s easy to find later. After that, you can post charges and payments.

You must not post room charges here. They’re only posted to the guest folios.

Once you’ve created the external folio, you can perform different actions. The most useful:

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

The folio balance should always be zero.

Post charges

1. Aggregate charges by service type, VAT type, and product group (sub-account).
2. For each combination, post a single charge to the external folio with the aggregated amount, VAT, and service type, using the following endpoint:

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

{
   "serviceType":"FoodAndBeverages",
   "vatType":"Normal",
   "subAccountId":"SDXE-3100",
   "name":"Food - SDXE-3100",
   "amount":{
      "amount":"800",
      "currency":"EUR"
   },
   "businessDate":"2026-05-26"
}

You can post charges to the current business date. Until 6 AM local time, you can also post to the previous business date.

For example, if a shift ends at 2 AM, you can explicitly set the previous day as the business date for those charges and payments.

Posting to future dates is not allowed, and posting to the previous business date is not possible after 6 AM.

Post payments

1. Aggregate payments by business day and payment method.
2. For each payment method, post a single payment to the external folio with the aggregated amount and the mapped payment method, using the following endpoint:

POST /finance/v1/folios/{folioId}/payments

{
   "method":"Cash",
   "amount":{
      "amount":1500,
      "currency":"EUR"
   },
   "receipt":"SDXE-SKYBAR-20260526",
   "businessDate":"2026-05-26"
}

A folio is limited to 5,000 lines (charges, payments, etc.). For high-volume outlets, close the folio before reaching the limit and open a new folio to continue posting.

Corrections

Same-day corrections

For transactions that need correction on the same business day (before day close), first correct the specific charge using:

POST /finance/v1/folio-actions/{folioId}/charges/{chargeId}/allowances

Once the charge is corrected you can do a refund using:

POST /finance/v1/folios/{folioId}/refunds

Posting negative charges

Required scope: folios.manage-negative-payments must be enabled in your app to use these endpoints.

Payments from a previous business day sometimes need to be corrected. For example, a guest returns an item a week after purchasing it because it was too small. Since the external folio for that business day is already closed, the refund can no longer be posted to it.

To apply a correction in this situation, you can post a global refund directly to the external folio, even when there’s no corresponding positive charge or payment on the folio to offset a previous business day transaction:

POST /finance/v1/folios/{folioId}/refunds

This lets you correct a payment without first reversing a specific charge.

This endpoint is for POS use only — it’s not available in the Apaleo UI.

Balance the folio

A folio can’t be closed with an open balance. To bring it to zero, post a negative charge using the same endpoint and structure as a standard charge, with a negative amount:

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

Posting negative charges is allowed only via API.

End of shift/day report

The external folio needs to account for all the aggregated (combined, not individual) charges and payments at the end of each day or shift.

The hotel defines the shift timings in the POS. If the shift ends at 2 AM, you can explicitly specify the previous day as the correct business date for which the charges and payments should be counted. Post the amount aggregated per payment method on the payment endpoint.

You can post to the previous business day only until 6 AM local time. For example, you can post charges and payments for 2026-05-26 until 6 AM on 2026-05-27.

Close a folio

Once all the aggregated charges and payments for the shift have been posted, the external folio can be closed. After closing, no more charges can be added or changed, and it becomes a document.

PUT /finance/v1/folio-actions/{folioId}/close

A folio cannot be closed with an open balance.