Step 6: Reservation and booking

Last updated on Invalid Date

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:

  • User searches for a product / time slot to book, finds one
  • User asks Bókun to book the above slot (through widget, OTA or API request etc.)
  • Bókun makes reservation request for requested combination of pricing categories, rates etc.
  • If the reservation is approved, Bókun proceeds with securing funds (if applicable) for this particular booking
  • Once the funds are secured, Bókun issues confirmation request

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:

  • For Bókun-originated bookings, reservation can auto-timeout in 30 minutes.
  • For OTA-originated bookings, timeout varies. GetYourGuide expects to hold the reservation for one hour, Expedia specifies this manually (typically 30 minutes) and so on.

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.

Two steps VS single step booking process

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

 

Two steps booking process: reservation request and response (1/2)

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

Attribute
Mandatory
Notes
parameters
Plugin configuration parameters, as specified in Step 3. plugin configuration
reservationData
Data containing details about what product has been booked, what are the pricing categories and their quantities, rates, pickups and so on. NOTE: in some cases, parts of this data may be preliminary. For example, some OTAs do not provide traveller details at this stage but only pricing categories and relevant quantities. ConfirmBookingRequest will contain reservationData field of the same type which will contain the final data about the passenger(s), external sale ids and so on. It is safe to assume things like start times, pricing category quantities and rates to be the same across both requests.

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

Attribute
Mandatory
Notes
successfulReservation
see notes
Should be set if reservation had succeeded. Successful reservation must have reservationConfirmationCode set to some unique ID. The next step (confirmation) will use this code to confirm this reservation
failedReservation
see notes
Should be set if reservation had failed. reservationError must refer to the actual error and will be shown on the screen to the end user. Either successfulReservation or failedReservation should be set but not both. Setting none will trigger an error
 

Two step booking process: confirmation request and response (2/2)

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

Attribute
Mandatory
Notes
parameters
Plugin configuration parameters, as specified in Step 3. plugin configuration
reservationConfirmationCode
Same as ReservationResponse::successfulReservation::reservationConfirmationCode, as supplied by the plugin during reservation
reservationData
Data containing final details about what product has been booked, what are the pricing categories and their quantities, rates, pickups and so on. NOTE: in some cases, this data may differ from ReservationRequest::reservationData. This can happen because some OTAs might not send the final details at the reservation stage. Plugins must treat reservation data of this (confirmation) request as the final source of truth. Key elements, such as number of seats, rates and pricing categories are expected to be the same
confirmationData
Data pertaining to confirmation (e.g. what kind of tickets to issue)

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

Attribute
Mandatory
Notes
successfulBooking
see notes
Should be set if confirmation had succeeded. Successful confirmation must have bookingConfirmationCode set to some unique ID as well as tickets (see relevant objects for more details) Note: if plugin supports binary tickets and implements REST transport, the contents of those tickets must be encoded with Base64, as explained in Binary ticket data object differences
failedBooking
see notes
Should be set if confirmation had failed. bookingError must refer to the actual error and will be shown on the screen to the end user. Either successfulBooking or failedBooking should be set but not both. Setting none will trigger an error
 

One step booking process: reservation and confirmation

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:

Attribute
Mandatory
Notes
parameters
Plugin configuration parameters, as specified in Step 3. plugin configuration
reservationData
Data containing final details about what product has been booked, what are the pricing categories and their quantities, rates, pickups and so on
confirmationData
Data pertaining to confirmation (e.g. what kind of tickets to issue)

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.

 

Reservation cancellation

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:

Attribute
Mandatory
Notes
parameters
Plugin configuration parameters, as specified in Step 3. plugin configuration
reservationConfirmationCode
Same as ReservationResponse::successfulReservation::reservationConfirmationCode, as supplied by the plugin during reservation
agentCode
Agent code who has cancelled the reservation (if set)

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

Attribute
Mandatory
Notes
successfulReservationCancellation
see notes
Should be set if reservation cancellation had succeeded.
failedReservationCancellation
see notes
Should be set if reservation cancellation had failed. Either successfulReservationCancellation or failedReservationCancellation should be set but not both. Setting none will trigger an error

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.

 
Did this answer your question?
😞
😐
🤩