Book a demo


Blog Detail Title

Short Content Here

by Author Name

Date Published


Digital guest journey with apaleo

Andrea Stubbe June 13, 2019

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 products! Whether it's a native mobile or progressive web app, a kiosk, voice controlled, automated - this guide explains how to integrate anything guest-facing with apaleo.

The guest's journey

The journey starts when a person (let's call her Caroline) sits at home or in the office, and thinks about staying at a hotel. We'll skip that whole part, and fast-forward to when she booked, and the reservation is created in apaleo.

We will also skip everything related to selling the guest more extras. Those are already covered here:

This is all about happiness of hotel guests and hotel staff (because they'll have to work less). Not about the money.

So let's start the journey...

PRE-STAY, Caroline receives a reservation confirmation, time passes and she can't wait to get to the hotel, and then she finally checks in.

That's where the STAY part of the journey starts, and at that point a couple of things have to happen:

  • Caroline needs to know which room to go to
  • She needs keys to the room
  • You need her data for registration forms and similar

Now, that doesn't need to be done in the exact moment of checking in. That's way too stressful. They can happen shortly after, or even before.

During the stay, when hanging out in the room, Caroline wants to check the total current price of her stay. Including all those rollercoaster rides and cotton candy she booked as extras.

When it's time to check out, Caroline updates the invoice address, because that's just nicer to do in bed, and not at the check-out counter. She also directly pays it, with the credit card she entered when making the booking. Now that all is taken care of, she just leaves the hotel.

POST-STAY, Caroline receives an email that says thanks for staying, and has the invoice PDF attached.

Reservation status and real time events

Each step in the journey relates to a reservation status in apaleo: Confirmed, InHouse, or CheckedOut. For changes from one to the next, we do send events you can observe using webhooks. The events to listen to are checked-in and checked-out. (Duh, Captain Obvious!)


Some example calls

Now that we got the basics covered, here are some calls that will come in handy.

Get the email address. You'll need this every time you want to send an email. You can choose who you want to send the email to the booker, or the guest.

GET /booking/v1/reservations/{id}?expand=booker

From the response, take or


Update guest information. This is for registration forms and statistics. First get the reservation, to fill the data entry form, and then pass the changed data to

PATCH /booking/v1/reservations/{id}


Assign a random room. Have to sleep somewhere, right? You best first check if a room is already assigned. Hotels don't always (never) appreciate it, if you mess with their room assignment.

GET /booking/v1/reservations/{id}?expand=timeslices

Careful here, you will see a unit on the top level of the response, but you might want to check in the timeslices to also see room moves. Otherwise you'll get the first room (pre-stay), the current room (stay), or the last room (post-stay). When you don't see anything, call this to assign a random unit:

PUT /booking/v1/reservation-actions/{id}/assign-unit


Let the guest pick a room. Room with a view? Next to the elevator or far away? The guest's favourite number is 5? Display all available rooms and their attributes:

GET /booking/v1/available-units

... and then enrich the results with the unit attributes you get for one unit:

GET /inventory/v1/units/{id}

Last thing to do, set the chosen room on the reservation:

PUT /booking/v1/reservation-actions/{id}/assign-unit/{unitId}


Check in, check out. Yeah.

PUT /booking/v1/reservation-actions/checkin
PUT /booking/v1/reservation-actions/checkout


Check the current price. As a guest, I would love this one, someone build it please! See the current price of your reservation. Or do it like banking apps do, and send a notification when the balance changes.

GET /booking/v1/reservations/{id}

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


Add credit card payments. When the guest entered their credit card info when making a booking, you can charge it using the API. Complicated things happen in the background, but for you it is a plain call to:

POST /finance/v1/payment-tasks


Update the invoice address. The guest's address is not necessarily the same as the billing address, and it is stored separately in apaleo. Change it with

PATCH /finance/v1/folios/{id}


Generate an invoice. Once the address is updated and everything is paid, you can generate the invoice. This call needs the folioId as input, for more information on that check the POS guide.

POST /finance/v1/invoices

Get the invoice PDF. You can do that right after you generated the invoice, or also pick it up later. If you do it later, either remember the invoice ID, or get it using the invoice API with filters. Or subscribe to invoice events using webhooks.

GET /finance/v1/invoices?reservationId={reservationId}
GET /finance/v1/invoices/{id}/pdf


Have a great guest facing app? Want to integrate? Request your credentials and you're ready to go!

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.


by Benjamin Schmid


IBE Integration Guide

Let's talk Internet Booking Engines (IBEs). They work best when directly connected to the PMS, without any intermediaries that might get in the way with delays ...

by Andrea Stubbe


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


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 letting us use your email address to send you our newsletter and other relevant stuff.