Skip to main content

Availability rules

As the name suggests, availability rules are used to define the availability of a service. They are used to define the time slots in which the service can be booked.

{
  // Duración del evento
  "duration": "string",
  // Frecuencia de inicio
  "step": "string",
  // Horarios
  "repeatingAvailability": {
    "timeZone": "string",
    "weekly": {
      "[DAY_OF_THE_WEEK]": [
        {
          "start": "string",
          "end": "string"
        }
      ]
    }
  },
  // Máximo de reservas concurrentes
  "maxConcurrentBookings": 0,
  // Antelación mínima de reserva
  "minBookingNotice": "string",
  // Antelación máxima de reserva
  "maxBookingNotice": "string",
  // Margen de tiempo después de la reserva
  "beforeBuffer": "string",
  // Margen de tiempo antes de la reserva
  "afterBuffer": "string",
  // Permite conectar calendarios externos y crear o comprobar la disponibilidad en ellos...
  "thirdPartyCalendars": {},
  // Permite configurar manualmente intervalos donde no se ofrecerá disponibilidad...
  "busyIntervals": [],
}

Basic rules​

Duration (duration)​

The duration field allows you to configure the duration of the event in hours and minutes. The duration is specified in standard ISO9601 format

Examples:

  • An interval of one hour: PT1H
  • An interval of one hour and 30 minutes: PT1H30M
  • An interval of 20 minutes: PT20M

Start frequency (step)​

Regardless of the duration of the services, we may want them to start at a certain time.

The step field allows you to configure how often time slots are generated in which the event can be booked.

Example: Duration 1h Step 30m​

{
    duration: 'PT1H',
    step: 'PT30M',
}

If we create an event of 1h with a step of 30m the following slots will be generated:

  • 09:00 - 10:00
  • 09:30 - 10:30
  • 10:00 - 11:00
  • 10:30 - 11:30

Example: Duration 1h Step 20m​

{
    duration: 'PT1H',
    step: 'PT20M',
}

If we create an event of 1h with a step of 20m the following slots will be generated:

  • 09:00 - 10:00
  • 09:20 - 10:20
  • 09:40 - 10:40
  • 10:00 - 11:00
  • 10:20 - 11:20
  • 10:40 - 11:40

Schedule (repeatingAvailability)​

note

The repeatingAvailability field will be replaced by the schedule field in future versions of the API.

Allows you to configure the hours in which slots will be generated regularly.

The schedule object consists of two main properties, the time zone and the weekly periodicity.

Example: Working days from 09:00 to 18:00​

{
  timeZone: 'Europe/Madrid',
    weekly: {
        SUNDAY: [],
        MONDAY: [{ start: '09:00', end: '18:00' }],
        TUESDAY: [{ start: '09:00', end: '18:00' }],
        WEDNESDAY: [{ start: '09:00', end: '18:00' }],
        THURSDAY: [{ start: '09:00', end: '18:00' }],
        FRIDAY: [{ start: '09:00', end: '18:00' }],
        SATURDAY: [],
    }
}

To specify breaks, for example the corresponding to lunch time, it is enough to add another interval to the corresponding day.

Example: Working days from 09:00 to 14:00 and from 16:00 to 18:00​

{
  timeZone: 'Europe/Madrid',
    weekly: {
        SUNDAY: [],
        MONDAY: [{ start: '09:00', end: '14:00' }, { start: '16:00', end: '18:00' }],
        TUESDAY: [{ start: '09:00', end: '14:00' }, { start: '16:00', end: '18:00' }],
        WEDNESDAY: [{ start: '09:00', end: '14:00' }, { start: '16:00', end: '18:00' }],
        THURSDAY: [{ start: '09:00', end: '14:00' }, { start: '16:00', end: '18:00' }],
        FRIDAY: [{ start: '09:00', end: '14:00' }, { start: '16:00', end: '18:00' }],
        SATURDAY: [],
    }
}

Advanced rules​

Buffers between bookings​

Sometimes we want to block a time span before and after the events. An example is a doctor who wants to have 10 minutes before each appointment to read the patient's data calmly or a beauty clinic that has to disinfect the cabins after each session.

  • beforeBuffer: Allows you to specify a time margin before the events in duration format.
  • afterBuffer Allows you to specify this time margin after the events in duration format.

Example: A service that has to have 10 minutes before and 20 minutes after each appointment.​

{
  // 10 minutes before
  beforeBuffer: "PT10M",
  // 20 minutes after.
  afterBuffer: "PT20M",
}

Example: A service that has to have 10 minutes before and 20 minutes after each appointment.​

{
  // 10 minutes before
  beforeBuffer: "PT10M",
  // 20 minutes after.
  afterBuffer: "PT20M",
}

Maximum and minimun booking notice​

This option allows you to restrict how far in advance a service can be booked.

Example: A service that has to be booked 24h in advance and maximum in the next 7 days​

{
  // The service has to be booked 24h in advance
  minBookingNotice: "PT24H",
  // The service has to be booked maximum in the next 7 days
  maxBookingNotice: "PT7D",
}

When this option is enabled, bookings outside the specified time range will not be allowed. This is useful to avoid last minute bookings or too far in advance.

Max number of bookings per slot​

Allows you to configure the maximum number of bookings that can be made in each available slot.

Example: A psychologist who can only see one patient at a time:​

{
  // 1 concurrent booking per slot is allowed.
  "maxConcurrentBookings": 1,
}

Example: A spinning class with 10 bikes:​

{
  // 10 concurrent bookings per slot are allowed.
  "maxConcurrentBookings": 10,
}

Limit of bookings per time unit. (maxBookingsPerTimeUnit)​

Permite configurar el número máximo de reservas que se pueden hacer en un periodo determinado de tiempo. Contiene un array de límites formado por los siguientes campos:

Allows to configure the maximum number of bookings that can be made in a given time period. It contains an array of limits formed by the following fields:

En:

  • perHour: Maximum number of bookings per hour.
  • perDay: Maximum number of bookings per day.
  • perWeek: Maximum number of bookings per week.
  • perMonth: Maximum number of bookings per month.
Important

It is considered that an event belongs to the period if its start date or its end date is within the period. Time periods are calculated according to the time zone specified in the TimeZone field of the service. If this field is not configured, UTC is used.

Example: A service that allows a maximum of 10 bookings per hour:​

maxBookingsPerTimeUnit: {
  byHour: 10,
}

### Example: Maximum 3 bookings per day, 15 per week or 30 per month.

{
 maxBookingsPerTimeUnit: {
    byDay: 3,
    byWeek: 15,
    byMonth: 30,
 }
}

Units​

In certain types of bookings the maxConcurrentBookings field is not enough if we want to represent situations where in each booking a variable number of bookable objects can be specified.

Example: A show that has 100 seats and for each reservation a minimum of 1 seat and a maximum of 5 can be reserved:​

{
  "availableUnits": 20,
  "minUnitsPerBooking": 5,
  "maxUnitsPerBooking": 20,
}