The Bookings API from Klook — 5 operation(s) for bookings.
openapi: 3.1.0
info:
title: OCTO API Specification Availability Bookings API
version: '1.0'
contact:
email: sayhello@octo.travel
url: https://www.octo.travel/contact
name: OCTO Standards NP Inc
description: 'OCTO (Open Connectivity for Tours, Activities, and Attractions) is an open standard API specification for the in-destination experiences sector of the travel industry. The standard defines agreed-upon schemas, endpoints, and capabilities commonly needed when connecting platforms, resellers, OTAs, and other technologies in tours, activities, and attractions._
OCTO is open source. Available to anyone who wants to use it. You do not need to be a member to use this specification in your business.'
servers:
- url: https://api.example.com/octo
tags:
- externalDocs:
description: Docs
url: https://docs.octo.travel/octo-core/bookings
name: Bookings
paths:
/bookings:
post:
summary: Booking Reservation
tags:
- Bookings
operationId: post-bookings
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
x-examples:
example-1:
id: 36d2d844-121d-453c-b514-de027caaf27f
uuid: 3698539b-65c4-41e3-95b1-fa108fd024b2
testMode: false
resellerReference: 102-256952-3
supplierReference: 300SK9
status: CONFIRMED
utcCreatedAt: '2021-10-27T23:28:43Z'
utcUpdatedAt: '2021-10-27T23:28:45Z'
utcExpiresAt: null
utcRedeemedAt: null
utcConfirmedAt: '2021-10-27T23:28:45Z'
productId: 5379ce46-0620-42ce-b65c-70d6fc1c9ac2
examples: []
description: ''
title: ''
properties:
id:
type: string
example: bbbb6227-54fc-4c32-9ed7-dc3eb99966ea
description: A unique ID / UUID generated by the supplier system to identify the booking.
uuid:
type: string
format: uuid
example: 559aed3d-6d5b-4fe0-bfca-99f5e7218a56
description: A UUID you can set when generating the booking to use as an idempotency key.
testMode:
type: boolean
description: If `TRUE`, booking was created on test mode
resellerReference:
type:
- string
- 'null'
description: The reference set by the Reseller. A mandatory field for resellers to be set in the booking confirmation request.
supplierReference:
type:
- string
- 'null'
description: The Supplier's / booking platform reference.
status:
type: string
title: BookingStatus
x-stoplight:
id: 8igglzvoke69w
enum:
- ON_HOLD
- CONFIRMED
- EXPIRED
- CANCELLED
- REDEEMED
- PENDING
- REJECTED
example: CONFIRMED
description: 'The status of the booking, possible values are:
`ON_HOLD` The booking is pending confirmation, this is the default value when you first create the booking.
`EXPIRED` If the booking is not confirmed before the expiration hold expires, it goes into an expired state.
`CONFIRMED` Once the confirmation call is made the booking is ready to be used.
`CANCELLED` If the booking is cancelled.
`PENDING` If the booking is pending outside availability confirmation.
`REDEEMED` If the booking is already redeemed.'
examples:
- CONFIRMED
utcCreatedAt:
type: string
example: '2021-10-27T23:28:43Z'
description: An ISO8601 date time in UTC when the booking was created.
utcUpdatedAt:
type:
- string
- 'null'
example: '2021-10-27T23:28:43Z'
description: An ISO8601 date time in UTC when the booking was updated.
utcExpiresAt:
type:
- string
- 'null'
description: An ISO8601 date times in UTC for when this booking is due to expire if the status is `ON_HOLD`.
example: '2021-10-27T23:58:43Z'
utcRedeemedAt:
type:
- string
- 'null'
description: An ISO8601 date time in UTC at when the booking was redeemed.
utcConfirmedAt:
type:
- string
- 'null'
example: '2021-10-27T23:28:43Z'
description: An ISO8601 date time in UTC when the booking was confirmed.
productId:
type: string
example: 6b903d44-dc24-4ca4-ae71-6bde6c4f4854
description: The product ID that identifies the product in the booking system to make this reservation.
product:
type: object
x-examples:
example-1:
id: 28ca088b-bc7b-4746-ab06-5971f1ed5a5e
internalName: Edinburgh Hop-On Hop-Off Bus Tour
reference: null
locale: en
timeZone: Europe/London
allowFreesale: true
instantConfirmation: true
instantDelivery: true
availabilityRequired: false
examples:
- id: 6b903d44-dc24-4ca4-ae71-6bde6c4f4854
internalName: Amazon River Tour
reference: AMZN
locale: en-GB
timeZone: Europe/London
allowFreesale: true
instantConfirmation: true
instantDelivery: true
availabilityRequired: true
availabilityType: START_TIME
deliveryFormats:
- QRCODE
deliveryMethods:
- VOUCHER
redemptionMethod: DIGITAL
options:
- id: DEFAULT
default: true
internalName: Private Morning Tour
reference: VIP-MORN
availabilityLocalStartTimes:
- 09:00
cancellationCutoff: 1 hour
cancellationCutoffAmount: 1
cancellationCutoffUnit: hour
requiredContactFields:
- firstName
restrictions:
minUnits: 'null'
maxUnits: 10
units:
- id: adult_697e3ce8-1860-4cbf-80ad-95857df1f640
internalName: Adult(s)
reference: LR1-01-new
type: YOUTH
requiredContactFields:
- firstName
restrictions:
minAge: 3
maxAge: 17
idRequired: true
minQuantity: 2
maxQuantity: 7
paxCount: 1
accompaniedBy:
- adult_697e3ce8-1860-4cbf-80ad-95857df1f640
description: A bookable product listed by a supplier.
properties:
id:
type: string
example: 6b903d44-dc24-4ca4-ae71-6bde6c4f4854
description: The id used for checking for availability and creating bookings for the product. This MUST be unique within the scope of the Supplier.
internalName:
type: string
description: The name the supplier calls the product.
example: Amazon River Tour
reference:
type:
- 'null'
- string
description: An optional code this supplier might use to identify the product.
example: AMZN
locale:
type: string
example: en-GB
description: A language code indicating what language this product content is in. This MUST be a valid BCP 47 RFC 5646 RFC 4647 language tag.
timeZone:
type: string
example: Europe/London
description: The IANA TimeZone name this product is located in.
allowFreesale:
type: boolean
description: Whether a booking can be made for this product without having to query availability first.
instantConfirmation:
type: boolean
description: Whether bookings will be immediately confirmed when a sale is made, otherwise the supplier will later either accept or reject the booking. When `instantConfirmation` is set to false one should expect created bookings to first get into a `PENDING` state.
instantDelivery:
type: boolean
description: This indicates whether the Reseller can expect immediate delivery of the customer's tickets. If `false` then the Reseller MUST be able to delay delivery of the tickets to the customer.
availabilityRequired:
type: boolean
description: Whether an `availabilityId` is required when creating a booking. Without this the booking will be open-dated and not have a specified travel date.
availabilityType:
type: string
title: AvailabilityType
x-stoplight:
id: n70vwjh7kvmxk
enum:
- START_TIME
- OPENING_HOURS
description: 'What type of availability this product has, possible values are:
`START_TIME` if there are fixed departure times which you must pick one. Typical for day tours or activities.
`OPENING_HOURS` if you just select a date and can visit any time when the venue is open.'
example: START_TIME
examples:
- START_TIME
deliveryFormats:
type: array
description: 'An array of formats the API will deliver the tickets as. Possible values are:
`QRCODE` A code to be presented as a QR CODE barcode
`CODE128A` code to be presented as a CODE 128 barcode
`PDF_URL` A URL to a PDF file which contains all the ticket details'
items:
type: string
title: DeliveryFormat
x-stoplight:
id: xo5qi6jemvvhc
enum:
- PDF_URL
- QRCODE
description: 'The format for the delivery option possible values are:
`QRCODE` You should generate the QR Code yourself on a ticket.
`PDF_URL` Where you use the generated tickets as a PDF.'
example: QRCODE
examples:
- QRCODE
deliveryMethods:
type: array
description: 'How the formats described in `deliveryFormats` will be delivered in the booking response, possible values are:
`TICKET`: Individually per unit in the order (i.e. single ticket for each person)
`VOUCHER`: One ticket for the whole booking'
items:
type: string
title: DeliveryMethod
x-stoplight:
id: tdh9akr9neqhb
enum:
- VOUCHER
- TICKET
description: 'An array of delivery methods available for this booking. Possible values are:
`VOUCHER` The voucher object is populated which is a single ticket for the whole booking.
`TICKET` The ticket object is populated on each unit item which is a ticket for each individual person.
If `booking.deliveryMethods` contains both `TICKET` and `VOUCHER` then both those values will be set.'
examples:
- VOUCHER
redemptionMethod:
type: string
title: RedemptionMethod
x-stoplight:
id: jrrh8rbyzfuzm
enum:
- DIGITAL
- PRINT
- MANIFEST
description: 'How the voucher can be redeemed. Possible values are:
`MANIFEST` The guest name will be written down and they just need to show up
`DIGITAL` The tickets/voucher must be scanned but can be on mobile
`PRINT` The tickets/voucher must be printed and presented on arrival'
examples:
- DIGITAL
options:
type: array
description: An array of all options for this product. All products must have at least one option.
items:
type: object
x-examples:
example-1:
id: DEFAULT
default: true
internalName: DEFAULT
reference: null
availabilityLocalStartTimes:
- 00:00
cancellationCutoff: 1 hour
cancellationCutoffAmount: 1
cancellationCutoffUnit: hour
requiredContactFields: []
examples:
- id: DEFAULT
default: true
internalName: Private Morning Tour
reference: VIP-MORN
availabilityLocalStartTimes:
- 09:00
cancellationCutoff: 1 hour
cancellationCutoffAmount: 1
cancellationCutoffUnit: hour
requiredContactFields:
- firstName
restrictions:
minUnits: 'null'
maxUnits: 10
units:
- id: adult_697e3ce8-1860-4cbf-80ad-95857df1f640
internalName: Adult(s)
reference: LR1-01-new
type: YOUTH
requiredContactFields:
- firstName
restrictions:
minAge: 3
maxAge: 17
idRequired: true
minQuantity: 2
maxQuantity: 7
paxCount: 1
accompaniedBy:
- adult_697e3ce8-1860-4cbf-80ad-95857df1f640
description: Product options are subdivisions of the original product that will affect price and / or duration. Within the OCTo spec, every product must contain an option.
properties:
id:
type: string
example: DEFAULT
description: The id that identifies this option, it is only unique within the product.
default:
type: boolean
description: '`TRUE` identifies the option as default, and should therefore rendered and selected first'
internalName:
type: string
description: The name the supplier calls the option by.
example: Private Morning Tour
reference:
type:
- 'null'
- string
description: An optional code this supplier might use to identify the product.
example: VIP-MORN
availabilityLocalStartTimes:
type: array
description: This will be an array of all possible start times that can be returned during availability. For example an all day attraction may have a single value like `["00:00"]` whilst a tour with multiple departure times may have multiple:`["09:00", "14:00", "17:00"]`.
items:
type: string
default: 00:00
example: 09:00
cancellationCutoff:
type: string
example: 1 hour
description: This is how long before the tour the booking can be still be cancelled.
cancellationCutoffAmount:
type: integer
example: 1
description: The numeric amount for the cutoff.
cancellationCutoffUnit:
type: string
title: DurationUnit
x-stoplight:
id: etuhjhtharyrt
enum:
- hour
- minute
- day
example: hour
description: 'Time units used to determine duration. Three values are available: `hour`, `minute`, `day`.'
examples:
- hour
requiredContactFields:
type: array
description: An array of the contact fields required to confirm a booking. These just apply to the lead traveller on the booking and not for every ticket.
items:
type: string
title: ContactField
x-stoplight:
id: 5qud985l1i6ih
enum:
- firstName
- lastName
- emailAddress
- phoneNumber
- country
- notes
- locales
examples:
- firstName
description: ''
restrictions:
type: object
x-examples:
example-1:
minUnits: 0
maxUnits: 9
description: An object containing a fixed list of restrictions for booking the option.
examples:
- minUnits: null
maxUnits: 10
properties:
minUnits:
type:
- integer
- 'null'
example: 0
description: The minimum number of tickets that can be purchased in a single booking (null = 0).
maxUnits:
type:
- integer
- 'null'
example: 10
description: The maximum number of tickets that can be purchased in a single booking (null = unlimited).
required:
- minUnits
- maxUnits
units:
type: array
description: The list of ticket types (units) available for sale.
items:
type: object
x-examples:
example-1:
id: unit_c1709f42-297e-4f7e-bd6b-3e77d4622d8a
internalName: Adult
reference: null
type: ADULT
requiredContactFields: []
examples:
- id: adult_697e3ce8-1860-4cbf-80ad-95857df1f640
internalName: Adult(s)
reference: LR1-01-new
type: YOUTH
requiredContactFields:
- firstName
restrictions:
minAge: 3
maxAge: 17
idRequired: true
minQuantity: 2
maxQuantity: 7
paxCount: 1
accompaniedBy:
- adult_697e3ce8-1860-4cbf-80ad-95857df1f640
properties:
id:
type: string
description: This MUST be a unique identifier within the scope of the option.
example: adult_697e3ce8-1860-4cbf-80ad-95857df1f640
internalName:
type: string
example: Adult(s)
description: This should be a name to help with identifying the unit. It should NOT be shown to the customer.
reference:
type:
- 'null'
- string
description: This is an internal reference identifier that the Supplier wishes to use. It MAY be non-unique.
example: LR1-01-new
type:
type: string
title: UnitType
x-stoplight:
id: 9womjjbg9rhr7
enum:
- ADULT
- YOUTH
- CHILD
- INFANT
- FAMILY
- SENIOR
- STUDENT
- MILITARY
- OTHER
examples:
- ADULT
description: This is the base unit type for this unit definition. A value of TRAVELLER MUST only be used in replacement of `ADULT`, `CHILD`, `INFANT`, `YOUTH`, `STUDENT`, or `SENIOR`.
example: YOUTH
requiredContactFields:
type: array
description: This is the array of the contact information PER ticket that the supplier expects.
items:
type: string
title: ContactField
x-stoplight:
id: 5qud985l1i6ih
enum:
- firstName
- lastName
- emailAddress
- phoneNumber
- country
- notes
- locales
examples:
- firstName
description: ''
restrictions:
type: object
x-examples:
example-1:
minAge: 0
maxAge: 100
idRequired: false
minQuantity: 1
maxQuantity: null
paxCount: 4
accompaniedBy: []
description: unit restrictions
examples:
- minAge: 3
maxAge: 17
idRequired: true
minQuantity: 2
maxQuantity: 7
paxCount: 1
accompaniedBy:
- adult_697e3ce8-1860-4cbf-80ad-95857df1f640
title: UnitRestrictions
properties:
minAge:
type: integer
example: 3
description: This is the minumum age this unit can be sold to
maxAge:
type: integer
example: 17
description: This is the maximum age this unit can be sold to
idRequired:
type: boolean
description: This is whether a form of identification will be required at redemption point (eg. student card)
minQuantity:
type:
- integer
- 'null'
example: 2
description: This is if there is a minimum amount of units to be chosen for purchase (eg. 2)
maxQuantity:
type:
- 'null'
- integer
example: 7
description: This is if there is a maximum amount of units to be chosen for purchase (eg. 7)
paxCount:
type: integer
description: This is the amount of people each unit counts as (eg. family == 4pax)
example: 1
accompaniedBy:
type: array
description: This is if the unit needs to be accompanied by another unit (eg. Infant with Adult)
items:
type: string
example: adult_697e3ce8-1860-4cbf-80ad-95857df1f640
required:
- minAge
- maxAge
- idRequired
- minQuantity
- maxQuantity
- paxCount
- accompaniedBy
required:
- id
- internalName
- type
- requiredContactFields
- restrictions
description: ''
required:
- id
- default
- internalName
- reference
- availabilityLocalStartTimes
- cancellationCutoff
- cancellationCutoffAmount
- cancellationCutoffUnit
- requiredContactFields
- restrictions
- units
required:
- id
- internalName
- reference
- locale
- allowFreesale
- instantConfirmation
- instantDelivery
- availabilityRequired
- availabilityType
- deliveryFormats
- deliveryMethods
- redemptionMethod
- options
optionId:
type: string
example: DEFAULT
description: The product ID that identifies the product option in the booking system to make this reservation.
option:
type: object
x-examples:
example-1:
id: DEFAULT
default: true
# --- truncated at 32 KB (636 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/klook/refs/heads/main/openapi/klook-bookings-api-openapi.yml