Introduction to the data model of products – Bókun developer documentation

Before you try to book activities using the API, you must understand the different types of bookings and capacities on offer - as this will affect your booking requests. You therefore need to inspect how the activity is configured, before you can attempt to book it. You can see how to get the activity configuration details here: Get product details

Booking type: Date / Date & time / Pass

We support three booking types for activities (specified in Activity.bookingType):

DATE_AND_TIME

You must book a specific date and start time. Availability and capacity is managed per start time.

DATE

You only need to specify the date when booking, no start time. Availability and capacity is managed per date.

PASS

You do not need to specify date or start time when booking.

It is therefore important that you check the bookingType of the activity you are about to book. The PASS type is useful for booking products such as "tourist pass", museum admission, pool passes, etc. - products which do not require you to specify the date or time that you will be arriving.

Pass expiry

Passes can expire. For example, the tourist pass may only be valid for a month after purchase, or maybe you are buying a pass which is only valid until end of 2018. To see how the pass expires, you need to look at the activity passExpiryType which will be one of the following options:

NEVER

The pass actually never expires. Simple as that!

FIXED_DATE

The pass is valid until a fixed date as specified in the activity rate fixedPassExpiryDate.

RELATIVE_DATE

The pass is valid for X days after purchase, as specified in the activity rate passValidForDays .

Pass capacity

In most cases, activities with bookingType set to PASS , the capacityType will be set to FREE_SALE. If it is, however, set to LIMITED , then that means that there is a fixed number of passes available for purchase (remember that this is not per date, so this is the global capacity). An example case for this is a pass for a music festival, where there are a total of 1000 passes available.

In such cases, the remaining number of available passes can be found in the passesAvailable field on the activity.

Opening hours

PASS products will generally specify opening hours. For example, a museum may have opening hours. The opening hours are specified in the activity defaultOpeningHours field.

Sometimes opening hours are different over summer vs winter. In such cases the default opening hours may be overridden by specifying seasonalOpeningHours, so make sure you check for that too.

Capacity type: Free sale / Limited / On request

It is important to understand the difference between availability and capacity:

Availability : dates when the activity is available. A FREE_SALE product does still have availability.

Capacity : number of seats available for a particular availability. A FREE_SALE product does not have capacity.

We differentiate between three capacity types for activities (specified in Activity.capacityType):

FREE_SALE

Unlimited seats, can be sold without performing capacity checks.

LIMITED

Only a limited number of seats on offer, must check remaining capacity before booking.

ON_REQUEST

No capacity specified. Instead the operator (also called supplier) will manually confirm or reject each booking.

Pricing categories (aka Ticket categories)

TBD

Rates

TBD

Tiered pricing

TBD

Pick up: selection, pricing, and pick up time

Whether or not a product offers pick up is specified on both the product level and on the rate level. First let's look at the relevant fields on the product level:

meetingType: Describes how participants meet at the beginning of a tour/activity. Has one of the following values:

MEET_ON_LOCATION

Participants should meet on location, they have to get there on their own. Pick up is not offered for any rate.

PICK_UP

Pick up is mandatory and automatically selected at time of booking. Pick up details must be provided when booking. Participants will be picked up at one of the available pick up places. The rates will have pickupSelectionType set to either OPTIONAL or PRESELECTED

MEET_ON_LOCATION_OR_PICK_UP

Participants can either meet on location, or ask to be picked up. The rates will have pickupSelectionType set to one of: OPTIONAL, PRESELECTED, UNAVAILABLE.

customPickupAllowed (TRUE/FALSE): Specifies whether pick up place can be specified as free text. If this is false, then pick up place must be selected from the product's predefined list of pick up places.

Now let's look at the activity rate level settings. The following fields are used to specify the pick up settings within a rate:

pickupSelectionType: Specifies how to handle pick up for this rate. Note: if Activity.meetingType == MEET\_ON\_LOCATION, then this will always be UNAVAILABLE. Has one of the following values:

OPTIONAL

Pick up is available, but the product can also be booked without pick up. Selection is done at the time of booking.

PRESELECTED

Pick up is mandatory and selected automatically when this rate is booked - you must provide pick up details at the time of booking.

UNAVAILABLE

Pick up is not available when this rate is booked.

pickupPricingType: Specifies whether pickup is included in the price or whether it is priced separately. Has one of the following values:

INCLUDED_IN_PRICE

Pick up is included in the price when booking this rate.

PRICED_SEPARATELY

Pick up is priced separately when booking this rate.

pickupPricedPerPerson (TRUE/FALSE): Specifies whether pick up is priced per person (per unit of ticket category). If this is false, then pick up is priced per booking. Note that this field is only relevant if Activity.meetingType != MEET\_ON\_LOCATION and pickupPricingType == PRICED\_SEPARATELY.

If pick up is offered, when should the traveller be ready for pick up? The pick up time in Bokun is not currently dependent on the pick up place. Therefore, to find the pick up time, simply have a look at:

Activity.startTimes[].pickupHour

Activity.startTimes[].pickupMinute

Extras: selection, pricing, and max units

The details of how an extra is priced can be found in the activity rates, under "extraConfigs":

selectionType

OPTIONAL or PRESELECTED. This determines whether the extra is optional or is always selected. If the extra does not have a config in extraConfigs, then it is unavailable for this rate.

pricingType

INCLUDED_IN_PRICE or PRICED_SEPARATELY. This determines how the extra is priced. It is either included in the total price (in which case there will not be a separate line item in the invoice, and you don't have to worry about the pricing for the extra), or priced separately - which means that having the extra will impact the total pricing of the booking.

pricedPerPerson

either TRUE or FALSE. This determines how pricing is specified for the extra. If false, then there is a single cost item for the extra. If true, then the extra can be priced differently for different pricing categories (e.g. separate cost item per pricing category - so you can enter different price if extra is selected by Adult vs Child, for example).

Note that these settings in the rate only specify how the extra should be selected and how it is priced. It does not specify anything about the number of units can be booked of the extra.

In terms of how many units of the extra can be booked, you need to look at the extra itself (as retrieved from the activity) rather than the rate. Then you should apply the following rule:

If extra.limitByPax == TRUE, then limit the number of extras by the number of passengers being booked.

Else, if extra.maxPerBooking > 0, then limit the number of extras by extra.maxPerBooking.

Else, there is not really a maximum, but it's probably a good idea to set a sensible one.