Booking process

Last updated on April 26, 2022

Booking vs product booking

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.

Notion image

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.

Direct Booking Request or Shopping Cart?

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

  1. Send a direct booking request,
      • Send all the products you want to book in a single booking request directly to checkout.
  1. ...or use the shopping cart API
      • Add individual product booking requests one at a time to the shopping cart.
      • When the customer is ready, send the shopping cart to checkout.

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:

Notion image

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

  1. Aggregate all product booking request into a single Booking Request, and send a single request to get checkout options.
  1. Review any questions that need answering in the checkout options response, and add answers to the Booking Request.
  1. Send a checkout request containing the Booking Request with the answers added.

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.

Notion image

The flow for shopping cart would normally be as follows:

  1. Send a single product booking request to the shopping cart. Repeat as needed. Also possible to remove product bookings from the cart.
  1. Send a request to get checkout options for the shopping cart.
  1. Review any questions that need answering in the checkout options response, and add answers.
  1. Send a checkout request referencing the shopping cart, and including answers to any required questions.

Booking Request Schema

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: https://bokun.github.io/api-docs/schemas/BookingRequest.html):

Notion image

The Booking Request has the following fields:

  • mainContactDetails: Answers to the main contact details questions.
  • externalBookingReference: Optional. Specifies an external booking reference to store on the booking.
  • externalBookingEntityName: Optional. Specifies the name of the external booking entity that created the booking. Max 255 characters.
  • externalBookingEntityCode: Optional. Specifies the code/ID of the external booking entity that created the booking. Max 100 characters.
  • labels: Optional. A list of booking labels to apply to this new booking.
  • promoCode: Optional. A string value with a promo code. This will be applied to the booking if there are valid products for the given promo code in the booking request.
  • giftCardCode: Optional. A string value with a gift card code. This will be applied as payment for the booking if there are valid products for the given gift card in the booking request.

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

Activity Booking Request Schema

Notion image

The following fields can be used for all activity types:

  • activityI: Required. The ID of the Activity product being booked.
  • rateId Optional. The ID of the activity rate to use. Default value is the default rate of the Activity.
  • note: Optional. A note that will be attached to the booking.
  • checkedIn: Optional. Specifies whether to mark the booking as "arrived" or "checked in". Useful when creating bookings where the passenger is already checked in.

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

Specifying Answers in the Booking Request

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:

  • answers: Any per-booking answers for the booking
  • pickupAnswers: Any answers relating to pick up (if booked). For example, if an airport was selected for pick up, we may ask about flight number.
  • dropoffAnswers: Any answers relating to drop off (if booked). For example, if an airport was selected for drop off, we may ask about terminal.

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

Activity booking type: Date / Date & time / Pass

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.

Specifying the date

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):

"date": "2016-02-20",

Specifying date and time

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):

"date": "2019-02-20","startTimeId": 567,

Booking "on request" products

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.

Specifying a request callback URL

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:

  • CONFIRMED
    • The supplier confirmed the booking.
  • REJECTED
    • The supplier rejected the booking.
  • TIMEOUT
    • The supplier did not respond before the deadline.

Specifying a deadline for the supplier

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):

"responseDeadline": "2020-06-01 12:00"

Creating a custom booking

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

"date": "2019-02-20",
"customizedTime": "15:15",
"customizedItinerary": "This is the custom itinerary, can contain HTML",
"customizedDurationMinutes": 30
"customizedLineItems": [
	{
		"description": "Entry fee",
		"unitPrice": 130,
	}
]
 

Booking pick up

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:

  • OPTIONAL : You can optionally book pick up. If you do, you MUST provide pick up place selection when booking.
  • PRESELECTED : Pick up is mandatory (and automatically selected) when this rate is booked. You MUST provide pick up place selection when booking.
  • UNAVAILABLE : You cannot book pick up for this rate.

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

"pickup": true,"pickupPlaceId": 567

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"

Booking drop off

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.

"dropoff": true,"dropoffPlaceId": 567

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

"dropoff": true,"dropoffDescription": "150 Some Street, Some post code"

Booking the Passengers

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

Notion image
  • pricingCategoryId: Required. The ID of the pricing category that this passenger belongs to (e.g. Adult, Child, etc.).
  • passengerDetails: Personal details for the passenger, as asked for in the booking questions.
  • answers: Answers to any per-passenger questions.
  • extras: Container for extras being booked for this passenger.
    • extraId: The ID of the extra being booked.
    • quantity: Optional. Number of units being booked. Defaults to 1.
    • answers: Answers to any per-extra questions.

Promo Codes and Gift Cards

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.

  • Using a direct booking request
    • To apply a promo code during check out, specify the promo code in the promoCode field of the booking request
    • To apply a gift card during check out, specify the gift card code in the giftCardCode field of the booking request

Using the Shopping Cart

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 the Shopping Cart

GET /cart.json/{cartUUID}

The response will be shopping cart schema.

Add Activity to the Shopping Cart

POST /cart.json/{cartUUID}/activity

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

Remove from the Shopping Cart

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

The response will be shopping cart schema.

Apply Gift Card to Shopping Cart

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

Applies the gift card specified to the shopping cart.

Apply Promo Code to Shopping Cart

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

Applies the promo code specified to the shopping cart.

Remove Promo Code from to Shopping Cart

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

Removes any promo code from the shopping cart.

Did this answer your question?
😞
😐
🤩