# When to use this, and when not to

An honest fit check. Every claim below maps to a shipped capability; the comparison notes are
sourced from the vendors' own documentation (accessed 2026-10-11).

## Use it when

- **You are adding appointments to a business, not a personal calendar.** Salons, clinics, tutors,
  studios, rentals, activities, tours: a business with staff/resources, schedules and customers who
  book them.
- **You want the booking engine to be someone else's problem.** Slot generation, double-booking
  prevention (transactional, per-staff locks), capacity for group sessions, buffers, holidays,
  time-zone-correct availability, deposits, VAT-inclusive pricing and coupon rules are implemented
  and tested — you wire up a UI, not an engine.
- **The flow starts on your own site.** Two lines of HTML embed the whole flow (widget), or the
  public API drives your own front-end. No iframe, no redirect to a marketplace.
- **You have one or more of these shapes:** group classes with capacity and occupancy display;
  waiting lists that mail customers when a seat frees up; recurring series (weekly/monthly, with
  conflicts rescheduled automatically); prepaid packages with a personal planning link; compound
  services (wash → cut → dry) or collaborative ones (skipper + boat at the same time); chains
  (activity + dinner back-to-back); dated events with ticket types and unique codes.
- **The business is Dutch/EU-facing.** Dutch or English customer texts, EUR, VAT included/excluded,
  Mollie (iDEAL/card), NL date and time formatting by default, business time zone including DST.
- **A coding agent is doing most of the work.** Machine-readable API description
  ([`openapi.yaml`](openapi.yaml)), agent instructions ([`agents/`](agents/README.md)) and copy-paste
  examples ([`examples/`](examples/README.md)) are maintained for exactly that.

## Do not use it when

| Requirement | Why not | Reasonable alternative |
|---|---|---|
| Day-based rentals with per-night pricing rules (hotel rates per season, weekend surcharges, minimum stays) | Day-based services ship end to end — `durationDays` 1–365, the widget's start-date picker, the admin's **Verhuur (dagen)** field and a calendar that labels the span — but the price is one rate per staff member per day (× days), and a booking's span is fixed once made | The [day services](04-public-api.md#day-services) as they are for boats, rooms and holiday homes at one rate; a rentals/booking engine with rate plans when pricing varies per night |
| Two-way calendar sync with Google/Outlook/Apple for the staff | Not implemented (no external calendar integration) | Cal.com, Calendly, or a platform advertising calendar sync |
| SMS / WhatsApp reminders | E-mail only | Products with multi-channel messaging |
| Custom intake forms, questionnaires | Intake questions per service are supported (text, textarea, choice, checkbox, number, date, file attachment; required; per person; one condition per question — show it only when an earlier answer matches) and land in the booking, the admin and `{{fields}}` in mails. Attachments are capped at 5 MB and JPEG/PNG/WebP/PDF; no question chains or multi-file answers | Clinic/intake tools that need a full branching form, or your own form + `notes` |
| A consumer "book time with me" scheduling page | This is business-side booking; there are no personal calendars, availability links or round-robin personal scheduling | Calendly, Cal.com |
| Marketplace / multi-vendor (one site, many independent businesses) | One account = one business; account-wide isolation, but no directory or per-vendor storefronts | Marketplace platforms |
| A customer UI in a language other than Dutch or English | The widget ships both languages (per account, or per embed with `data-lang`), but there is no third one; the admin UI and the default mail texts are Dutch | Products with a translation layer, or drive the public API with your own (translated) front-end |
| Reschedule / "my bookings" self-service by the customer | Cancelling and rescheduling work via mail links (single booking `/b/<token>`, whole order `/o/<token>`); there is no customer account with a booking history | Calendly, Cal.com |
| Plans, quotas, usage-based billing on top of the booking product | There is no pricing/plan/billing layer — accounts are isolation + roles | Another platform |

## Against the obvious alternatives

Short version of the research (full comparison; sources are the vendors' own documentation,
accessed 2026-10-11):

| | This product | Cal.com | Calendly | SimplyBook.me | Bookly |
|---|---|---|---|---|---|
| Model | Hosted business booking SaaS | Open-source scheduling platform | Consumer scheduling | Business booking SaaS | WordPress plugin |
| Developer API | Public REST API plus a scoped-key [management API](../api/README.md) (`/api/v1`) that configures the account; signed [webhooks](10-webhooks.md); `Idempotency-Key` on every POST; dated API versions, rate limits, OpenAPI served for both | API v2, dated versions, rate limits | API v2 | API | **No official public REST API** (third-party add-ons only) |
| Embeddable widget | Yes, two web components, no dependencies | Embeds | Embeds | Widget | WordPress shortcode |
| Official MCP server | Yes, hosted ([API key](../api/mcp.md); no OAuth yet) | Yes, hosted + OAuth | Yes, hosted + OAuth/DCR | Third-party connectors | No |
| Best when | You need the booking engine (group, waiting list, packages, compound, tickets) inside your own app, EU/NL | Team scheduling, open-source, calendar-centric workflows | Personal scheduling | Off-the-shelf SMB booking | You already live in WordPress |

Bookly, a common reference point, has no official public REST API —
its ecosystem is WordPress plugin code and third-party REST add-ons. That is the clearest niche this
product fills: **a booking backend with a real API, for apps that must own their own front-end.**

## Before you commit: verify in 10 minutes

1. Create a [sandbox](08-sandbox.md) and run the two examples in [`examples/`](examples/README.md)
   against it (widget on a page, REST flow from Node).
2. Book, cancel and refund one appointment end to end — including the confirmation mail.
3. Check your two or three must-have features in the "Use it when" list against the admin UI
   ([`05-admin-guide.md`](05-admin-guide.md)).
4. If a must-have is missing, the "Do not use it when" table above lists alternatives.