Getting Started with the Bókun OCTO API – Bókun developer documentation

What is the OCTO API?

Octo is an API standard for the connection between booking systems and reseller systems allowing them to interact without any custom development work.

➡️

Find the documentation of OCTO API data structures, endpoints & conventions in the OCTO developer hub!

Given the variety in booking systems and reseller systems, no standard can 100% match the data models of resellers or booking systems, so conversions are made on both ends. Booking systems providing data need to convert data from their internal data structures to Octo formats, and reseller systems consuming the API need to convert from Octo structures into their internal ones.

This page aims to make the most significant conversions on Bókun side transparent to developers to better understand the data Bókun is providing.

Base URL

The OCTO base URL is https://api.bokun.io/octo/v1 for the production environment and https://api.bokuntest.com/octo/v1 for the test environment.

Authentication

An OCTO API token can be created going to Settings → Connectivity → API keys. An API key needs to have the OCTO token enabled.

The token is used for authentication with a Authentication: Bearer <token> header on each request.

✅

By default, the token acts on your Bókun account returning e.g. all products bookable by you. Do to the OCTO limitation of not supporting pagination, we return only the first 100 products / bookings / etc. when the token is used as is. See the section below for what we recommend instead.

Vendor specific tokens

We recommend using your token in a vendor specific way. This is done by appending the vendor ID, separated with a /, to your token. Example: if your token is a1b2c3, then you can create a vendor specific token for vendor 64572 by authenticating your requests with the header:

Authentication: Bearer a1b2c3/64572

This way, when you query e.g. the /products endpoint, it will limit the returned data to the products that you can (re)sell from vendor 64572. No page limit is applied to this request.

Using the OCTO API together with other Bókun APIs

The OCTO API does not cover all of Bókun's functionality. If you want to use the REST API or GraphQL API additionally to the OCTO API, you can easily do that.

The OCTO API's booking supplierReference consists of the vendor prefix (usually a number of uppercase letters, often 3), followed by a dash and the booking ID, e.g. SEL-12345 for the booking ID 12345. That ID can directly be used in the REST API. GraphQL has an ID system, where the type of the ID is prepended to the ID itself with a colon and the result is base64 encoded. Example: SEL-12345 → 12345 → Booking:12345 → Qm9va2luZzoxMjM0NQ==.

The same goes for OCTO product IDs (prefixed in GraphQL with Experience), OCTO product option IDs (GraphQL prefix ExperienceRate) and OCTO unit IDs (GraphQL prefix PassengerCategory).

Requests

Supplier

When performing the supplier request with an API token as is - i.e. without vendor suffix - the supplier object returned is the supplier that owns the API token, that is: your own vendor. If you add a vendor ID to the API token, you'll get instead the vendor with that ID returned, if you have a marketplace contract with that vendor.

Availability

For Bókun experiences that are "Date Only" or "Pass" (not "Date And Time") to have their availability exposed through the Octo API, they must have opening hours defined. Date Only & Pass products without opening hours defined are not visible through Octo.

Booking Cancellation

According to Octo, a booking is either cancellable or not. In Bókun, you can always cancel a booking, and the supplier can define granular cancellation policies. In Octo terms, a booking is cancellable, when there's a 100% refund rule for the time of cancellation. Bókun's rich feature set around cancellation policies is unfortunately not available through Octo, so the Octo API cannot return detailed cancellation information. If you need this data, please use REST API or GraphQL API endpoints for this.

Octo has a boolean force parameter for cancellation requests, that has no documented meaning. We implement it that way, that when force == false, the cancellation request will fail, if the booking isn't 100% refundable. With force == true, the booking will always be cancelled.

Booking Update

The OCTO standard requires an update endpoint that is able to update bookings as long as they're cancellable and not yet redeemed. Our Bókun implementation goes beyond the OCTO standard and allows booking updates at any point, that you as the vendor are allowed to update the booking. The control over when you are allowed to do what lies therefore within your marketplace contracts.

Entities

Supplier

An Octo Supplier is in Bókun a vendor.

Product

An Octo Product is in Bókun a experience.

The product locale is the vendor's default locale. In Bókun, vendors can set up additional languages for a product, e.g. when guiding is available in multiple languages, but Octo does not provide a way of exposing this information via the Product object in Octo core (this will be added in octo/content).

Redemption method: The redemption method is always DIGITAL because Bókun encourages it's vendors to use digital tickets and vendors don't have a possibility to set up another option.

requiredContactFields: In Bókun, you can have both required and optional contact fields. Only required fields are returned here, since Octo doesn't have a way to communicate optionally available contact fields. Additionally, Bókun supports more types of contact fields than Octo does, e.g. passport information, date of birth, title, gender - you will not know whether these are required based on Octo API information. In Bókun, the email address, first name & last name are always required for a booking regardless of the configuration.

availabilityType: Bókun Date & Pass products are OPENING_HOURS whereas Date And Time products are START_TIME.

allowFreesale: For this to be true, a product needs to be both of type Pass and have the availability type Free Sale.

availabilityRequired: This is the case when the product is not a Pass product.

Product option

An Octo Product option is in Bókun a rate.

Cancellation cutoff: In Bókun, vendors have granular control over how much cancellation fee they want to charge based on how long before departure the cancellation happens. In Octo, there's only two stages, free cancellation or no free cancellation. The granularity of different percentages based on different time frames, that Bókun has, cannot be exposed through the Octo API. The data returned in this field shows the moment when 100% free cancellation is possible. If 100% free cancellation is never possible, a cancellation cutoff of 9999 days is returned.

Booking

An Octo booking consists on Bókun side of one booking and one (or more) activity bookings:

There can be more than one activity booking in case that a change has been made to the booking that cannot be represented in one activity booking. This is for example a change of the experience (Product) or rate (Product option). Also some other actions like rescheduling after a disrupted departure done by the passenger through the Bókun booking portal can lead to the situation where one, older, activity booking gets cancelled and a new one gets created. There's always at most one activity booking with a status different from Cancelled or Aborted.

The resellerReference is what's called externalBookingReference in other places in Bókun

The supplierReference is the booking's confirmation code, e.g. SEL-12345.

The cancellable refers to whether the booking is cancellable with a full refund (see note on cancellation above).

The notes is the general booking note in Bókun. Finance note & operational note are not exposed into Octo.

Booking Status

The booking status is mapped between Bókun and Octo in the following way:

Octo ON_HOLD: Bókun Cart & Reserved

Octo PENDING: Bókun Pending

Octo CONFIRMED: Bókun Confirmed

Octo REDEEMED: Bókun Arrived & No Show

Octo EXPIRED: Bókun Timeout & Error

Octo CANCELLED: Bókun Cancelled & Aborted

Octo REJECTED: Bókun Rejected

Unit

An Octo Unit is in Bókun a pricing category.

accompaniedBy in the restrictions is currently not implemented.

Unit types:

The unit types are mapped between Bókun and Octo in the following way:

Adult, Child, Infant, Senior, Student & Military are mapped 1:1 between the systems

Octo FAMILY and YOUTH are not used

Bókun Teenager and Group are currently returned as OCTO OTHER.

Contact

An Octo Contact is in Bókun a customer.

Full name: Bókun doesn't store full names, only first names & last names. When reading a booking through the Octo API, the first name + last name get joined by a space to become the full name: firstName + " " + lastName. When making a booking request where the first name or last name are provided, the fullName field is ignored. When no first & last name are provided, the fullName is split up at the last space into two parts and stored into firstName & lastName respectively.

Locales: Bókun can only store one locale / language per customer, so if multiple are supplied through Octo, only the first one gets stored and the other ones are ignored.