Docs

Booking Module

Let customers book services against your availability rules via public APIs. Dashboard calendar included.

Overview

The Booking module provides a full scheduling system via REST APIs. Define services with duration, buffer time, capacity, and pricing. Set weekly availability rules with optional date-specific exceptions. Customers fetch available slots and create bookings through public endpoints — no authentication required on their end. All bookings appear in your dashboard calendar with CSV export.

API Endpoints

Create Services

Define your bookable services with duration, buffer time between appointments, group capacity, and pricing.

POST /v1/booking/services
Authorization: Bearer nk_live_...

{
  "names": { "en": "30-min Consultation", "de": "30-Min Beratung" },
  "durationMin": 30,
  "bufferMin": 10,
  "capacity": 1,
  "priceCents": 5000,
  "currency": "EUR"
}

Set Availability

Configure weekly rules by day-of-week (0 = Sunday, 6 = Saturday) with start and end times. You can set multiple time windows per day — e.g., morning and afternoon splits. Add date-specific exceptions for holidays or special hours.

POST /v1/booking/availability
Authorization: Bearer nk_live_...

{
  "rules": [
    { "day": 1, "start": "09:00", "end": "12:00" },
    { "day": 1, "start": "14:00", "end": "17:00" },
    { "day": 2, "start": "09:00", "end": "17:00" },
    { "day": 3, "start": "09:00", "end": "12:00" }
  ],
  "exceptions": {
    "2025-12-25": null,
    "2025-12-31": { "windows": [{ "start": "09:00", "end": "12:00" }] }
  }
}

Get Available Slots

Customers fetch available time slots for a specific date. The algorithm computes slots from your rules, service duration, buffer time, and existing bookings.

GET /v1/public/booking/services/{serviceId}/slots?date=2025-07-15

// Response:
{
  "slots": [
    { "startsAt": "2025-07-15T07:00:00Z", "endsAt": "2025-07-15T07:30:00Z" },
    { "startsAt": "2025-07-15T07:40:00Z", "endsAt": "2025-07-15T08:10:00Z" },
    { "startsAt": "2025-07-15T12:00:00Z", "endsAt": "2025-07-15T12:30:00Z" }
  ]
}

Create Bookings

Customers submit a booking with the service ID, chosen start time, and their contact details. The public endpoint handles validation and capacity checks.

POST /v1/public/booking/bookings
{
  "serviceId": "abc123",
  "startsAt": "2025-07-15T07:00:00Z",
  "customer": {
    "name": "Jane Doe",
    "email": "[email protected]"
  },
  "turnstileToken": "..."
}

// Response:
{
  "id": "...",
  "status": "confirmed",
  "startsAt": "2025-07-15T07:00:00Z",
  "endsAt": "2025-07-15T07:30:00Z"
}

Time Zones

Each tenant has a timezone field (defaults to UTC). All availability rules are interpreted in your tenant timezone. Slot timestamps are returned in UTC so customers across time zones book consistently. Display the slot time in the customer's local timezone on your frontend.

FAQ