Booking Calendars

Booking Calendars are the platform's way of taking time-based bookings — appointments, room reservations, slot-based scheduling, classes, lessons, support sessions. Each calendar represents one bookable resource or service with its own availability rules and confirmation behaviour.

The feature handles all the awkward parts of time-based booking: enforcing one-booking-per-slot, respecting working hours and holidays, sending confirmation emails with .ics calendar attachments, dealing with time zones, and managing cancellations.

What you can build

Booking Calendars cover a wide range of use cases:

• Service appointments — haircut, dentist, mechanic, beauty salon, personal trainer.
• Resource reservations — meeting rooms, equipment, vehicles, lockers.
• Class / event registration — classes with capacity limits, training sessions, workshops.
• Customer support sessions — onboarding calls, training sessions, professional services.
• Medical and clinical appointments — doctor, dentist, physiotherapist, mental-health practitioner.
• Multi-resource booking — e.g. a trainer + a specific room, both needed for the booking to work.

Where they're managed

From the Architect Panel → Booking Calendars. Each calendar has its own availability rules, slot durations, capacity limits, and confirmation behaviour.

Anatomy of a Booking Calendar

Every calendar has three layers of configuration:

1. Resource / Service definition

Who or what is being booked. "Dr. Smith's Consultations", "Conference Room A", "Yoga Class — Tuesdays 6pm". Plus owner (the user who's booked) and any descriptive content shown on the booking page.

2. Availability rules

When can it be booked? Working hours per day of the week ("Mon-Fri 9am-5pm"). Date-specific exceptions ("closed every Friday in August"). Lead time ("can't book within 24 hours of now"). Booking window ("can book up to 6 months ahead").

3. Slot configuration

How long is each bookable slot (15 / 30 / 60 / 90 minutes)? Is there a buffer between slots (15 minutes for clean-up)? Can multiple people book the same slot (a class with capacity 12) or only one (a 1-on-1 appointment)?

Three real-world Booking Calendars

Example 1: Hair salon — Stylist Booking

One calendar per stylist. Slot duration: 60 minutes. Working hours: Mon/Tue/Thu/Fri 9-5, Wed 11-7 (late night). Buffer: 15 minutes between bookings for cleanup. Capacity: 1 (one customer per slot). Lead time: 4 hours minimum. Booking window: 6 weeks ahead.

Example 2: Office meeting room

One calendar per room. Slot duration: 30 minutes (allowing flexible meeting lengths). Working hours: Mon-Fri 8-18. No buffer. Capacity: 1 (room is fully booked when reserved). Lead time: none. Booking window: 90 days.

Example 3: Group yoga class

One calendar per class type. Slot duration: 60 minutes. Working hours: defined per scheduled class (e.g. Mon 6-7pm, Wed 7-8am, Sat 10-11am). Capacity: 12 (12 people can book each slot). Lead time: 1 hour. Booking window: 30 days. Each booking ties a person to the class — multiple people can book the same slot.

How users book

The booking experience for end users is a calendar grid showing available slots. Users pick a day, then pick a slot from the available list for that day. They fill in a quick form (name, email, any custom fields you've added) and confirm. The platform validates that the slot is still available (race-condition-safe), books it, and sends a confirmation.

What gets stored

Each booking creates a row in the calendar's bookings datastore with the booker's identity, the slot start/end times, any custom-field values, and a status (Confirmed / Cancelled / Completed / No Show). The row can be queried like any other datastore for reporting, reminders, or integration with other systems.

From the Architect Panel → Booking Calendars, click New. The configuration form opens with three logical sections: core settings, availability, and slot configuration.

Core settings

• Name — internal name and the default page heading. Be specific: "Dr. Smith's Consultations" rather than just "Doctor".
• Description — text shown on the booking page above the calendar. Use it to explain what's being booked, any preparation the booker should do, cancellation policy.
• Owner — the user or resource the calendar belongs to. For per-staff calendars, this is the staff member; for resource calendars, it's typically a service account.
• Slot Duration — how long each bookable slot is. Standard durations: 15, 30, 45, 60, 90 minutes. Custom durations are supported.
• Buffer between slots — optional gap inserted between adjacent bookings (e.g. 15 minutes for cleanup or travel time).
• Lead time — how far in advance bookings must be made. Useful for preventing last-minute bookings that the resource can't realistically accept.
• Booking window — how far ahead users can see slots. Limits future visibility (e.g. "can only see and book the next 6 weeks").
• Capacity per slot — usually 1 for 1-on-1 services, higher for classes or events.

Availability rules

Set working hours per day of the week. The standard pattern: enter a start time and end time per weekday, leaving days off the resource closes blank.

Then add exceptions:

• Closed dates — public holidays, training days, leave.
• Special opening — e.g. "Saturday opening for a sale weekend".
• Reduced hours — half-day closures or extended hours.

Each exception has a date (or date range) and either marks the day closed or overrides the working hours for that day.

Slot rendering

When a user views the calendar to book, the platform renders the available slots by computing:

• Take the working hours for the day.
• Generate slots based on slot duration + buffer.
• Subtract any already-booked slots (with capacity check).
• Subtract any slots within the lead-time window.
• Subtract any slots beyond the booking window.

What's left is shown as available. Slots in the past are never shown.

Custom fields on bookings

Beyond the default booking fields (name, email, slot, status), you can add custom fields to capture booker-specific information. Examples:

• Reason for appointment — text area where the booker describes what they need.
• Special requirements — accessibility needs, equipment needed.
• Number of attendees — for group bookings where capacity isn't 1.
• Phone number — for SMS reminders.

Custom fields are added to the calendar's bookings datastore via the standard Datastore Field admin.

Test before going live

Before pointing real customers at the booking page, run through it as a test user:

1. Open the booking URL.
2. Verify the days show up correctly (matching your working hours config).
3. Pick a slot and book.
4. Confirm the confirmation email arrives.
5. Verify the slot is now marked unavailable to other bookers.
6. Test the cancellation flow.

The calendar's available slots are the union of its working-hours rules minus any conflicts (existing bookings, blocked dates, holidays). Getting this right matters because it directly drives what end users see when they try to book.

Recurring availability

The base layer is default working hours per weekday. For each day of the week, pick:

• Open / closed.
• Opening time if open.
• Closing time.

Three real-world weekly availability patterns:

• 9-5 office hours: Mon-Fri 9-5, Sat-Sun closed.
• Retail-style late nights: Mon/Wed/Fri 9-5, Tue/Thu 9-7, Sat 10-3, Sun closed.
• Weekend services: Sat-Sun 9-5, Mon-Fri closed.

Date-specific overrides

On top of the recurring availability, configure date-specific exceptions:

• Holidays — closed on specific calendar dates.
• Special opening — e.g. Sunday opening for a sale.
• Reduced hours — half-day closure on specific dates.
• Per-resource exceptions — "Dr. Smith is on leave from 1-7 Oct".

Each exception is a row in the calendar's blackout-dates table. Add as many as you need; they're processed alongside the recurring rules when slots are computed.

Slot computation

When the platform renders the booking grid for a specific day, it:

1. Looks up the day's working hours (recurring config + any overrides).
2. Generates slot start times by walking from opening time, incrementing by slot duration + buffer.
3. For each potential slot, checks if it's already booked (counting capacity).
4. Excludes slots that fall within the lead-time window from now.
5. Excludes slots beyond the booking window.

The remaining slots are what the user sees as available.

Three real-world slot configurations

Example 1: 30-minute doctor's appointments

Slot duration: 30 mins. Buffer: 0. Working hours: 9-5. Result: 16 slots per day (9:00, 9:30, 10:00, ..., 4:30). Each slot is 30 minutes long, capacity 1.

Example 2: 60-minute massage with cleanup time

Slot duration: 60 mins. Buffer: 15 mins. Working hours: 10-7. Result: about 8 slots per day (10:00, 11:15, 12:30, 13:45, 15:00, 16:15, 17:30 — the last full slot ends at 18:30, fitting the 19:00 close). The buffer prevents bookings stacking back-to-back without recovery time.

Example 3: 90-minute group fitness class

Slot duration: 90 mins. Working hours: 7-8:30 morning class, 18-19:30 evening class (set via specific exceptions for the class days). Capacity: 12. Result: two slots per day, each able to take up to 12 bookings.

Multi-calendar conflicts

For environments with multiple related calendars (e.g. several staff members in the same role), you can configure conflict avoidance — a slot is only shown as available if it's free on all relevant calendars. This is useful for resource pools where any qualified team member can take the booking.

Time zones

By default, slots are shown in the calendar's configured time zone (typically the platform-wide setting). For customer-facing calendars where bookers are in many time zones, the platform can render slot times in the booker's local time zone via JavaScript.

When a booking is confirmed, the platform sends a confirmation email to the booker — and optionally to the calendar owner. This email is often the booker's only touchpoint between booking and arriving, so making it informative and well-branded matters.

What's included by default

The platform's default confirmation email includes:

• Date, time, duration of the booking.
• Calendar owner / resource details.
• Location address (if the calendar has one) or join link (for video meetings).
• Direct link to the booking detail page (where the user can later cancel or reschedule).
• Calendar attachment (.ics file) for adding to their personal calendar — works with Outlook, Google Calendar, Apple Calendar, and most other clients.
• Cancellation instructions.

Template choice

Pick the email template per booking calendar in its configuration. Different calendars can use different templates if you want distinct tone or branding per service.

Three real-world template patterns:

Pattern 1: Branded consumer-facing

Full HTML with logo, brand colours, friendly tone. Includes the booking details, prep instructions ("please arrive 5 minutes early"), and a button to add to calendar. Footer with policy links and contact info.

Pattern 2: Plain professional

Minimal HTML, body-text only. Date, time, location, what to bring. Suitable for B2B professional services where flashy branding isn't appropriate.

Pattern 3: Reminder-style follow-up

For longer-lead-time bookings (e.g. classes booked 2 months in advance), the initial confirmation gets a follow-up reminder closer to the date. Two templates: the initial "thanks, your booking is confirmed" and the reminder "your booking is tomorrow".

Merge tokens available

The template can reference any field on the booking record plus several platform-provided tokens:

• ##AMDATA_fieldname## — any field on the booking.
• ##CALENDARNAME## — the calendar's display name.
• ##CALENDAROWNER## — name of the owner.
• ##SLOTDATE##, ##SLOTTIME## — formatted date/time.
• ##CANCELURL## — direct cancellation link.
• ##RESCHEDULEURL## — direct reschedule link.
• ##ICSURL## — link to the .ics calendar attachment.

Reminder emails

Beyond the initial confirmation, set up reminder emails to fire closer to the booking. Configurable intervals (24 hours before, 1 hour before) trigger a separate email template. Useful for reducing no-show rates — a reminder the day before a booking dramatically reduces forgotten appointments.

Cancellation and reschedule

If the booker cancels via the cancellation link in the email, the slot is freed up and the calendar owner is notified. If they reschedule, the platform shows them available slots and confirms the new time with a fresh confirmation email plus a cancellation note for the original slot.

Tip: Always include the cancellation link prominently. Bookers who can't easily cancel are more likely to no-show — which is worse than a clean cancellation because the slot stays blocked. A visible cancellation link increases the rate of clean cancellations and reduces no-shows.