Distribution / OTA

An OTA provides a way for guests to search & book, creates and manages its own reservations, collects payments and pays out commission to Administrations.

An OTA is usually responsible for the following actions:

  • Creating a channel in Booking Experts
  • Creating type mappings (Booking Experts type X corresponds to external resource Y)
  • Pushing the latest availability of categories
  • Pushing the latest prices of categories
  • Fetching new reservations and pushing updates to Booking Experts

This guide is applicable to Channel management as well.


Relevant permissions

An OTA will usually need the following permissions:

  • availability|read
  • channel::reservation|read
  • channel::customer|read
  • channel::booking|read
  • rentable_type|read
  • reservation|write
  • channel|write
  • internal_message|write

Relevant webhooks

An OTA will usually need the following webhooks:

  • rentable_type|reindexed
    Triggered when the availability or prices of a type have been changed. It is called reindexed because it is triggered when our Availability Search Index has been updated as well. This index can be queried using the GET availabilities endpoint.
    • Alternatively, for more fine-grained control you can use the events rentable_type|availability_updated and rentable_type|prices_updated instead.
  • rentable_type|updated
    Triggered when attributes of the type have changed.
    A special case is when a type becomes archived, which means it is not used anymore, but has not permanently been deleted because it is still associated to certain reservations. Therefore, when the attribute archived is true, the availability and prices of the type must be cleared.
  • rentable_type|deleted
    When a type is permanently deleted, the mapping can be removed and the availability and prices must be cleared.

Creating a channel

Channels in Booking Experts are used to track the origin of reservations. A channel can also store the pricing type used. We currently support 'simple prices' (night prices) and 'complex prices' (LOS prices).
When an organization subscribes to your App, it is possible to associate a channel to each administration of the organization you get access to. However, it is preferred that the App creates a channel instead.

To create a channel, you will need the channel|write permission. Please see the POST channels endpoint for more information. An example can be seen below.

{
  "data": {
    "type": "channel",
    "attributes": {
      "name": "TourOperator.com",
      "kind": "tour_operator",
      "available_currencies": ["EUR"]
    }
  }
}

Pushing availability and prices

Availability and prices for a type can be fetched 3 ways. The way to go is dependent on the information you need and the pricing type you use. You will need the availability|read permission for these endpoints.

👍

Our favourite method :

  • When using complex LOS prices, use the GET availabilities endpoint.
    Besides price and availability, this will also return the rent price, original price and discount price. It also returns the expected check-in and check-out time of reservations.
  • When using simple night prices, you can use the GET night prices endpoint. It returns the price and stock for each available date. This endpoint also supports the If-Modified-Since header.
  • When using complex LOS prices, you can also use the GET LOS prices endpoint. For each date, it returns a record with price and stock for each LOS. This endpoint also supports the If-Modified-Since header.

Currently, when receiving a rentable_type|reindexed event, you need to manually figure out which prices have changed if you only want to store differences in availability and prices.
This can easily be achieved by storing the last processed response and comparing this to the current response.


Pushing updates to Booking Experts

To create, update or cancel reservations, you can use the Channel Reservations endpoint. You will need the reservation|write permission to do this. More information on how to create or update reservations can be found in the Bookings and Reservations guide.


When things go wrong

Occasionally, problems may occur when keeping reservations in sync.
For example, a conflict may occur when a certain period has already been booked in Booking Experts. For these cases, it is possible to send an internal message to the administration.
You can use the POST internal_message endpoint. You will need the internal_message|write permission to do this.