Booking process

When you successfully complete a checkout, this will result in exactly one booking. The booking is the "order", that has the customer details, payments, etc. The booking will contain one or more product bookings.

For example, if you are booking two activities (e.g. whale watching on Wednesday and horseback riding on Thursday), this will result in one Booking containing two activity bookings.

When creating a booking, you can choose between two methods:

Which of these you choose will be based on your business case. When you send a direct booking request, you are sending a request containing a list of all the product booking requests you want to make directly to checkout:

The flow for direct booking request would normally be as follows:

However, with the shopping cart, the flow is different. You send individual product booking requests one add a time to the shopping cart, and when ready you send the shopping cart to checkout.

The flow for shopping cart would normally be as follows:

The Booking Request JSON schema has a list of product booking request. Each product booking request is on the same format that would be sent to the shopping cart.

The Booking Request schema has the following structure (see the schema online here:

The Booking Request has the following fields:

The Booking Request also has lists of product booking requests. Let's review each type in more detail.

The following fields can be used for all activity types:

Now let's look at the other fields, as their use depends on how the product is set up.

The Activity Booking Request schema inherits from the Answers schema (see "Questions schema"). This allows you to supply answers to booking questions inside the booking request:

You can specify more answers in the Passenger Booking Requests, see more on that below.

Before you try booking an activity you must inspect what the Activity.bookingType is, so you know how to proceed with the booking. Note that if the bookingType is PASS, then you do not have to specify the date or the time.

For activities with booking type DATE or DATE_AND_TIME, you need to specify the date additionally (we leave out the other data for brevity):

For activities with booking type DATE_AND_TIME, you will also need to specify the start time ID (we leave out the other data for brevity):

If the Activity.capacityType is ON_REQUEST, then we cannot provide instant confirmation for the booking. Instead, you can supply a callback URL which we will post to once the supplier responds to the booking request. You can also specify a deadline for the supplier.

For ON_REQUEST bookings, you can specify a callback URL when booking. When the supplier responds, you will get an HTTP POST to this URL, containing the booking details on JSON format in the request body. This is how you would specify the callback URL in your booking request (other data left out for brevity):

"responseCallbackUrl": "https://example.com/bokun-callback"

To determine whether the booking was confirmed or rejected, look at the "status" field in the booking JSON you get in the callback request POST body. It will be one of the three:

Optionally, you can specify a deadline for the supplier. This is a date and time before which the supplier must respond. If the supplier does not respond to the booking request before this deadline, then the booking will be moved to status TIMEOUT. If no deadline is specified, then the default product settings will apply. This is how you would specify the deadline (format is yyyy-MM-dd HH:mm):

If the activity supports it, you can create a customized booking:

First, make sure you understand how the pick up is set up for the product is booking. You can read about this in the following section: Pick up: selection & pricing. How you book pick up depends on the value of ActivityRate.pickupSelectionType:

To book pick up, set pickup to true, and provide the ID of a pick up place that the activity allows (other data left out for brevity).

To get the list of available pick up places for the activity, please use the following endpoint (specify the ID of the activity you want to book in the path):

GET /activity.json/{id}/pickup-places

If the activity allows custom pick up (Activity.customPickupAllowed is TRUE), then you can specify the pickup place as free text:

"pickup": true,"pickupDescription": "150 Some Street, Some post code"

If the activity rate being booked provides pick up (ActivityRate.dropoffSelectionType is not set to UNAVAILABLE), then you can provide drop off details (other data left out for brevity). Set dropoff to true, and provide the ID of a drop off place that is allowed by the activity product.

If the activity allows custom drop off (Activity.customDropoffAllowed is TRUE), then you can specify the drop off place as free text:

You must book at least one passenger. Now let's look at the schema for the Passenger Booking Request.

Promo codes are a way for you to provide a discount to your customers, whereas gift cards act as a form of payment (either partial or full). How you apply promos and gift cards during checkout depends on whether you're using the shopping cart or direct booking request.

The shopping cart functionality assumes that you maintain a unique ID for each of your carts. The ID must be unique across the booking channel.

GET /cart.json/{cartUUID}

The response will be shopping cart schema.

POST /cart.json/{cartUUID}/activity

The request body should contain JSON using the Activity Booking Request schema. The response will be shopping cart schema.

GET /cart.json/{cartUUID}/remove/{productConfirmationCode}

The response will be shopping cart schema.

GET /cart.json/:sessionId/apply-gift-card/:code

Applies the gift card specified to the shopping cart.

GET /cart.json/:sessionId/apply-promo-code/:code

Applies the promo code specified to the shopping cart.

GET /cart.json/:sessionId/remove-promo-code

Removes any promo code from the shopping cart.