Step 6: Reservation and booking

Once the searches for availability are complete, the user might proceed with the booking. Booking in Bókun is split into two steps: reservation and confirmation.

Reservation is a step where availability is reserved for a particular time slot. Bókun normally triggers confirmation without delay if the reservation step succeeds. However, any given reservation must be held for some limited time (defined by the external system), and return reserved slot back to availability if no confirmation follows.

A typical scenario for reservation would be as follows:

Generally it is unacceptable to fail the booking at confirmation if the corresponding reservation request has succeeded. Such failure should be highly exceptional case and is described below. High rate of confirm-failure-after-successful-reserve events might result immediate disconnect of your plugin without any prior warning.

In the unlikely case of absence of the confirmation call after reservation, the plugin is responsible for releasing the reserved time slot and failing the confirmation (if it ever happens). Timeout for when to release the availability varies, based on the source of the booking:

The general advice would be to release the inventory back after one hour once the confirmation had not arrived. Since July 2022, Bókun also supports a separate API endpoint, cancelReservation, which might be called to trigger reservation cancellation providing incoming channels, such as OTAs, support it. See chapter below for more details on this.

Inventory API allows the plugin to either implement two step, where reservation and confirmation are two distinct calls, or alternatively single step booking process where both reserve and confirm actions are spliced into a single call. This chapter will address the differences between these two options.

The plugin has to declare its choice by either returning SUPPORTS_RESERVATION flag in the PluginDefinition::capabilities (signalling two step process is supported) or not. See Step 2: retrieval of plugin definition for the relevant specification part. The setting applies for all bookings.

The pros of supporting two step booking action is greater control over the booking process.

The pros of opting for single step booking is implementation simplicity. The cons of single step booking is higher chances of failed bookings.

Plugin choice over one or two steps is completely opaque to the Bókun platform. In cases where plugin only supports single step (reserve&confirm), Inventory service will always generate fake reservation response signalling reservation had succeeded. What this means is that single-step plugins are only sent reserve&confirm requests at the confirmation stage of the actual booking.

Above said, this opens a potential source of problems where a single-step plugin would fail the reserve&confirm request, failure being a reasonable outcome of such design. The problem here is that the upper chain (such as OTA) has already received a positive reservation response and collected the money from the end customer. Negative reserve&confirm response would then fail the booking and create a conflict. To avoid this, Bókun pre-emptively invokes deep availability check for given number of passengers, rate which is being booked etc. just before the reserve&confirm call is made. This, of course, does not provide robust guarantees against race conditions and other unpredictable circumstances. Therefore the general recommendation is to always implement the two step process whenever possible to minimize chances of a failed booking.

If it so happens that plugin is confirmed on the Bókun end (and possibly further up the chain) and failed to be confirmed on the Inventory plugin end, Bókun will mark this booking as conflicting (”Inventory confirmation failed") informing about the mismatch. It is the responsibility of the vendor who runs a particular Inventory plugin to liaise with (OTA, customer, etc) to rectify such booking.

gRPC service interfaces

gRPC-enabled plugins must implement the following API calls for two step process:

rpc CreateReservation (ReservationRequest) returns (io.bokun.inventory.common.api.grpc.ReservationResponse) {}

rpc ConfirmBooking (ConfirmBookingRequest) returns (io.bokun.inventory.common.api.grpc.ConfirmBookingResponse) {}

Single step process API is as follows:

rpc CreateAndConfirmBooking(CreateConfirmBookingRequest) returns (io.bokun.inventory.common.api.grpc.ConfirmBookingResponse) {}

REST URLs

REST-enabled plugins must provide valid responses on the following URLs for two step process:

POST /booking/reserve

POST /booking/confirm

Single step process API is as follows:

POST /booking/createAndConfirm

Booking reservation request is defined by ReservationRequest object and has the following structure:

The plugin must respond in form of ReservationResponse, which has the following structure:

Booking confirmation comes in the shape of ConfirmBookingRequest object and has the following structure:

The plugin must respond with ConfirmBookingResponse object which has the following structure:

If the plugin chose to implement single step booking process, it must not contain SUPPORTS_RESERVATION flag in PluginDefinition::capabilities. See Step 2: retrieval of plugin definition for more details.

It is also important that plugin must not fail booking calls if there is sufficient availability, as explained in Two step VS single step booking process. High levels of booking failures may result plugin disconnect without prior warning.

The request object, CreateAndConfirmBookingRequest, has the following structure:

The response object, ConfirmBookingResponse has the same structure and semantics as the confirmation step response in two step booking process. Refer to Two step booking process: confirmation request and response (2/2) for more details.

Bókun has added support for explicit reservation cancellation since July 2022. It is called if incoming sources (such as OTAs) support such functionality.

To ensure such calls are enabled, the plugin must contain both SUPPORTS_RESERVATION as well as SUPPORTS_RESERVATION_CANCELLATION flags in PluginDefinition::capabilities. Plugins supporting one step (reserve&confirm) are not eligible for this feature for obvious reasons.

gRPC service interface

gRPC-enabled plugins must implement the following API calls to support reservation cancellation:

rpc CancelReservation(CancelReservationRequest) returns (io.bokun.inventory.common.api.grpc.CancelReservationResponse) {}

REST URLs

REST-enabled plugins must provide valid responses on the following URL:

POST /booking/cancelReserve

Request and response format

Cancellation reservation request comes in the shape of CancelReservationRequest and has the following structure:

The plugin must respond in form of CancelReservationResponse, which has the following structure:

Note: we recommend using failed case with caution as this might lead to build up of list of abandoned phantom bookings in Bókun. For example, the plugin is expected to return successfulReservationCancellation in case if reservation has already been cancelled by your system as returning failure won’t help clarity and generate unnecessary noise. On the other hand, failing on reservationConfirmationCode never seen before is a valid failure case though.