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
| Method | Path | Description |
|---|---|---|
GET | /reservation-available-slots | Get available slots |
The availability object
json
Fields
| Field | Type | Description |
|---|---|---|
available | boolean | true when at least one slot can be booked. |
reason | string | Only 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. |
date | string | Requested date, YYYY-MM-DD. Absent when reason is returned. |
service_id | integer | Requested service. Absent when reason is returned. |
resource_id | integer | Requested resource, only when resource_id was sent. |
duration_minutes | integer | Service duration. |
max_party_size | integer | Service maximum party size. |
slot_capacity | integer | Reservations allowed per slot. |
timezone | string | Service timezone. Slot times are wall-clock times in this zone. |
slots | array | Slots of the day in time order (empty when reason is returned). |
slots[].time | string | Start time, HH:mm. |
slots[].start_datetime | string | Start, in the format expected by POST /reservations (wall-clock time with Z suffix, not UTC). |
slots[].end_datetime | string | Start + duration_minutes. |
slots[].available | boolean | true when available_spots ≥ 1. Full slots are still listed with false. |
slots[].available_spots | integer | slot_capacity minus booked, never below 0. |
slots[].total_capacity | integer | Same as slot_capacity. |
slots[].booked | integer | Capacity already used in the slot (reservations, or people when capacity_unit is people). |
slots[].start_time, slots[].end_time | string | Start and end, HH:mm. |
slots[].remaining_capacity | integer | Capacity still free in the slot: bookings, or seats when the service capacity_unit is people. |
slots[].available_resource_ids | array of integers | Resources free for the whole slot. |
slots[].unavailable_reason | string | Only on unavailable slots: full, resource_unavailable, calendar_busy, calendar_error or outside_hours. |
duration_mode, duration_options, capacity_unit, min_party_size, party_size | The service settings used and the requested party size. | |
calendar_errors | array | Connected 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
- 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). - Exceptions. An organization-wide
blockedexception closes the day; a resourceblockedexception removes that resource's hours; a resourcespecial_hoursexception replaces them with itsstart_time–end_time. - Slots. Starting at each block's start, a slot every
slot_intervalminutes while start +duration_minutesfits before the block end. Duplicate start times across resources are merged. - Booking window. Slots starting before now +
min_advance_hoursor aftermax_advance_days(service timezone) are dropped.buffer_before_minutes/buffer_after_minutesmust also be free. - Occupancy. Overlapping
pending,confirmedand unexpiredawaiting_paymentreservations count againstslot_capacity(one each, or theirparty_sizewhencapacity_unitispeople) and against each resource'scapacity. A resource is busy when a reservation of any service assigned to it overlaps.max_daily_bookingscloses the day when reached. - 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.