Reservation available slots

Computes the bookable time slots of a service on one date. Use it before creating a reservation: send the chosen slot's start_datetime. It is read-only and calculated on every request; nothing is stored.

Endpoints

MethodPathDescription
GET/reservation-available-slotsGet available slots

The availability object

json

Fields

FieldTypeDescription
availablebooleantrue when at least one slot can be booked.
reasonstringOnly when the whole day is unavailable. One of Service is not active, Cannot book past dates, Cannot book more than N days in advance, No availability configured for this day, This date is blocked, All resources are blocked on this date.
datestringRequested date, YYYY-MM-DD. Absent when reason is returned.
service_idintegerRequested service. Absent when reason is returned.
resource_idintegerRequested resource, only when resource_id was sent.
duration_minutesintegerService duration.
max_party_sizeintegerService maximum party size.
slot_capacityintegerReservations allowed per slot.
timezonestringService timezone. Slot times are wall-clock times in this zone.
slotsarraySlots of the day in time order (empty when reason is returned).
slots[].timestringStart time, HH:mm.
slots[].start_datetimestringStart, in the format expected by POST /reservations (wall-clock time with Z suffix, not UTC).
slots[].end_datetimestringStart + duration_minutes.
slots[].availablebooleantrue when available_spots ≥ 1. Full slots are still listed with false.
slots[].available_spotsintegerslot_capacity minus booked, never below 0.
slots[].total_capacityintegerSame as slot_capacity.
slots[].bookedintegerCapacity already used in the slot (reservations, or people when capacity_unit is people).
slots[].start_time, slots[].end_timestringStart and end, HH:mm.
slots[].remaining_capacityintegerCapacity still free in the slot: bookings, or seats when the service capacity_unit is people.
slots[].available_resource_idsarray of integersResources free for the whole slot.
slots[].unavailable_reasonstringOnly on unavailable slots: full, resource_unavailable, calendar_busy, calendar_error or outside_hours.
duration_mode, duration_options, capacity_unit, min_party_size, party_sizeThe service settings used and the requested party size.
calendar_errorsarrayConnected calendars that could not be read. Their slots are not offered until the calendar works again. Each item: link_id, scope, service_id, resource_id, source_type, calendar_integration_id, label, message.

How slots are calculated

  1. Hours. If the service has no linked resources, the day runs 08:00–18:00. Otherwise each linked resource's active weekly blocks for that weekday are used (only resource_id's when it is sent).
  2. Exceptions. An organization-wide blocked exception closes the day; a resource blocked exception removes that resource's hours; a resource special_hours exception replaces them with its start_time–end_time.
  3. Slots. Starting at each block's start, a slot every slot_interval minutes while start + duration_minutes fits before the block end. Duplicate start times across resources are merged.
  4. Booking window. Slots starting before now + min_advance_hours or after max_advance_days (service timezone) are dropped. buffer_before_minutes / buffer_after_minutes must also be free.
  5. Occupancy. Overlapping pending, confirmed and unexpired awaiting_payment reservations count against slot_capacity (one each, or their party_size when capacity_unit is people) and against each resource's capacity. A resource is busy when a reservation of any service assigned to it overlaps. max_daily_bookings closes the day when reached.
  6. Connected calendars. Busy time of calendars linked to the organization, the service or a resource (Google, Outlook, or open CRM activities of a member) removes the slots it overlaps. A calendar that cannot be read blocks its slots and is listed in calendar_errors.

Weekly availability breaks and valid_from/valid_until are honored. Creating a reservation runs the same checks again at booking time, so a slot taken in between is rejected with 400.

Related

Report an issue with this documentation

Please log in to report issues with our documentation.