Stay

The STAY phase begins when the guest physically arrives at the hotel. At this point, several key steps need to be completed to ensure a smooth check-in experience:

  • The guest must be informed of their assigned room
  • Room keys need to be issued or activated
  • Guest information should be collected for registration forms and any legal or operational requirements

To get the reservations of the guests who have checked in, use webhooks to receive a notification when a reservation changes to checked-in.

During their stay, guests may wish to view the current total cost of their reservation—including any additional services or extras they’ve booked. This allows them to stay informed about their charges in real time and avoid surprises at check-out.

Check the Current Price Guests appreciate transparency during their stay. Providing real-time access to the current total cost of their reservation—including any added services—can greatly enhance their experience. Consider offering an in-app view of the current balance, or take it a step further by sending notifications whenever the total changes, similar to how banking apps handle account activity.

GET /booking/v1/reservations/{id}

Look for the balance field. You can also use webhooks to be informed about changes.

Post Charges The guest may have made additional purchases during their stay—such as shopping at the hotel boutique or using services like the spa. These charges should be reflected in the reservation balance.

For details on how to retrieve and display these charges, refer to the following documentation: Point of Sale integration guide. You can add the charges to her reservation by making a simple call to:

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

View Charges The guest may want to review all charges associated with their stay. You can provide this information by calling the following API:

GET /finance/v1/folios/{id}

Split Charges The guest may wish to split charges between their company and personal account—for example, if certain expenses like a spa treatment aren’t covered by company policy. This can be handled by calling the following APIs:

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

Add Credit Card Payments If the guest provided their credit card details during the booking process, you can charge the card directly using the API. While complex processes occur behind the scenes, the implementation on your end is as simple as calling:

POST /finance/v1/folios/{folioId}/payments/by-payment-account

At check-out, the guest may wish to update the invoice address—something that’s much more convenient to do from their room than at the front desk. Once updated, they can also complete the payment using the credit card provided at the time of booking, ensuring a smooth and contactless departure experience.

Update the Invoice Address Please note that the guest’s personal address is not necessarily the same as the billing address. Apaleo stores these separately. If you need to update the billing address, use the following API:

PATCH /finance/v1/folios/{id}

Verify The Details Once the billing address has been updated and the payment is completed, you can proceed to generate the invoice. To do this, simply call the following API, providing the folioId as input:

POST /finance/v1/invoices

Generate an Invoice After the billing address has been updated and payment is completed, you can generate the invoice and email it to the guest. This operation requires the folioId as input. Don’t forget to close the folio after generating the invoice to ensure the billing process is finalized.

POST /finance/v1/invoices
GET /finance/v1/invoices/{id}/pdf
PUT /finance/v1/folio-actions/{folioId}/close

Check-out

PUT /booking/v1/reservation-actions/checkout

Now that all is taken care of, Caroline just leaves the hotel.