Last updated

Listing availability management

Reference documentation for listing availability management.

The listing availability management features of Flex allow providers to define when (and when not) their listings are available for booking. There are two different concepts related to availability management that can be used in combination or separately:

  • An availability plan can be defined for each listing. It comprises of general availability rules for each day of the week. For instance "available on Mondays and Thursdays", or "available on Tuesday, Wednesday and Friday from 9 AM to 6 PM".
  • An availability exception overrides the availability plan for a concrete period of time. For instance "Available on 2018-11-25 and 2018-11-26", "not available on 2018-11-30".

The availability plan and exceptions, together with booking information can be combined to determine if a particular time range is available for booking or not. For instance, the /timeslots/query API endpoint returns availability information for future dates, taking into account the listing's availability plan, exceptions and bookings. In addition, your transaction process can automatically prevent bookings for unavailable time ranges.

Seats

Both availability plans and availability exceptions use the concept of seats to define whether a particular time is available or not. Currently Flex allows the number of seats to be only 0 or 1, meaning unavailable and available for single booking, respectively. Each booking currently consumes exactly one seat.

Day-based availability management

Day-based availability works with both daily and nightly bookings. For instance, an availability plan can define that Mondays and Tuesdays are available for booking. For daily bookings this means that dates that are a Monday or a Tuesday can be booked. For nightly bookings, this means that nights Monday-Tuesday and Tuesday-Wednesday can be booked.

Interpretation of availability exceptions and bookings

For day-based availability plans, it is recommended to create availability exceptions with timestamps having 00:00:00 time in UTC.

Creating availability exceptions with arbitrary time is allowed, but such exceptions are subject to the following interpretation rules in the context of a listing with day-based availability plan:

  • if the availability exception covers only partially a given date in UTC time zone, the availability exception is interpreted as covering the entire date
  • if multiple availability exceptions cover partially a given UTC date, the minimum number of seats of all these availability exceptions is taken as the resulting number of available seats for that date, prior to taking any existing bookings into account.

If your transaction process uses time-based bookings, the bookings are also subject to the same interpretation rules.

Example 1:

An exception with start 2018-11-26T12:30:00.000+01 and end 2018-11-27T10:25:00.000+01 is interpreted as if it were from 2018-11-26T00:00:00.000Z to 2018-11-28T00:00:00.000Z

Example 2:

An exception with start 2018-11-26T00:30.000+01:00 and end 2018-11-27T00:15:00.000+01:00 is interpreted as if it were from 2018-11-25T00:00:00.000Z to 2018-11-27T00:00:00.000Z.

Example 3:

Given exception 1 from 2017-11-26T10:00:00.000Z to 2018-11-26T12:00:00.000Z with 1 seat and exception 2 from 2017-11-26T10:00:00.000Z to 2018-11-26T12:00:00.000Z with 0 seats, this is interpreted as if single exception existed from 2018-11-26T00:00:00.0Z to 2018-11-27T00:00:00.000Z with 0 seats.

Time-based availability management

Time-based availability can be used with time-based bookings. Time-based availability plans can specify one or more time intervals for each day of the week, and specify the time zone in which these times should be interpreted. For instance, with time-based availability it is possible to define that the listing is available on weekdays from 9 AM to 11AM and from 1 PM to 6 PM. More information on how to set a time-based availability plan for a listing can be found in the time-based bookings guide.

Interpretation of availability exceptions and bookings

For time-based plans, both availability exceptions and bookings are interpreted literally, i.e. covering the exact time intervals determined by their start and end times.

Booking display times

Booking display times are a handy tool for managing listing availability. You can use them by passing bookingDisplayStart and bookingDisplayEnd attributes when initiating a new transaction. This will set displayStart and displayEnd attributes correspondingly to the booking that is related to the initiated transaction. The display times are used alongside with the normal start and end attributes (defined by bookingStart and bookingEnd params in a transaction initiation request) of a booking and they can be used to present different start and end times to the customer than actully is booked. See the booking resource format for a full list of booking attributes.

Example:

A provider needs 10 minutes of preparation time before each booking. They can pass the following params regarding booking start when initiating a transaction:

bookingStart: "2018-04-20T12:20:00.000Z",
bookingDisplayStart: "2018-04-20T12:30:00.000Z"

The displayStart attribute will now indicate that the booking starts at 12:30 and this can be presented to the customer. However, the listing is booked already from 12:20, denoted by booking's start attribute. Now the listing is not available for other bookings 10 minutes before this booking starts. If another customer wishes to book this listing earlier, their booking will end at latest 10 minutes before this booking.

See the reference documentation for the following API endpoints for details: