# nisebookings

A hosted booking service for businesses: appointments, group bookings, recurring series, packages, waiting
lists and event tickets. It ships three surfaces:

| Surface | What it is | For |
|---|---|---|
| **Embeddable widget** | two dependency-free web components you paste into any site | any website, WordPress |
| **Public REST API** | the same engine without UI, one public key per business | custom front-ends, apps, agents |
| **Admin back office** | calendar, appointments, catalogue, payments, mail templates | the business |

The engine is strict where it matters: slots are re-checked and written transactionally, capacity can
never be exceeded, prices are always recomputed server-side, and all time is anchored to the business's
time zone.

## Start here

| Your task | Read |
|---|---|
| Decide whether this fits (and when not to use it) | [When to use it](09-when-to-use.md) |
| Test against a throwaway sandbox, no sign-up | [Sandbox](08-sandbox.md) |
| Put bookings on a website in 5 minutes | [Quickstart](01-quickstart.md) |
| Understand services, slots, capacity, money, time | [Concepts](02-concepts.md) |
| Configure the widget (attributes, flows, styling) | [Widget reference](03-widget-reference.md) |
| Build a custom front-end on the API | [Public API](04-public-api.md) · [openapi.yaml](openapi.yaml) · [verified examples](examples/README.md) |
| Integrate into a Next.js app | [Next.js](11-nextjs.md) · [runnable example](examples/nextjs/README.md) |
| Configure your account from code (no admin UI) | [Management API](../api/README.md) · [openapi.yaml](../api/openapi.yaml) |
| Let Claude Code, Codex, Cursor or VS Code operate your account | [MCP server](../api/mcp.md) |
| Get notified of bookings, cancellations, tickets and payments | [Webhooks](10-webhooks.md) |
| Use the back office | [Admin guide](05-admin-guide.md) |
| Change e-mail templates | [Notifications](06-notifications.md) |
| Know what data is stored and who can see it | [Data and privacy](07-data-and-privacy.md) |
| Feed a coding agent | [Agent instruction files](agents/README.md) |

## 5-minute integration

```html
<script src="https://app.nisebookings.com/widget.js" defer></script>
<nise-booking data-key="<your public key>"></nise-booking>
```

The customer gets service → time → details → payment → confirmation, in a shadow-DOM element that
inherits your page's font and is themed with CSS custom properties. Event tickets:
`<nise-events data-key="…">`. WordPress: paste the same two lines into a **Custom HTML** block.

## Headless integration

```js
const API = 'https://app.nisebookings.com/api/public/<your public key>';

const { tenant, services } = await (await fetch(`${API}/services`)).json();
const { days } = await (await fetch(`${API}/slots?service=${id}&from=2026-10-14&days=7`)).json();
const res = await fetch(`${API}/bookings`, {
  method: 'POST', headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    items: [{ service: id, staff: days[0].slots[0].staffId, start: days[0].slots[0].start, persons: 1 }],
    name: 'Ada Jansen', email: 'ada@example.com', gateway: 'local',
  }),
});
```

Send back the exact `start` you were given; handle `409 slot_unavailable` by re-fetching slots. Add an
`Idempotency-Key` header so a retry after a timeout never books twice.

## The five things to know

1. **Account = public key.** One key identifies the business on every public call. Nothing else is
   needed to embed or book.
2. **One order = one payment.** A cart, a chain, a repeated series or the parts of a compound service
   are all one checkout, with one payment and one order token.
3. **The client never decides.** Prices, staff, extras, capacity and slot availability are recomputed
   server-side inside a transaction with per-staff locks. The only thing the client must get right is
   sending back the `start` (and `staffId`) it received.
4. **Time is UTC on the wire, business-local in the UI.** Slot `start` values are ISO UTC; `from`/`until`
   are business-local dates; schedules, holidays and reminders use the business time zone.
5. **Timed work runs on its own.** Reminders, mail delivery, payment expiry, waiting-list offers and
   automatic status changes are processed by the service about once a minute; there is nothing to
   schedule on your side.

## For AI agents and coding agents

- [`agents/`](agents/README.md) — drop-in instruction files: `AGENTS.md` (Codex, Cursor, Copilot
  coding agent, VS Code, …), a Claude Code skill, and a Copilot instructions file. Copy one into the
  project that integrates this service.
- [`08-sandbox.md`](08-sandbox.md) — `POST /api/sandbox` returns a 24-hour test account with a public
  key and an all-scopes API key; no mail is delivered (read it via `GET /api/v1/outbox`), payments
  are fake. Verify your integration there before touching your real account.
- [`10-webhooks.md`](10-webhooks.md) — signed event messages (Standard Webhooks) to your backend for
  bookings, tickets and payments, with retries and a deliveries log; a dependency-free verifier.
- [`examples/`](examples/README.md) — three smallest-possible integrations; all run against a sandbox
  key, including a full Next.js app (widget and own UI) with every page explained in
  [`11-nextjs.md`](11-nextjs.md).
- [`llms.txt`](llms.txt) — this documentation as an index, per the llmstxt.org convention.
- [`llms-full.txt`](llms-full.txt) — every guide page concatenated into one file.
- [`openapi.yaml`](openapi.yaml) · [`openapi.json`](openapi.json) — machine-readable description of
  the whole public API (OpenAPI 3.1), in YAML and JSON.

When implementing a booking feature: start at [Quickstart](01-quickstart.md), fall back to the
[Public API](04-public-api.md) for anything the widget does not expose, and treat
[Concepts](02-concepts.md) as the source of truth for slot, capacity and pricing semantics. The
[Data and privacy](07-data-and-privacy.md) page explains what is stored, how accounts are isolated
and what is reachable from outside.

## What this service is not (yet)

- The [management API](../api/README.md) and the [MCP server](../api/mcp.md) cover what the admin does
  except creating real accounts (a 24-hour [sandbox](08-sandbox.md) can be created with one call) and
  the dashboard statistics. The MCP server takes API keys only (no OAuth yet).
- No customer accounts or "my bookings" area; bookings are managed through magic links: cancel a
  single booking (`/b/<token>`) or a whole order (`/o/<token>`), reschedule a single booking on
  `/b/<token>` or with `POST bookings/{token}/reschedule`.
- No SMS/WhatsApp and no external calendar sync.
- Admin UI is Dutch-only; the widget's text is Dutch **and English** (`data-lang`, or the account's language in Instellingen → Algemeen).
- No plans, quotas or billing layer — accounts are isolation + roles.

[`09-when-to-use.md`](09-when-to-use.md) turns this into a decision table with alternatives.
# Quickstart — add bookings to a site

The fastest path: get a public key, paste two lines of HTML, done. Every route below is a live
integration path; pick one.

| You want | Path | Time |
|---|---|---|
| Bookings on a normal website | [Widget](#path-a-widget-on-any-website) | minutes |
| Bookings on a WordPress site | [WordPress](#path-b-wordpress) | minutes |
| Your own UI / headless | [Public API](#path-c-your-own-front-end) | hours |
| Ticket sales for an event | [Events widget](#booking-events-instead-of-appointments) | minutes |
| Just test, no account yet | [Sandbox](08-sandbox.md): `curl -X POST https://app.nisebookings.com/api/sandbox` | seconds |

## Get a key

1. Create an account and complete the onboarding: **Bedrijfsnaam**, **Webadres** (a slug) and
   **Tijdzone**. This creates your account and makes you owner.
2. Add what can be booked: **Medewerkers** (staff/resources, each with a weekly schedule) and
   **Diensten** (services, and which staff perform them).
3. Copy the **Publieke sleutel** from **Instellingen → Insluiten**. That key is the only credential the
   browser-facing side needs.

Optional but recommended before going live: **Instellingen → Bedrijf en e-mail** (sender name,
reply-to), **Instellingen → Betalingen** (VAT, deposit, Mollie key), **Instellingen → Insluiten →
Toegestane websites** (restrict who may embed your widget).

### Let an agent configure your account

Everything above can also be done from code: **Instellingen → API** creates a key with scopes, and the
[management API](../api/README.md) then builds the whole catalogue — categories, services, staff,
per-staff prices, the working week, opening hours and holidays. Nothing to click.

```bash
export API=https://app.nisebookings.com/api/v1 KEY=nk_…
curl -s -H "Authorization: Bearer $KEY" $API/me
curl -s -H "Authorization: Bearer $KEY" -X POST $API/services \
  -d '{"title":"Knippen","duration":30,"price":25,"visibility":"public"}'
```

The quickstart in [`../api/README.md`](../api/README.md) walks an empty account to a real booking, and
the [OpenAPI spec](../api/openapi.yaml) covers every endpoint.

Prefer to ask in plain language? The same key connects your coding agent to the hosted
[MCP server](../api/mcp.md):

```bash
claude mcp add --transport http nise-booking https://app.nisebookings.com/api/mcp \
  --header "Authorization: Bearer $KEY"
```

## Path A: widget on any website

```html
<script src="https://app.nisebookings.com/widget.js" defer></script>
<nise-booking data-key="<your public key>"></nise-booking>
```

That is the whole integration. The element renders the full flow — service, time, details, payment —
inside a shadow DOM, styled with the page's font. Optional attributes:

```html
<nise-booking
  data-key="…"
  data-api="https://app.nisebookings.com"   <!-- needed only when widget.js is hosted elsewhere -->
  data-service="<service id>"              <!-- preselect a service -->
  data-staff="<staff id|any>"              <!-- preselect a staff member -->
  data-lang="nl|en"                        <!-- widget language; default: the account's -->
></nise-booking>
```

Details, styling tokens and limitations: [`03-widget-reference.md`](03-widget-reference.md).

## Path B: WordPress

No plugin needed; this works on any WordPress site where you can add HTML.

1. Edit the page, add a **Custom HTML** block and paste the two lines from Path A (with your public
   key). Optional attributes such as `data-service` and `data-staff` work the same way.
2. Add the WordPress site to **Toegestane websites** in the booking app, or leave the list empty.

Your WordPress user must be allowed to add scripts (administrators are, by default).

## Path C: your own front-end

```js
const KEY = '<your public key>';
const API = 'https://app.nisebookings.com/api/public/' + KEY;

const { tenant, services } = await fetch(`${API}/services`).then((r) => r.json());
// tenant.timeZone, tenant.currency, tenant.gateways, tenant.depositMode, …

const { days } = await fetch(`${API}/slots?service=${serviceId}&from=2026-10-14&days=7&persons=1`)
  .then((r) => r.json());
const slot = days.flatMap((d) => d.slots)[0];

const res = await fetch(`${API}/bookings`, {
  method: 'POST', headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    items: [{ service: serviceId, staff: slot.staffId, start: slot.start, persons: 1 }],
    name: 'Ada Jansen', email: 'ada@example.com', gateway: 'local',
  }),
});
const order = await res.json();          // order.orderToken, order.items[0].status
```

Full endpoint reference, error codes and recipes (Mollie checkout, recurring series, waiting list,
tickets): [`04-public-api.md`](04-public-api.md). Machine-readable: [`openapi.yaml`](openapi.yaml).

## Booking events instead of appointments

```html
<script src="https://app.nisebookings.com/events.js" defer></script>
<nise-events data-key="<your public key>"></nise-events>
```

Publish an event with ticket types in **Evenementen**, then embed. See
[`03-widget-reference.md`](03-widget-reference.md#nise-events).

## Try it first

No account needed: one call creates a [sandbox](08-sandbox.md) — a complete test business with a
public key and an all-scopes management key, valid for 24 hours. It never sends mail (read what it
would have sent via `GET /api/v1/outbox`) and its Mollie checkout is a fake page.

```bash
curl -s -X POST https://app.nisebookings.com/api/sandbox   # → {publicKey, apiKey, expiresAt, endpoints}
```

To just look: `https://app.nisebookings.com/demo.html` (widget + event shop). Runnable code:
[`examples/`](examples/README.md) — `headless.mjs` runs against a sandbox key unchanged.

## Verify your integration

1. Complete a booking through your page. The calendar (**Agenda**) shows it immediately.
2. **Afspraken** shows the booking status; **Betalingen** shows the payment (if priced).
3. **Meldingen → Verzendlog** shows the confirmation mail and its delivery status.
4. The confirmation mail contains a cancel link; open it and cancel to test the customer path.

## Troubleshooting

| Symptom | Cause / fix |
|---|---|
| Widget shows "De agenda kan nu niet worden geladen." | Wrong key, or the API host is unreachable from the browser. Check the network tab: a 404 means the key is wrong. |
| `403 {"error":"origin_not_allowed"}` | The embedding origin is not in **Toegestane websites**. Add it, or clear the list. |
| Widget renders but lists no services | Your account has no services with `visibility = public` and at least one public staff member who performs them. Check **Diensten** and **Medewerkers → Diensten**. |
| No times offered | Staff schedules (or opening hours for new staff), company/staff holidays, minimum notice, booking horizon, and the slot grid. Try another day; check the staff's **Rooster**. |
| Times offered but booking fails with 409 | Someone else took the slot; re-fetch and pick again. |
| Payment link fails / `502 payment_unavailable` | Mollie key missing or invalid, or Mollie temporarily unreachable. Check **Instellingen → Betalingen**. |
| Mails not arriving | Check **Meldingen → Verzendlog** for status and error text; a customer may also find it in their spam folder. |
| Widget shows an older version than expected | Rare — the console shows `nisebookings@<version>` on load; add `?v=<version>` to the script URL (or hard-refresh) if a cache serves an old copy. |

## Going live checklist

- [ ] Real services, staff schedules, holidays (company + per staff) entered.
- [ ] **Instellingen → Algemeen**: time zone, time step, minimum notice, booking horizon.
- [ ] **Instellingen → Afspraken**: new bookings confirmed immediately or pending approval?
- [ ] **Instellingen → Betalingen**: VAT mode, deposit mode, gateways, Mollie live key.
- [ ] **Instellingen → Insluiten**: allowed websites restricted to your domains.
- [ ] Notification templates reviewed in Dutch (sender name, reply-to, texts, reminders).
- [ ] Reminders, payment timeouts and automatic status changes are handled by the service —
      nothing to run yourself.
- [ ] A test booking, cancellation and refund done end to end.
# Concepts

How the booking engine thinks. Read this before writing an integration; it prevents most wrong
assumptions about slots, capacity, money and time.

## Contents

- [The shape of the system](#the-shape-of-the-system)
- [Your account (tenant)](#your-account-tenant)
- [Catalogue: services, staff, extras](#catalogue-services-staff-extras)
- [When is a time bookable?](#when-is-a-time-bookable)
- [Appointments, bookings, orders](#appointments-bookings-orders)
- [Statuses](#statuses)
- [Special booking kinds](#special-booking-kinds)
- [Money](#money)
- [Notifications](#notifications)
- [Time and locale](#time-and-locale)
- [Terminology: Dutch UI and English](#terminology-dutch-ui-and-english)

## The shape of the system

```
                       ┌─────────────────────────── admin UI (/app, login)
account ─► catalogue ──┤
(key)      services    │
           staff       └──► availability engine ──► slots ──► order ──► payment
           schedules                                            │
           holidays                                             └──► notifications (mail)
                                    ▲
     public API / widget ───────────┘   (no login, public key, server-side re-check)
```

- **One account = one business.** Your account is identified by its public key on the public side,
  and by the signed-in user's membership in the admin.
- **The availability engine is deterministic**: given service, staff, schedules, holidays, existing
  appointments and preferences, it returns the list of bookable slots. The server re-runs the same
  check when a booking comes in, so what was offered is what gets verified.
- **The public API never trusts the client.** Every booking is re-resolved and re-checked, then written
  inside one transaction that takes a per-staff lock. The widget is a convenience client, not a
  privileged one.

## Your account (tenant)

An account is one business (the API calls it a *tenant*): name, slug, **public key** (the credential for the public API), time zone,
locale, currency, VAT mode, deposit mode, gateways, booking rules (slot length, minimum notice, booking
horizon, default status), calendar options and feature switches (cart, chain, recurrence, waiting
list, combined-price method, occupancy display).

All data belongs to one account: a business can only ever see its own records, and every public call
is bound to exactly one account by its key. A person relates to an account with a role (`owner`,
`admin`, `front_desk`, `staff`); there is no account switcher — the first membership wins.

## Catalogue: services, staff, extras

**Category** — grouping for the customer-facing list (Knippen, Verhuur, …). Optional.

**Service** — the thing being booked. Four types:

| Type | Meaning | Example |
|---|---|---|
| `simple` | one appointment, one staff member | haircut, intake, rental hour |
| `compound` | a fixed sequence of parts, one after another, with optional spare time between them | wash → cut → dry |
| `collaborative` | parts that must happen **at the same time**, each by a different staff member | skipper + boat; two instructors |
| `package` | a prepaid bundle of N appointments of one `simple` service | 5-ride card |

A `simple` service carries: duration, optional own slot length, price, deposit rule, VAT rate, minimum
and maximum persons (capacity), padding before/after, staff preference for "any", visibility
(public/private), `one_booking_per_slot`, which recurrence frequencies customers may choose, and an
optional waiting-list cap. Prices and capacity can be overridden **per staff member**
(`staff_services`), which is why a slot is always evaluated per (service, staff) pair.

**Staff** — anything with its own schedule that can be booked: a person, a boat, a room, a device.
Staff carries a weekly schedule (per weekday start/end plus breaks), holidays/vacation days, contact
details, visibility (public/private/archive), and the list of services performed. A staff record needs
no login; a login is linked via `staff.user_id` when the person should see their own agenda.

**Extras** — optional add-ons per simple service: price, extra duration (added **after** the
appointment), minimum/maximum quantity. A minimum of 1 makes the extra mandatory. Extras belong to
simple services; on compound/collaborative services every extra is attached to the part that owns it.

**Schedule and holidays** — a service's availability comes from the *staff* schedules. Company opening
hours are only a template for new staff rows; company holidays apply to everyone, staff holidays only
to that staff member. A "toch open" holiday row (kind `exception`) makes the company open on a yearly
closing day.

## When is a time bookable?

A slot is a start time the engine may offer. For the chosen service and each candidate staff member:

1. The start time lies on the **slot grid**: step = `service.slot_length` or the account-wide `slot_length`
   (default 15 min).
2. The **whole block fits in the schedule**: duration + extras + padding before/after must be inside a
   working period and outside breaks, on that weekday.
3. The date is not a **holiday** for the staff member or the company.
4. The start is at least `min_prior_minutes` from now and within the booking horizon
   (`max_days`, default 365).
5. It does not **conflict**, with padding, with an existing blocking appointment of that staff member
   (plus events they are linked to, plus holds while a customer is mid-checkout).
6. Capacity allows it: the number of persons already booked (blocking statuses only) plus the
   requested persons must fit the staff member's capacity for that service.

A block that is partly occupied is offered as a **partial** slot when the remaining capacity suffices
(group slots; the UI shows the occupancy). A **full** slot is omitted, unless a waiting list is open —
then it is returned with `state: "waitlist"`.

Two services can be booked into the *same* appointment (group join) only when the service, start,
duration and extras match and the capacity still allows it; `one_booking_per_slot` forbids any join.

When several staff members qualify and the customer sends `staff: "any"`, the service's
**staff preference** decides: `order` (list order), `least_expensive`, `most_expensive`.

For compound/collaborative services the engine searches the whole sequence at once: parts run
consecutively (compound, with spare time free for others) or in parallel on **distinct** staff members
(collaborative). Only the first part's staff is customer-choosable.

## Appointments, bookings, orders

```
order (one checkout)                      ← orders row, one token, one payment
 ├── appointment 09:30–10:15 (service A, staff X)   ← a block of time in a calendar
 │    ├── booking: Ada, 1 person, approved
 │    └── booking: Bob, 2 persons, approved          ← group join, same appointment
 ├── appointment 10:15–11:00 (service B, staff Y)   ← chain part
 └── series: appointments on 7 dates                ← recurring occurrences
```

- **Appointment** = the occupied time block (staff + service + start/end + internal note).
- **Booking** = one customer on an appointment, with persons, status, notes and a magic **token**.
  The public cancel/reschedule page is `/b/<booking token>`; the token also appears in mails.
- **Order** = everything a customer checks out in one go (cart items, chain parts, all occurrences of
  a series, compound/collaborative parts). One order = one payment. The order token is returned as
  `orderToken` and mailed as the cancel-order link (`{cancel_order_url}` → `/o/<token>`).
- **Hold** = an item a customer has chosen but not yet booked; the client sends it back with slot
  searches so the customer's own choices count as occupied. Holds are never real appointments.
- **Series** = recurring appointments created together, sharing a `series` row with the rule. The
  admin can edit one, this-and-following, or all occurrences.
- **Compound/collaborative parts** share a `group_token`; status changes apply to all parts.

Blocking statuses are `pending` and `approved` — those (and appointments with **no** bookings at all,
which block entirely) determine occupancy.

## Statuses

| Status | Dutch label | Blocking | Meaning |
|---|---|---|---|
| `pending` | In afwachting | yes | booked, awaiting confirmation (when the business requires approval, or a payment is open) |
| `approved` | Bevestigd | yes | confirmed |
| `waitlisted` | Wachtlijst | no | wants a seat if one frees up; never paid, never blocking |
| `cancelled` | Geannuleerd | no | cancelled by customer or admin |
| `rejected` | Afgewezen | no | refused by admin, or payment failed/expired |
| `done` | Afgerond | no | the appointment happened (manual or via automatic status change) |

An account-level **automatic status change** can move appointments that have ended from one status to
another (e.g. approved → done) automatically, checked every minute; bookings changed in the last two days get a
notification.

## Special booking kinds

- **Group booking** — a service with capacity > 1; several customers share one appointment. Occupancy
  can be shown to customers (off / `3/8` / `nog 5`).
- **Waiting list** — when a slot is full and the service and account settings allow it, customers can take a place
  on the list. Optional mode *"Wachtlijst telt mee als bezet"*: waitlisted persons count as occupying
  and once anyone is waitlisted, later bookers are waitlisted too. When seats free up, **all** waiting
  customers of that appointment get a first-come-first-served mail. No payment is involved.
- **Recurring** — a series of occurrences with a rule (daily/weekly/biweekly/monthly, interval,
  weekdays, monthly day or nth-weekday, until/count, max 52). Occurrences whose preferred time is taken
  are moved to a nearby available time (`anotherTime: true`) or reported as "no time found". Payment
  mode: the whole series in one payment, or only the first occurrence (the rest is paid on site —
  `onSite` in the quote).
- **Package** — prepaid N appointments. Bought online (`kind: "package"`) or created by the admin;
  the customer receives a personal `/p/<token>` link and schedules visits with the widget in package
  mode. Validity starts at the first planned visit; visits are never paid again.
- **Events** — separate from appointments: dated happenings with ticket types, quantities, reserved
  seats and a sales deadline. Tickets get unique codes from a mask; codes are only shown/valid once the
  order is approved (paid). Every staff member linked to an event (organiser or support) shows the
  event in the calendar and has that time blocked for bookings.
- **Extras** — priced and timed add-ons, snapshot per booking (title, price, duration, quantity).
  Whether extras multiply by persons is an account setting.
- **Chain** — several services back-to-back for one customer, one after another, with each part
  possibly a different staff member.
- **Cart** — several independent appointments checked out together as one order.

## Money

**Price sources.** The unit price of an item is the staff-specific price (`staff_services.price`) when
that staff member was assigned, otherwise the service price. Compound/collaborative services use their
own price, or the sum of the parts' staff prices when the business chose *Optelsom van de onderdelen*.

**Order formula**: per item `unit price × persons`, plus
extras (× persons when the account multiplies them), summed to a subtotal; deposit applied per item
(`'100%'`, or `'30%'`, or a fixed amount **per person**); coupon discount and fixed deduction; optional
gateway surcharge (Mollie % + fixed); VAT. Prices include VAT by default (NL B2C): the shown total
already contains it and the quote returns `tax` as the part that is VAT. Rounding is half-away-from-zero
at 2 decimals.

**What the customer pays now** (`payNow`) is the deposit, or the full amount, depending on the account's
deposit mode (`deposit_only`, `choose_deposit`, `choose_full`) and the customer's choice. The rest is
`due`, payable on site. A zero order becomes a **free** order; a Mollie order whose payable amount is
zero falls back to a **local** one.

**Payment types.** `local` (pay at the desk — the admin completes it later), `free` (nothing to pay),
`mollie` (online; iDEAL/card on Mollie's page). One payment per order. Statuses: `pending`,
`completed`, `rejected`, `refunded`; late arrivals are flagged (`late_paid`) when the slot was already
given away.

**Coupons** — percentage and/or fixed amount, usage limit (account-wide), once-per-customer, validity
dates (the *booking* date counts), minimum/maximum appointments per order, and optional restrictions to
services/staff. A coupon use is given back when the payment is rejected.

## Notifications

Mail is driven by **templates** per type: `new_booking`, `status_changed`, `reminder`, `waitlisted`,
`waitlist_offer`, `package_new`, `event_tickets`. Each template picks recipients (customer, the staff
member, admins, extra addresses), a status filter, a service filter and — for reminders — a timing
(relative: N hours before the start; or a fixed hour, N days before). Bodies use `{codes}` and
`{#if …}` blocks. Rendering happens when the mail is queued; sending retries with backoff. Order mails
are sent once per order (staff get one per own appointment); status changes and reminders stay per
booking. See [`06-notifications.md`](06-notifications.md).

## Time and locale

- Instants are stored and transmitted as UTC. Everything customer-visible (slot times, day headings,
  "today", holidays, schedules, reminder timing) is computed in the **business time zone**.
- Recurrence and slot `from`/`until` use business-local calendar dates (`YYYY-MM-DD`).
- Formatting uses the account `locale` (default `nl`) and `currency` (default `EUR`).
- Bookings do not store a customer time zone; the whole product presents business-local time.

## Terminology: Dutch UI and English

| Dutch (UI) | English (docs) |
|---|---|
| dienst | service |
| medewerker | staff (member) |
| categorie | category |
| afspraak | appointment |
| boeking | booking |
| bestelling | order |
| reeks | series |
| wachtlijst | waiting list |
| pakket | package |
| evenement / deelnemer | event / attendee |
| tickettype | ticket type |
| rooster | schedule |
| vrije dag | day off / holiday |
| openingstijden | opening hours |
| pauze | break |
| toeslag | surcharge |
| aanbetaling | deposit |
| kortingscode | coupon |
| opmerking | note (customer's) |
| interne notitie | internal note |
| extra('s) | extras |
| tijdstap | slot length / time step |
| bezetting | occupancy |
# Widget reference

Two dependency-free custom elements turn any HTML page into a booking page:

- **`<nise-booking>`** — the booking flow (service → time → details → payment → done).
- **`<nise-events>`** — the event/ticket shop.

Both render into an open shadow DOM, read their configuration from `data-*` attributes, and talk to
the [public API](04-public-api.md) directly from the browser. There is no iframe, no build step and no
npm package.

## Contents

- [Embedding](#embedding)
- [Language](#language)
- [The API base URL](#the-api-base-url)
- [`<nise-booking>` attributes](#nise-booking-attributes)
- [Booking flow step by step](#booking-flow-step-by-step)
- [Package mode](#package-mode)
- [Recurrence, cart and chain in the widget](#recurrence-cart-and-chain-in-the-widget)
- [Waitlist and occupancy](#waitlist-and-occupancy)
- [Payment step and return handling](#payment-step-and-return-handling)
- [`<nise-events>`](#nise-events)
- [Styling](#styling)
- [Accessibility](#accessibility)
- [WordPress](#wordpress)
- [Limits, caching and versioning](#limits-caching-and-versioning)
- [What the widget cannot do](#what-the-widget-cannot-do)

## Embedding

```html
<script src="https://app.nisebookings.com/widget.js" defer></script>
<nise-booking data-key="YOUR_PUBLIC_KEY"></nise-booking>
```

```html
<script src="https://app.nisebookings.com/events.js" defer></script>
<nise-events data-key="YOUR_PUBLIC_KEY"></nise-events>
```

- The scripts are classic scripts (not modules), need no dependencies, and register the element only
  if it is not registered yet — loading the script twice is harmless.
- Keep `defer`: the elements upgrade themselves and start loading as soon as they are connected.
- One element instance per page slot. The element has no JS API: no constructor, no methods, no events
  (details below); the only global it sets is `window.nisebookings.version`.
- The widget needs no cookies and sends no credentials.

## Language

The customer-facing texts ship in **Dutch and English**. Each element resolves its language on its
own, in this order:

1. **`data-lang` on the element** — trimmed and lowercased; anything starting with `nl` is Dutch,
   everything else English. Use it to run one page, or one embed, in another language than the
   account.
2. **The account's language** — **Instellingen → Algemeen → Taal van het boekingsformulier**
   (Nederlands/Engels; `locale` in `PATCH /api/v1/settings`). It arrives with `GET services`.
3. **Dutch**, when neither is set.

`<nise-booking data-key="…" data-lang="en">` sets `lang` on its host element (the shadow tree
inherits it) and re-renders the current step when `data-lang` changes; `<nise-events data-lang="en">`
reads the attribute on connect and again after the first fetch. On WordPress the plugin shortcodes
take the same value: `[nise_booking lang="en"]` and `[nise_events lang="en"]` (`"nl"` for Dutch);
without it they follow the account language.

Not translated on purpose: server data (service, staff and event titles and descriptions) and
numbers and dates. Formatted values follow the *account's* `locale`, so an English widget on a Dutch
account shows Dutch month names and `€ 1.234,56` — set the account language as well if you want
everything in English.

## The API base URL

The widget decides once, at script-load time, where the API lives:

1. `data-api="https://app.nisebookings.com"` if present — used **verbatim** (no trailing-slash
   normalisation);
2. otherwise the origin of the script's own `src` (`https://app.nisebookings.com/widget.js` → `https://app.nisebookings.com`);
3. otherwise the embedding page's origin.

If you load the scripts from anywhere other than `https://app.nisebookings.com`, **`data-api` is
mandatory**. Note that `document.currentScript` is
`null` for module scripts, inline scripts and dynamically injected `async` scripts; in those cases the
fallback is the page origin, so set `data-api` explicitly.

Requests without an `Origin` header work too (server-to-server), but for browser embeddings your
account's **Toegestane websites** list applies (Instellingen → Insluiten). Empty list = any site;
otherwise the API answers 403 `origin_not_allowed`.

## `<nise-booking>` attributes

| Attribute | Default | Meaning |
|---|---|---|
| `data-key` | — | **Required.** Your account's public key. |
| `data-api` | script origin | API base URL (see above). |
| `data-service` | — | Preselect a service id (from `GET services`). The widget skips the service step only when the service has fewer than 2 staff (or hides staff), no extras, capacity 1, the chain feature is off and the entry is not already in the cart. |
| `data-staff` | `any` | Preselect a staff id, or `any`. Ignored when the chosen service is not offered by that staff member (falls back to `any`). |
| `data-package` | — | Package mode for an already bought package: the token from the `/p/<token>` link. |
| `data-lang` | account language | Language of the customer-facing texts: `nl` or `en` (anything not starting with `nl` means English). See [Language](#language). |

Attributes are read on connect only — except `data-lang`, which the element observes: changing it
after the element is in the DOM switches the language (and the host's `lang` attribute) and
re-renders. No other attribute has an `attributeChangedCallback`, and re-inserting the same element
does not re-initialise it. If you need a different configuration, create a new element (or replace
the old one).

## Booking flow step by step

Steps are `0` services, `1` time, `2` details/payment, `3` done, `4` payment-status message,
`5` cart.

**Step 0 — Kies een dienst.** Service list with title, description, duration and price; packages show
"N dagen geldig"/"onbeperkt geldig". A staff `<select>` ("Medewerker", first option "Maakt niet uit")
appears only when the service has more than one public staff member and the business has not hidden
staff for collaborative services. "Aantal personen" appears when capacity > 1. Extras render as
checkboxes (single-choice) or number inputs; mandatory extras are pre-set and disabled. Buttons:
**Kies een tijd** (packages: **Verder**), **Dienst toevoegen** (chain), **Deze dienst weglaten** /
**Geen dienst toevoegen**, **Terug naar je afspraken** (cart). Empty: "Er zijn nu geen diensten te
boeken."

**Step 1 — Kies een tijd.** One week at a time with **Vorige week** / **Volgende week**
(`hasMore` from the API decides whether "next" is enabled). Slots are grouped per day with
localised headings. Occupancy is shown only when *Bezetting tonen* is on and capacity > 1: `3/8`
("Bezette plaatsen") or `nog 5` ("Vrije plaatsen"). Waiting-list slots are greyed with
"wachtlijst (N)". Loading text "Tijden laden…", empty "Geen vrije tijden in deze week. Kijk een week
verder.", failure "De tijden kunnen nu niet worden geladen. Probeer het opnieuw."

**Step 5 — Je afspraken** (cart; shown when *winkelmand* is on or the entry is recurring). Lists each
entry with service, extras, day/time, staff, "· herhaald" for series, and per entry **Wijzigen**,
**Verwijderen** and, when the service allows repeats, **Herhalen** / **Herhaling aanpassen**. Footer:
**Verder** and **Nog een afspraak**.

**Step 2 — Je gegevens.** Fields Naam, E-mail, Telefoon, Opmerking, then the service's own intake
questions (Instellingen → Diensten → Velden: text, textarea, choice, checkbox, number, date or file —
JPG/PNG/WebP/PDF up to 5 MB, uploaded before the booking is sent; a required one is marked, a
per-person one renders a control per person as "Persoon 1", "Persoon 2", and a conditional one
(**Toon alleen als**) appears and disappears as the customer answers the question it depends on —
see the public API's
`fields` and `{{fields}}` in mails); then, when something has to be
paid: the coupon field (**Toepassen**), payment method radios (**Ter plaatse betalen** / **Online
betalen (iDEAL, creditcard en meer)** — only when the business offers both), and, for Mollie orders where
any service has a deposit other than 100%, the choice **Alleen de aanbetaling** / **Het hele bedrag**.
A live price summary (refreshed through `POST quote`, 250 ms debounce) shows Totaal, plus Subtotaal
and Korting only when a coupon applies, a VAT line ("waarvan btw" when prices include VAT, "Btw"
otherwise) only when VAT is non-zero, "Nu te betalen" / "Later te betalen" for deposits and "Ter
plaatse te betalen (herhaalde afspraken)" when part of a series is paid on site.
Submit: **Afspraak bevestigen**, or **Naar betalen** for an online payment. Notes appear for waiting
list ("Je komt op de wachtlijst, je betaalt nu niets.") and package bookings ("Gebruik het
e-mailadres waarmee je het pakket hebt gekocht.").

**Step 3 — done.** Heading and text follow the result: "Je afspraak staat vast" when every timed item
is `approved`, "Je aanvraag is ontvangen" when something is still pending, "Je staat op de wachtlijst"
for waiting-list-only orders, "Je pakket is besteld" for package purchases.
**Nog een afspraak maken** restarts (in package mode it reloads the package).

**Error handling** is inline and specific:

| Situation | Message |
|---|---|
| Slot taken between choosing and submitting (409) | "Een gekozen tijdstip is net geboekt. Kies een ander tijdstip." — the entry is highlighted, or reopened for editing when it was the only one. |
| Validation (422) | Per-field messages ("Vul je naam in.", "Vul een geldig e-mailadres in.", "Vul een geldig telefoonnummer in.", "Je opmerking is te lang.") + "Controleer de gemarkeerde velden."; focus moves to the first invalid field. |
| Invalid coupon | "Deze code is ongeldig of al gebruikt." / "Deze code is verlopen." — the field is cleared and the price re-quoted. |
| Package errors | "Dit pakket hoort bij een ander e-mailadres.", "Dit pakket is verlopen.", "Dit pakket is opgebruikt." |
| Waiting list full | "De wachtlijst voor dit tijdstip is vol. Kies een ander tijdstip." |
| Mollie unavailable (502) | "Online betalen lukt nu even niet. Kies ter plaatse betalen of probeer het later opnieuw." |
| Anything else | "Er ging iets mis bij het boeken. Probeer het opnieuw." |
| Services unreachable | "De agenda kan nu niet worden geladen. Probeer het later opnieuw." |

## Package mode

`<nise-booking data-key="…" data-package="<token>">` (this is what `/p/<token>` renders) loads
`GET packages/<token>` and locks the widget to that package:

- The service list is replaced by the package's service with the package's fixed staff (or free
  choice), price 0, and the widget jumps straight to the time step.
- A banner shows "`<packageTitle>` · nog `N` van `M` · geldig t/m `date`".
- Cart and chain are disabled inside package mode; the API refuses paid booking of package visits.
- Invalid or used-up packages render "Dit pakket is opgebruikt of verlopen." / "Dit pakket is niet
  gevonden."

## Recurrence, cart and chain in the widget

- **Herhalen** (visible per entry when the service offers frequencies): choose *Hoe vaak* (Elke dag /
  Elke week / Om de week / Elke maand), the interval for daily ("Om de hoeveel dagen"), weekdays for
  weekly ("Op", ma–zo), a monthly option (a day number, "de Ne <weekdag>", or "de laatste <weekdag>"),
  and either **Aantal keer** (2–52) or **Of tot en met** (a date). **Data zoeken** calls
  `POST recurrence` and lists every occurrence; moved ones show "· ander tijdstip", ones without a time
  show "· geen tijd gevonden", each removable. The whole series is sent as one order with a series key.
- **Cart**: with *winkelmand* on, selections accumulate and are sent as one order; earlier entries are
  passed as `hold` during slot searches so the customer never sees their own choices as free.
- **Chain**: "Dienst toevoegen" adds a second service that must run right after the first; the time
  step then searches chain slots (`POST slots` with multiple items) and shows each part's time.

## Waitlist and occupancy

Waiting-list slots appear only when the business enabled the waiting list and the service allows it. A
slot row shows "wachtlijst (N)" where N is the number of people already waiting. Booking one creates a
`waitlisted` booking without payment; when a seat frees up the customer receives the `waitlist_offer`
mail with a first-come-first-served `/w/<token>` link.

## Payment step and return handling

For an online (Mollie) payment the widget redirects to the returned `checkoutUrl`. On return, with
`nb_pay=<token>` in the URL, it removes that parameter (`history.replaceState`), shows "Betaling
controleren…" and polls `GET payments/<token>` every 2 seconds, up to 15 times:

- **completed** → the done step ("Je betaling is ontvangen.").
- **failed/refused** → "Betaling niet gelukt" / "De betaling is niet gelukt. Je afspraak is niet
  geboekt." with **Opnieuw proberen** (restarts the flow at the service step and clears the cart).
- **still pending after 30 s** → "Betaling wordt verwerkt" / "Je betaling wordt nog verwerkt. Je krijgt
  een bevestiging per e-mail."

You do not need a thank-you page of your own when you use the widget: pass a `returnUrl` on your page
and the widget handles the return. When you build a custom checkout, do the same polling yourself —
see [`04-public-api.md`](04-public-api.md#2-mollie-checkout).

## `<nise-events>`

Attributes: `data-key`, `data-api` and `data-lang` (read on connect and again after the first fetch;
see [Language](#language)).

- **List**: each published event shows title, date range (localised, business time zone), optional image,
  info, and a row per ticket type with price ("gratis" when 0) and "nog N" or "uitverkocht"; quantity
  inputs are capped at `min(left, 50)`. **Tickets kiezen** continues; without a selection: "Kies ten
  minste één ticket."
- **Form**: Naam, E-mail, Telefoon, and when the total is > 0 and both gateways are enabled, the same
  **Betaalwijze** radios. **Tickets bestellen** sends `POST events/<id>/tickets`.
- **Done**: "Je tickets zijn besteld" with the codes, or "Je codes krijg je na betaling." when the
  order is not approved yet.
- **Payment return**: the same 2-second polling, but it requires both `nb_pay` **and** `ne` in the URL
  (`ne=1` is what this widget writes into its own `returnUrl`, so a booking widget on the same page
  does not pick up the ticket payment).
- No coupon, no notes, no deposit choice, no per-item price breakdown.
- Errors: "Er zijn niet genoeg tickets meer. Kies opnieuw." (sold out), "De verkoop voor dit
  evenement is gesloten.", "Online betalen lukt nu even niet. Kies ter plaatse betalen of probeer het
  later opnieuw.", "Er ging iets mis bij het bestellen. Probeer het opnieuw."

## Styling

The shadow DOM isolates internal styles; the host exposes design tokens as CSS custom properties.
Set them on the element (or any ancestor):

```css
nise-booking, nise-events {
  --nb-accent: #E5006F;        /* buttons, links, highlights */
  --nb-accent-hover: #C2005E;
  --nb-text: #1A1A1F;
  --nb-text-2: #4A4B68;
  --nb-text-3: #6E6F88;        /* muted meta text */
  --nb-bg: #fff;
  --nb-sunken: #F7F8FB;        /* cards, panels */
  --nb-border: #E6E7EE;
  --nb-border-strong: #C7C6D1;
  --nb-danger: #CF2E36;
  --nb-focus: #FF4D9B;         /* focus ring */
  --nb-radius: 4px;
}
```

- `font` is inherited from the page (the host sets only `font-weight: 300` and `line-height: 1.6`),
  so your typography reaches the widget; sizes and colours do not.
- The host is `display: block; max-width: 640px`. Control the width with a wrapper.
- There are **no** `::part` hooks and no class API — the internal class names are implementation
  detail. Anything not listed above cannot be restyled.
- Customer-facing texts are the built-in Dutch/English strings ([Language](#language)); only names,
  prices, durations and date formatting come from the API (your account's `locale`, `currency` and
  `timeZone`).

## Accessibility

- The error line is `role="alert" aria-live="assertive"`; the loading line and the price summary are
  `aria-live="polite"`.
- Headings are `h2` with `tabindex="-1"` and receive focus on each step change.
- Service choices are buttons with `aria-pressed`; the selected one is exposed as a toggle state.
- Invalid fields get `aria-invalid` plus `aria-describedby` pointing at their message, and focus moves
  to the first invalid field after a failed submit.
- Inputs are wrapped in or bound to `<label>`s; focus styling uses `:focus-visible` with a 2 px ring.
- The container is keyboard-operable end to end (links, buttons, radios, selects).

## WordPress

No plugin is needed. In the block editor, add a **Custom HTML** block to any page or post and paste the
two lines from [Embedding](#embedding) (`widget.js` + `<nise-booking>`, or `events.js` +
`<nise-events>`). The `data-service`, `data-staff` and other attributes work the same way,
`data-lang` included. The plugin's shortcodes take the language as `lang`: `[nise_booking lang="en"]`
and `[nise_events lang="en"]` (or `"nl"`; without it, the account's language). Your
WordPress user must be allowed to add scripts (administrators are, by default). Add the
WordPress site to **Toegestane websites** in the booking app, or leave that list empty.

## Limits, caching and versioning

| Limit | Value |
|---|---|
| Items per order | 60 (server), chain parts 10 (server); the widget itself adds no cap |
| Chain/search window | 31 days per slots call (the widget asks one week at a time) |
| Recurrence | 2–52 occurrences, interval 1–30 |
| Name / email | 255 characters |
| Phone | 50 characters |
| Notes | 2000 characters |
| Coupon code | the widget's field allows 50; the API accepts 40 |
| Ticket quantity | 1–50 per type, at most 20 types |
| Script sizes (budget) | `widget.js` ≤ 20 KB gzip (≈16.5 KB now), `events.js` ≤ 8 KB gzip (≈5.8 KB now); both languages ship in the same file |

- **Version marker.** The first of the two scripts that loads logs `nisebookings@0.4.0` to the browser
  console (once per page) and sets `window.nisebookings.version`. That is how you tell which build a
  page is running — a page that mixes a stale cached script with a fresh one reports whichever loaded
  first.
- **Cache-busting.** Appending a version query to the script URL (`/widget.js?v=0.4.0`) is supported:
  it forces a fresh fetch, and the file served does not depend on the query. The WordPress plugin
  adds `?ver=0.4.0` automatically. After an update a browser may otherwise briefly keep an old copy;
  a hard refresh fixes it too.
- Load both scripts from `https://app.nisebookings.com` so you always get the current version. A copy
  served from elsewhere needs `data-api` and does not update itself.

## What the widget cannot do

- Intake questions and file uploads (JPG, PNG, WebP or PDF, up to 5 MB) yes, both in step 2; customer
  accounts no.
- Only Dutch and English ([Language](#language)): no third language, no way to override individual
  strings.
- No JS API: no events fired, no methods to call, no way to drive it from your own script. If you need
  that, build on the [public API](04-public-api.md) instead.
- No rescheduling inside the widget; customers cancel or move their booking through the mail link
  (`/b/<token>`).
- Day-based services (rentals per whole day, `durationDays` ≥ 1) show a **start-date picker** instead of
  the time grid: the service line reads "N dagen · € X per dag", the customer picks a start date, and
  the summary and confirmation show the span ("woensdag 21 oktober → zaterdag 24 oktober · 3 dagen").
  Such a service cannot be combined with other items in a chain or cart (button hidden, the API also
  refuses it).
- No styling beyond the custom properties above, no `::part`, no theme attribute.
# Public API reference

Everything a website, app or widget needs to sell and manage bookings for one business. No
authentication: the business's account is identified by its **public key** in the path. All endpoints live under
`/api/public/<key>/…`.

Read [`02-concepts.md`](02-concepts.md) first if terms like *service*, *item*, *order* or *hold* are new.

- Base URL: `https://app.nisebookings.com`.
- This page documents the **public** API (no login). The account itself — services, staff,
  schedules, opening hours — is configured through the separate
  [management API](../api/README.md), which uses scoped keys instead of the public key.
- The key is the business's **publieke sleutel**: the admin shows it under *Instellingen → Insluiten*.
- Bodies are JSON (`Content-Type: application/json`), except `POST uploads` which takes
  `multipart/form-data`. Responses are JSON with `Cache-Control: no-store` — except
  `GET services`, which is cacheable for 60 s.
- All times in requests and responses are **ISO 8601 UTC** (`2026-10-14T09:30:00.000Z`). Dates in
  requests (`from`, `until`) are **business-local calendar dates** (`YYYY-MM-DD`). The business
  time zone comes from `GET services` (`tenant.timeZone`).

## Contents

- [CORS and errors](#cors-and-errors)
- [The item object](#the-item-object)
- [Endpoints](#endpoints)
  - [GET services](#get-services)
  - [GET slots](#get-slots)
  - [POST slots (chain / holds)](#post-slots-chain--holds)
  - [POST recurrence](#post-recurrence)
  - [POST quote](#post-quote)
  - [POST uploads](#post-uploads)
  - [POST bookings](#post-bookings)
  - [POST bookings/{token}/reschedule](#post-bookingstokenreschedule)
  - [GET payments/{token}](#get-paymentstoken)
  - [GET packages/{token}](#get-packagestoken)
  - [GET events](#get-events)
  - [POST events/{id}/tickets](#post-eventsidtickets)
- [Retries and Idempotency-Key](#retries-and-idempotency-key)
- [Versioning and rate limits](#versioning-and-rate-limits)
- [Payment lifecycle](#payment-lifecycle)
- [Integration recipes](#integration-recipes)
- [Rules the server enforces](#rules-the-server-enforces)
- [What the API does not do](#what-the-api-does-not-do)

## CORS and errors

The server reflects the request `Origin` when the account's **Toegestane websites** list
(`allowedOrigins`) is empty
(default = allow any site) or contains that exact origin. Otherwise it answers
`403 {"error":"origin_not_allowed"}`. `OPTIONS` is answered with 204 for every endpoint. Allowed request headers:
`Content-Type`, `Idempotency-Key` and `X-Api-Version`.

Every error body has an `error` field:

| HTTP | `error` | Meaning |
|---|---|---|
| 403 | `origin_not_allowed` | Origin not in the account's **Toegestane websites** list. |
| 404 | `not_found` | Unknown public key, service, event, package, payment or booking token. |
| 409 | `slot_unavailable` | Between choosing a time and submitting, the slot went away. Body has `item`: the 0-based index of the failing item. Re-fetch slots and let the user pick again. |
| 409 | `cannot_reschedule` | This booking cannot move (cancelled/rejected/waitlisted, already started, or inside the account's cancel window). |
| 409 | `sold_out` / `sales_closed` | Event tickets. `sold_out` has `type`: the ticket type id. |
| 400 | `bad_request` | `Idempotency-Key` header is empty, longer than 255 characters or not visible ASCII. |
| 400 | `bad_request` | `X-Api-Version` is not a supported version; the body also lists `versions`. |
| 409 | `idempotency_in_progress` | The first request with this `Idempotency-Key` is still running. Wait (`Retry-After: 1`) and send it again. |
| 413 | `too_large` | `POST uploads` file bigger than 5 MB. |
| 422 | `idempotency_mismatch` | This `Idempotency-Key` was already used with a different body. Use a new key for a new order. |
| 422 | `validation` | Body has `fields: {<field>: 'invalid'\|'required'\|'too_long'}` and sometimes `item` (index). For an intake question the key is the field id and the value a message in the request's `Accept-Language` (`nl` or `en`; English without the header — the widget sends its language). |
| 429 | `rate_limited` | More than 120 requests/min from this IP (20/min for booking commits). `retryAfter` in the body and `Retry-After` say when to try again. |
| 500 | `server` | Bug or DB failure; the message is logged server-side only. |
| 502 | `payment_unavailable` | Mollie could not be reached when creating the checkout. The order exists but its payment and bookings are set to **rejected**, so no visit stays booked; the customer sees this immediately after submitting. |

## The item object

A booking request is a list of *items*. Most integrations send exactly one. The same shape is used
by `POST slots`, `POST recurrence`, `POST quote` and `POST bookings`.

```jsonc
{
  "service": "50000000-0000-0000-0000-000000000001",  // required, uuid from GET services
  "staff": "e0000000-…-0001",                        // uuid, or "any"/omitted = server picks
  "start": "2026-10-14T09:30:00.000Z",               // required for bookings/quote/recurrence; the exact
                                                     // `start` of a slot from GET slots
  "end": "2026-10-17T00:00:00+02:00",                // day services only: the `end` of that same day slot
                                                     // (see "Day services" below), sent back verbatim
  "persons": 1,                                      // default 1; must fit the service capacity
  "extras": { "<extraId>": 2 },                       // optional; quantity per extra id
  "fields": { "<fieldId>": "noten" },                 // optional; answers to the service's intake questions
                                                     // (a perPerson field sends an array: one entry per person;
                                                     //  a file field sends the upload id from POST uploads)

  "series": "a",        // optional key: this item is one occurrence of a recurring series
  "waitlist": true,     // optional: join the waiting list instead of booking (slot state "waitlist")
  "package": "<48-hex token>", // optional: schedule a visit of an already-bought package (no payment)
  "kind": "package"     // buy a package itself: {"kind":"package","service":"<packageService>","staff":null}
}
```

Rules the parser applies (all violations → 422 with `fields.item`/`fields.<name>`):

- `staff: "any"` (or missing/empty) means *let the engine choose* by the service's staff preference.
  The response always contains the resolved `staffId`/`staffName`.
- `persons` is an integer 1–1000; it must be ≥ the minimum and ≤ the maximum capacity of some staff
  member that can perform the service. Multi-part (compound/collaborative) services require it to fit
  **every** part.
- `extras` keys are extra ids of that service; unknown or non-positive entries are dropped, quantities
  are clamped to `[max(1,minQty), maxQty]`, and mandatory extras (minQty ≥ 1) are added at their
  minimum even if the client omits them. The response price proves what was applied. A **day service**
  has no extras: any `extras` → 422 `fields.extras`.
- `waitlist: true` may not be combined with `series` or `package`, and `package` visits are always
  `persons: 1`. Day services (below) have no waiting list either: a full rental simply has no slot.
- At most **60 items** (`MAX_ITEMS`) per order. A chain (see below) may have at most **10** items.
- A recurring series may have at most **52** occurrences (`MAX_OCCURRENCES`).

## Endpoints

### GET services

The catalogue. Cacheable for 60 seconds; call it once per page load.

```
GET /api/public/<key>/services
```

```jsonc
{
  "tenant": {
    "name": "Kapsalon Demo", "timeZone": "Europe/Amsterdam", "currency": "EUR", "locale": "nl",
    "pricesIncludeTax": true,          // see 02-concepts.md § Pricing
    "depositMode": "deposit_only",     // "deposit_only" | "choose_deposit" | "choose_full"
    "gateways": ["local", "mollie"],   // enabled AND configured; never empty ("local" as fallback)
    "cart": true, "chain": true,       // may the customer combine items / "Dienst toevoegen"
    "recurringPayment": "all",         // "all" | "first": what a recurring booking is paid for
    "extrasMultiply": true,            // extra prices × persons
    "showOccupancy": "free"            // "off" | "busy" ([3/8]) | "free" (nog 5)
  },
  "services": [
    { "id": "…", "title": "Knippen dames", "info": "Wassen, knippen en föhnen",
      "type": "simple",                       // simple | compound | collaborative | package
      "price": 42.5, "deposit": "100%", "taxRate": 21,
      "categoryName": "Knippen", "duration": 45, "durationDays": 0, "capacityMax": 1,
      "staff": [{ "id": "…", "name": "Sanne" }],
      "extras": [{ "id": "…", "title": "Haarmasker", "price": 7.5, "duration": 10,
                   "minQty": 0, "maxQty": 1 }],
      "fields": [{ "id": "…", "label": "Allergieën", "kind": "text",
                   "required": true, "perPerson": true, "options": [], "showIf": null }],
      "oneBookingPerSlot": false,
      "recurrence": ["weekly", "biweekly"]     // [] when the account has recurrence off
    }
  ]
}
```

Service-type-specific fields:

| `type` | Extra fields | `duration` means |
|---|---|---|
| `simple` | — | the slot length |
| `compound` | `parts` (count) | total of all parts + spare time |
| `collaborative` | `parts`, `hideStaff` (bool) | the longest part |
| `package` | `size`, `lifeDays` (nullable), `serviceTitle`, `serviceId` | duration of the appointment it is for |

Behaviour notes:

- Only `visibility = 'public'` services with at least one public staff member are listed. An
  unknown/unbookable `service` id in later calls answers 404, a private/unknown `staff` id yields an
  empty slot list (never a leak).
- Staff lists are the *public* staff that performs the service, in display order. For
  compound/collaborative services only the first part's staff is choosable (`hideStaff` asks the UI
  to hide even that).
- Extras of compound/collaborative services carry `partServiceId`; send them in `extras` exactly as
  for simple services — the server routes each extra to the part that owns it.
- A service with `recurrence: []` cannot be repeated, even when the account has recurrence enabled.
- `fields` are the service's intake questions, in display order (empty array = none). Render them
  before the customer confirms: `required` must be answered, `kind` is
  `text` | `textarea` | `select` | `checkbox` | `number` | `date` | `file` (`options` only for `select`),
  and `perPerson` asks one answer per person. Send the answers back as `fields` on the booking item,
  keyed by field id; the server validates them again and answers 422 when one is missing or wrong.
  A `file` field's answer is the `id` from [`POST uploads`](#post-uploads) — upload first, then send
  the id. The stored answer is `{ "id": "…", "name": "paspoort.png" }`.
  **`showIf`** (`{"field": "<id of an earlier question>", "is": "<answer>"}`, or `null`) makes a
  question conditional: show it only while the referenced answer equals `is` (compare the trimmed
  value — a checkbox is `"true"`/`"false"`, a number is its digits). The server applies the same rule:
  a question whose condition fails is not required, and an answer sent for it is **dropped** rather
  than stored. Send the answers anyway if it is easier — the visibility is the server's call, not yours.

### GET slots

Availability for one item, day by day.

```
GET /api/public/<key>/slots?service=<id>&staff=<id|any>&from=2026-10-14&days=7&persons=1
```

| Query | Default | Notes |
|---|---|---|
| `service` | — | required, uuid |
| `staff` | `any` | optional |
| `from` | today (business time zone) | `YYYY-MM-DD` |
| `days` | `7` | 1–31; larger windows need several calls (`hasMore` tells you if the horizon is not reached) |
| `persons` | `1` | integer |

```jsonc
{
  "days": [
    { "date": "2026-10-14",
      "slots": [
        { "start": "2026-10-14T07:30:00.000Z", "time": "09:30", "staffId": "…",
          "occupied": 3, "capacity": 8,      // only when tenant.showOccupancy ≠ "off"
          "state": "waitlist", "waiting": 2  // only on waiting-list slots; omit otherwise
        }
      ] }
  ],
  "hasMore": true          // false when from+days passed the account's booking horizon (max_days)
}
```

- `state`: absent = bookable; `"waitlist"` = the slot is full but a waiting list is open (ask
  `waitlist_enabled`/`waiting_list_capacity`; send the item back with `waitlist: true` to join).
  Partially filled group slots are simply bookable.
- Only days that have slots appear in `days` (in date order); a day without free times is omitted, and
  so is the array itself when nothing is free in the window. Render your calendar from the dates you
  asked for, not from the returned entries.
- Poll-again advice: on 409 `slot_unavailable`, call `GET slots` for that day and re-render.

#### Day services

A **day service** (a boat, a holiday home, a room; `durationDays` 1–365 on the service, created with the
management API) is rented per whole calendar day. `GET slots` then answers with **day granularity**
instead of times: one entry per free start date, where `start` is that date's local midnight (ISO 8601
with the business offset, e.g. `2026-10-14T00:00:00+02:00`) and `end` is `start` plus `durationDays`
calendar days (again local midnight):

```jsonc
{ "days": [ { "date": "2026-10-14",
  "slots": [ { "start": "2026-10-14T00:00:00+02:00", "time": "00:00", "staffId": "…",
               "end": "2026-10-17T00:00:00+02:00" } ] } ], "hasMore": true }
```

A start date is offered only when **every** day of the span `[start, start + durationDays)` is free for
one staff member: no appointment that blocks (existing bookings and events that block support staff), no
day off for that staff member or the whole account. **Business hours and the weekly schedule do not
apply** — a rental is a day, not a shift. `now + minPriorMinutes`, the `maxDays` horizon and the
per-staff capacity all apply as usual. There is no `occupied`/`capacity` on a day slot.

Booking works like any other item — send the slot's `start` **and** `end` back verbatim; the server
re-checks the whole span inside the transaction, so a second booking overlapping the same staff member's
span is refused with 409 `slot_unavailable`. The price is `staff price × durationDays × persons`.
Day services cannot be combined into a chain or cart (`items` with a day service and any other item →
422), and `POST slots` reports them the same way as `GET slots`.

### POST slots (chain / holds)

For a **chain** (one customer, several services back-to-back, `tenant.chain`) or to search while the
customer already holds items in a cart (`hold`, `tenant.cart`).

```
POST /api/public/<key>/slots
{
  "items": [ { "service": "…", "staff": "any", "persons": 1 } ],   // 1 item = normal, >1 = chain
  "hold":  [ { "service": "…", "staff": "…", "start": "…", "persons": 1 } ],
  "from": "2026-10-14", "days": 7
}
```

Response is the same shape as `GET slots`; chain slots additionally carry
`parts: [{ "service", "staff", "start" }]` — the resolved consecutive appointments. A hold is an item
the user already selected; the search treats it as occupied and never joins it. `hold` items must have
a concrete `staff` id (the `staffId` of their slot) and are ignored for waiting-list/package items.
A day service must be the only item (chain → 422); its response is the same local-midnight span shape
as `GET slots` shows.

### POST recurrence

Plan a recurring series from one chosen slot (spec: Bookly-style repeat with conflict handling).

```
POST /api/public/<key>/recurrence
{
  "item":  { "service": "…", "staff": "any", "start": "2026-10-14T09:30:00.000Z", "persons": 1 },
  "rule":  { "freq": "weekly", "every": 2, "on": [2], "until": "2026-12-31", "count": 10 },
  "hold":  [ … ]
}
```

`rule`:

| Field | Values | Notes |
|---|---|---|
| `freq` | `daily` \| `weekly` \| `biweekly` \| `monthly` | must be offered by the service (`recurrence[]`) |
| `every` | 1–30 | interval, e.g. `weekly` + `every: 2` |
| `on` | array of ISO weekdays 1–7 | for weekly frequencies |
| `monthly` | `{ "day": 14 }` or `{ "nth": 2, "weekday": 2 }` (nth ∈ 1–4, −1 = last) | day 31 skips months without it |
| `until` | `YYYY-MM-DD` | capped at the booking horizon |
| `count` | 1–52 | alternative to `until` |

```jsonc
{ "occurrences": [
  { "date": "2026-10-28", "start": "2026-10-28T09:30:00.000Z", "time": "09:30",
    "staffId": "…", "anotherTime": false, "state": "waitlist"? }
] }
```

`anotherTime: true` means the preferred time was taken and the engine moved the occurrence (same
service, possibly another staff member) on the same day or later, up to `until`. `start: null` means
**no time was found at all** — show it and let the user drop that occurrence. Occurrences on a full
group slot come back with `state: "waitlist"`: send them in the order with `waitlist: true` (and the
same `series` key) if the customer accepts a waiting-list place.

To book a series, send every occurrence as its own item with the **same `series` key** plus
`series: { "<key>": rule }` in the order body (see `POST bookings`).

### POST quote

Price for an order that is already fully resolved (items with `start`). Use it to show the price
before submitting, and again after a coupon is entered. The server never trusts client amounts;
this endpoint and `POST bookings` compute the same numbers.

```
POST /api/public/<key>/quote
{ "items": [ … with "start" … ], "coupon": "WELKOM10", "payFull": false, "gateway": "mollie" }
```

```jsonc
{
  "subtotal": 42.5, "discount": 4.25, "tax": 6.65, "total": 38.25,
  "payNow": 38.25,        // what is asked online now (Mollie) or at the desk
  "due": 0,               // pay later (deposit mode)
  "paidType": "in_full",  // "in_full" | "deposit"
  "coupon": { "code": "WELKOM10", "status": "ok" },   // or "invalid" / "expired", null when not sent
  "items": [{ "price": 42.5, "extras": 0, "payNow": true }],
  "onSite": 0             // amount of recurring occurrences not in this payment ("first" mode)
}
```

### POST uploads

Uploads a customer file for a `file` intake question (see `GET services`). Call this first, then send
the returned `id` as that field's answer in `POST bookings`.

```
POST /api/public/<key>/uploads
Content-Type: multipart/form-data
```

One `file` part. Limits: at most **5 MB**; `image/jpeg`, `image/png`, `image/webp` or
`application/pdf` only.

```jsonc
// 201
{ "id": "7c9e…", "name": "paspoort.png", "size": 84231 }
// 413 { "error": "too_large" }
// 422 { "error": "validation", "fields": { "file": "file must be a JPEG, PNG, WebP or PDF" } }
// 422 { "error": "validation", "fields": { "file": "file is required" } }
```

- The file is stored in a **private** bucket; it is never public. Download links are signed and
  short-lived, so only the admin (and the mail/ICS flows) can read it back.
- An upload that is never used in a booking is **deleted after 24 hours** by the nightly cron. An
  upload can be attached to at most **one** booking: re-using an id answers 422 naming the field.
- The `id` is a uuid; the response is not idempotent — a retried upload makes a second file (the
  first is swept).

### POST bookings

Creates the order. One request = one order = one payment. Under the hood this re-checks every item
against the live schedule and writes everything in one database transaction, so two simultaneous customers
can never get the same seat.

```
POST /api/public/<key>/bookings
{
  "items":  [ … with "start" (and optional "series", "waitlist", "package") … ],
  // answers to the service's intake questions, by field id (see GET services):
  // "fields": { "<fieldId>": "noten", "<perPersonFieldId>": ["noten", "geen"] }
  "series": { "a": { "freq": "weekly", "until": "2026-12-31" } },
  "name": "Ada Jansen", "email": "ada@example.com", "phone": "+31612345678", "notes": "…",
  "gateway": "local",        // "local" | "mollie"; default = first of tenant.gateways
  "coupon": "WELKOM10",
  "payFull": false,          // deposit mode choose_*: pay in full instead of the deposit
  "returnUrl": "https://shop.example.com/bedankt"   // required for Mollie
}
```

The pre-order body shape (`{service, staff, start, persons, name, email, …}` without `items`) is still
accepted for a single booking.

**Responses**

```jsonc
// 201 — booked
{
  "id": "…", "status": "approved", "start": "2026-10-14T09:30:00.000Z",
  "serviceTitle": "Knippen dames", "staffName": "Sanne",     // first item, for single-item clients
  "orderToken": "…",                                          // 48-hex; also used in cancel links
  "fields": { "<fieldId>": "noten" },                         // the stored answers of the first item
  "items": [ { "id": "…", "status": "approved", "start": "…",
               "serviceTitle": "…", "staffName": "…",
               "fields": { "<fieldId>": { "id": "…", "name": "paspoort.png" } } } ],  // file answers store id + name
  "payment": { "status": "pending", "checkoutUrl": "https://www.mollie.com/…" }  // mollie
  // "payment": { "status": "completed" }   free order
  // "payment": { "status": "pending" }     local: admin marks it paid at the desk
}
// 409
{ "error": "slot_unavailable", "item": 0 }
// 422
{ "error": "validation", "fields": { "email": "invalid", "coupon": "invalid" }, "item": 0? }
// 422 — intake question missing or wrong: `fields` maps the *field id* to an English message
{ "error": "validation", "fields": { "9f1c…": "Allergieën is required" }, "item": 0 }
// 422 — file answer: unknown upload id, another account's file, or an id already on another booking
{ "error": "validation", "fields": { "9f1c…": "Allergieën must be an uploaded file id" }, "item": 0 }
```

- `returnUrl` must be http(s), and its origin must be in **Toegestane websites** (when set) or equal
  the request's `Origin` header (when the allowlist is empty). Otherwise `fields.returnUrl = "invalid"`.
- With `gateway: "mollie"` the response's `checkoutUrl` is where you send the browser. The server
  appends `nb_pay=<paymentToken>` to your `returnUrl` when Mollie redirects back — see
  [Payment lifecycle](#payment-lifecycle).
- Confirmation mail: sent immediately for local/free orders; for Mollie orders *after* the payment
  completes (the customer must not get "confirmed" before paying).
- `status` is `pending` or `approved` per the account's default status (Instellingen → Afspraken),
  `waitlisted` for waiting-list items, or the configured success status for a free order when the
  business set one.

### POST bookings/{token}/reschedule

Moves the customer's own booking to another time — the API behind the `/b/<token>` page. The booking
is addressed by its 48-hex `token` (the one in the cancel link the confirmation mail sends; the
management API's `GET /bookings/{id}` also shows it).

```
POST /api/public/<key>/bookings/<token>/reschedule
{
  "start": "2026-10-20T09:30:00.000Z",   // exact `start` of a slot from GET slots
  "staff": "e0000000-…-0001"             // optional: another staff member who offers the service
}
```

```jsonc
// 200 — moved; `start` as requested, `end` keeps the appointment's duration
{ "start": "2026-10-20T09:30:00.000Z", "end": "2026-10-20T10:00:00.000Z" }
// 404 { "error": "not_found" }
// 409 { "error": "cannot_reschedule" }
// 409 { "error": "slot_unavailable" }
// 422 { "error": "validation" }
```

- The booking keeps its service, staff and duration; `staff` moves it to another staff member that
  offers that service.
- The new time is re-checked exactly like a new booking — capacity, overlap, schedule and holidays —
  and there is **no** `force`: a time that does not fit answers 409 `slot_unavailable`. Re-fetch slots
  and pick again.
- The same limit as cancelling applies: the booking must be `pending` or `approved` and the call must
  be at least `cancelMinMinutes` (Instellingen → Bedrijf en e-mail) before the start. Otherwise 409
  `cannot_reschedule`. Waitlisted bookings cannot move; cancel and re-book instead.
- The customer and staff get the usual `status_changed` mails (with the new time and ICS); the old
  slot is free for others immediately.

### GET payments/{token}

```
GET /api/public/<key>/payments/<48-hex token>
```

```jsonc
{
  "status": "completed",     // pending | completed | rejected | refunded
  "booking": { "serviceTitle": "…", "staffName": "…", "start": "…", "durationDays": 0 },   // first booking, or null
  "items": [{ "id": "…", "status": "approved", "start": "…", "durationDays": 0, "serviceTitle": "…", "staffName": "…" }],   // durationDays > 0 = a rental: start → start + that many days
  "attendees": [{ "code": "ABCD-EFGH" }]   // event tickets, only once approved (paid)
}
```

The payment token is what the widget polls after a Mollie redirect. If the status is still `pending`
and the type is `mollie`, this call first asks Mollie directly (webhooks may lag), so polling this
endpoint is a valid replacement for the webhook. Poll every 2 s for up to ~30 s.

### GET packages/{token}

Package overview for the personal link that is mailed on purchase (`/p/<token>` renders it).

```jsonc
{
  "service": { "id": "…", "title": "Knippen heren", "duration": 30, "fields": [ /* the base service's intake questions, same shape as GET services */ ] },
  "packageTitle": "5× Knippen heren",
  "staff": { "id": "…", "name": "Sanne" },        // null = customer picks
  "size": 5, "used": 2, "remaining": 3,
  "expiresOn": "2027-04-01",                       // null = not started yet or never expires
  "firstName": "Ada",
  "visits": [{ "start": "2026-10-14T09:30:00.000Z", "status": "approved" }]
}
```

To schedule a visit, book normally with the item's `"package": "<token>"` field; the visit is not
priced and needs no payment. A visit books the base service, so its **intake questions** apply: the
`fields` above are what to render, and `POST bookings` answers them exactly like an ordinary booking
(including files through `POST uploads`).

### GET events

Published events whose sales are still open.

```jsonc
[{ "id": "…", "title": "Zonsondergangtocht", "info": "…", "imageUrl": null,
   "start": "2026-10-25T17:30:00.000Z", "end": "2026-10-25T19:30:00.000Z",
   "tickets": [{ "id": "…", "title": "Volwassene", "price": 25, "left": 26 }] }]
```

### POST events/{id}/tickets

```
POST /api/public/<key>/events/<eventId>/tickets
{ "tickets": [{ "type": "<ticketTypeId>", "qty": 2 }],
  "name": "…", "email": "…", "phone": "…",
  "gateway": "mollie", "returnUrl": "https://…" }
```

```jsonc
// 201
{ "orderToken": "…",
  "attendees": [{ "code": "ABCD-EFGH" }],   // [] until the order is approved (free = immediately,
                                             //  local = after "Betaling voltooien", mollie = after paying)
  "payment": { "status": "pending", "checkoutUrl": "…" } }
// 409 { "error": "sold_out", "type": "<ticketTypeId>" } | { "error": "sales_closed" }
```

1–20 distinct ticket types per request, 1–50 per type. All tickets in one order are paid in full
(deposits do not apply). Check `GET packages|payments/<token>` for the final codes; the confirmation
mail repeats them. Ticket codes use the event's `ticket_mask` (`****-****` by default) and are unique
per event.

## Retries and Idempotency-Key

A booking request can time out after the server already wrote the order. Retrying blindly would book
twice. Send an **`Idempotency-Key`** header on `POST bookings` and `POST events/<id>/tickets`, and a
retry with the same key returns the original result instead of creating a second order:

```js
const key = crypto.randomUUID();            // one key per checkout attempt, generated before the first try
async function book(body) {
  for (let attempt = 0; attempt < 4; attempt++) {
    const res = await fetch(`${API}/bookings`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json', 'Idempotency-Key': key },
      body: JSON.stringify(body),            // the same body on every attempt
    }).catch(() => null);                    // network error / timeout: retry with the same key
    const busy = res?.status === 409 && (await res.clone().json()).error === 'idempotency_in_progress';
    if (res && res.status < 500 && !busy) return res;   // 201, 409 slot_unavailable, 422 …: final
    await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt));
  }
  throw new Error('booking failed, try again later');
}
```

- **Same key + same body** → the stored response: same status, same body (same `orderToken`, same
  `checkoutUrl`), plus the header `Idempotent-Replayed: true`. Nothing is written again and no second
  mail is sent. Validation errors and `409 slot_unavailable` are replayed too — fix the input and use
  a **new** key.
- **Same key + different body** → `422 {"error":"idempotency_mismatch"}`.
- **Same key while the first request is still running** → `409 {"error":"idempotency_in_progress"}`
  with `Retry-After: 1`.
- A `5xx` answer is **not** stored: the key is released and the retry runs for real.
- Keys are 1–255 visible ASCII characters (a UUID is ideal), scoped to your account, and kept for
  **24 hours**; after that the same key counts as new. Without the header nothing changes.
- "Same body" means byte-identical: build the JSON once and resend that string.

The [management API](../api/README.md) accepts the same header on every `POST`.

## Versioning and rate limits

Every request may carry an **`X-Api-Version`** header; absent means the latest version. The current
(and only) version is `2026-10-13`; an unknown value is answered with
`400 {"error":"bad_request","versions":["2026-10-13"]}`. Every response carries `X-Api-Version` plus
the rate-limit state, except that `400` itself (no version to echo) and `OPTIONS` preflights, which
are free and uncounted:

```
X-Api-Version: 2026-10-13
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1791897600     # epoch seconds: the window resets then
```

Requests are counted per client IP address in a one-minute window: **120/min** in general and
**20/min** for the booking commits (`POST bookings`, `POST bookings/{token}/reschedule`,
`POST events/{id}/tickets`), which lock
schedules, send mail and start payments. Over the limit:

```
HTTP/1.1 429 Too Many Requests
Retry-After: 42

{"error":"rate_limited","retryAfter":42}
```

Wait `Retry-After` seconds before retrying; the counter resets when the minute is over. The limits
live in the server process: a restart resets them, and running more than one instance multiplies
the budget. They slow down runaway scripts, not a determined attacker.

Breaking changes never arrive silently: they get a new dated version, and the previous version stays
supported for **at least six months** (announced with `Deprecation`/`Sunset` headers when that
happens). The generated schema for this version:
[app.nisebookings.com/openapi.json](https://app.nisebookings.com/openapi.json).

## Payment lifecycle

```
                    ┌ free order (total 0) ──────► completed   (mail immediately)
bookings ──────────►├ local ────────────────────► pending     (admin: "Betaling voltooien" → completed)
                    └ mollie ─► createPayment ─► pending     (redirect to checkoutUrl)
                                     │
                     webhook ────────┼──────────► paid      → completed (+ mails)
                        or           │            failed/   → rejected  (+ bookings rejected,
                     poll payments/  │            canceled/    coupon use given back)
                     <token>         │            expired
                                     └ timeout (payment timeout setting,
                                        default 30 min, checked every minute) → sync, then rejected
```

- You only connect your Mollie API key (**Instellingen → Betalingen**). The service registers its own
  Mollie webhook on every payment and reconciles the status; there is nothing to configure on the
  Mollie side.
- A payment that arrives **after** rejection (customer paid too late) restores the bookings if the
  slot is still free; otherwise the admin sees `late_paid` on the payment and refunds manually.
- Refunds are an admin action (Mollie refund API); `GET payments/<token>` then reports `refunded`.

## Integration recipes

### 1. Own front-end instead of the widget (single booking)

```js
const API = 'https://app.nisebookings.com';
const KEY = '<your public key>';
const j = (r) => r.json();

const { tenant, services } = await fetch(`${API}/api/public/${KEY}/services`).then(j);
const svc = services.find((s) => s.title === 'Knippen dames');

const { days } = await fetch(
  `${API}/api/public/${KEY}/slots?service=${svc.id}&from=${todayISO()}&days=14&persons=1`).then(j);
const slot = days.flatMap((d) => d.slots)[0];            // whatever your UI picked

const res = await fetch(`${API}/api/public/${KEY}/bookings`, {
  method: 'POST', headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    items: [{ service: svc.id, staff: slot.staffId, start: slot.start, persons: 1 }],
    name: 'Ada Jansen', email: 'ada@example.com', phone: '+31612345678',
    gateway: 'local',
  }),
});
if (res.status === 409) { /* re-fetch slots; the seat is gone */ }
const order = await res.json();     // order.items[0].status, order.orderToken
```

Always send back the exact `start` you got from `GET slots` and the `staffId` you were shown (or
`"any"`): the server re-resolves and re-checks it. Do not construct times yourself.

### 2. Mollie checkout

```js
const res = await fetch(`${API}/api/public/${KEY}/bookings`, { … body: {
  items, name, email, gateway: 'mollie',
  returnUrl: location.origin + '/booking/thanks',      // origin must be allowed (see above)
}});
const order = await res.json();
location.href = order.payment.checkoutUrl;             // Mollie-hosted payment page
```

Mollie sends the customer back to `returnUrl?nb_pay=<token>`. On your thank-you page, poll
`GET payments/<token>`:

```js
const t = new URLSearchParams(location.search).get('nb_pay');
while (true) {
  const p = await fetch(`${API}/api/public/${KEY}/payments/${t}`).then(j);
  if (p.status !== 'pending') return render(p);        // completed | rejected | refunded
  await new Promise((r) => setTimeout(r, 2000));
}
```

Webhook delay never matters: this endpoint asks Mollie itself while the status is pending.

### 3. Recurring series

```js
const rule = { freq: 'weekly', on: [2], until: '2026-12-31' };          // Tuesdays until that date
const { occurrences } = await fetch(`${API}/api/public/${KEY}/recurrence`, {
  method: 'POST', headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ item: { …firstItem }, rule }),
}).then(j);

const items = occurrences.filter((o) => o.start)
  .map((o) => ({ service: svc.id, staff: o.staffId, start: o.start, persons: 1, series: 'a',
                 ...(o.state === 'waitlist' && { waitlist: true }) }));

await fetch(`${API}/api/public/${KEY}/bookings`, { … body: {
  items, series: { a: rule }, name, email, gateway: 'mollie', returnUrl,
}});
```

The whole series is one order and (with `recurringPayment: "all"`) one payment. With `"first"`,
only the earliest occurrence is charged online; `quote.onSite` shows the rest.

### 4. Waiting list

A full group slot with an open waiting list appears as `{ state: 'waitlist', waiting: n }`. Book it
with `waitlist: true`; the status becomes `waitlisted`, nothing is charged, and when a seat frees the
customer receives a `waitlist_offer` mail with a `/w/<token>` link (first come, first served).

### 5. Sell event tickets

Use `GET events` + `POST events/<id>/tickets` with the same `gateway`/`returnUrl` rules. After the
payment completes, redirect-poll `GET payments/<token>` for the attendee `code`s.

## Rules the server enforces

These are the invariants an integration must not fight — they also explain the error codes.

1. **Never trust the client.** `POST bookings` re-resolves staff, extras, persons and the price from
   the database. Sending a different price, staff or duration changes nothing.
2. **The slot must still be free at commit time.** Every item is re-checked and then
   written inside one transaction that locks that staff member's schedule. Two bookings
   for the same seat can never both succeed: the loser gets 409 `slot_unavailable`.
3. **Capacity and blocking.** A slot is occupied by appointments whose bookings are `pending` or
   `approved`, plus the service's padding before/after, plus extras duration. `capacity_max` is the
   number of persons; a join of an existing group appointment is only allowed when service, start,
   duration, extras and `oneBookingPerSlot` all permit it.
4. **Holds.** Cart items and chain parts the client sends back count as occupied while the user is
   deciding; they are not real appointments and can never be joined.
5. **Time.** All instants are UTC; day boundaries, schedules, holidays and "today" are computed in
   the business time zone. `from`/`until` are business-local dates.
6. **Day services occupy calendar days.** A day service's booking blocks its whole span of days for one
   staff member regardless of hours; the start and end bounds are local midnights, `durationDays` apart,
   and `end` comes from the server's own slot search — a hand-made span is refused with 409.
6. **Rate and size limits.** 60 items per order, 10 chain parts, 52 occurrences, 31 days per slot
   call, 2000-character return URLs and notes, 5 MB per upload (JPEG/PNG/WebP/PDF only). Requests from one IP address are capped at
   **120/min** (booking commits 20/min); send `X-Api-Version` to pin a version — see
   [Versioning and rate limits](#versioning-and-rate-limits).
7. **Idempotency is opt-in.** Without an `Idempotency-Key` header every `POST bookings` creates a
   new order, so a blind retry after a timeout books twice. Send the header and retry with the same
   key — see [Retries and Idempotency-Key](#retries-and-idempotency-key).

## What the API does not do

Deliberately out of scope for the public API (do these through the admin or your own layer):

- No customer accounts or login. Single bookings have a magic cancel/reschedule link
  (`/b/<booking token>`, also the address for `POST bookings/{token}/reschedule`), orders an
  order-level one (`/o/<order token>`), both mailed by the default templates (see `06-notifications.md`).
- No payment method list beyond `local`/`mollie`; no iDEAL/card selection — Mollie's own page does that.
- No statistics endpoints. Configuration that belongs to the business rather than the customer —
  services, staff, schedules, opening hours — lives in the [management API](../api/README.md) (a
  scoped key, called server-side); the rest is the back office.
- No bulk import/export. Outbound [webhooks](10-webhooks.md) (booking, ticket and payment events)
  are registered with the management API, not here (Mollie's payment callbacks are handled by the
  service).
- No event coupons, no gift cards, no tips (not planned).
- **Day services ship in the widget and the admin** (widget 0.4.0): the widget shows a start-date
  picker with the span and the price per day, the admin's service form has **Verhuur (dagen)**, the
  appointment form takes only a date for a rental and the calendar labels the span. Still not included:
  changing the number of days of an existing rental (a booking's span is fixed when it is made — move
  the start or cancel and rebook), and mixing a rental with other items in a chain or cart through the
  API.
# Management API: quickstart for coding agents

With one API key you can take an empty account to bookable without touching the admin. The full reference is
[`openapi.yaml`](openapi.yaml) / [`openapi.json`](openapi.json) (OpenAPI 3.1). Every step below (catalogue from
scratch, a real booking through the public API, cancellation) is covered by an automated end-to-end test.

## 1. Get a key

In the admin, go to **Settings → API → New key**. Pick scopes and copy the key: it is shown **once** (`nk_` + 43 chars).

No account yet, or just testing? `curl -s -X POST https://app.nisebookings.com/api/sandbox` (no auth) creates a
24-hour [sandbox](https://guide.nisebookings.com/08-sandbox.html) and returns an all-scopes `apiKey` plus its `publicKey`. Its mail is never
delivered and its Mollie checkout is a fake page; `DELETE /sandbox` (below) removes it early.

| Scope | Gives |
|---|---|
| `catalog:read` / `catalog:write` | categories, services (+ `/extras`, `/fields`, `/parts`), staff, staff↔service links, schedules, holidays, coupons, events (+ ticket types, event staff) |
| `settings:read` / `settings:write` | `/settings`, `/business-hours`, `/notifications`, `/outbox` (read), `/webhooks` |
| `customers:read` / `customers:write` | `/customers` |
| `bookings:read` / `bookings:write` | `/appointments`, `/bookings`, `/packages`, event attendees, waiting list (`give-seat`) |
| `payments:read` / `payments:write` | `/payments` (+ complete, refund), `PUT/DELETE /settings/mollie-key` |

`write` implies `read`. To configure an account from scratch, use `catalog:write` + `settings:write`; add
`customers:write` + `bookings:write` to plan appointments and `payments:write` for payments and the Mollie key.

```sh
export API=https://app.nisebookings.com/api/v1 KEY=nk_...
H=(-H "Authorization: Bearer $KEY" -H 'Content-Type: application/json')
curl -s "${H[@]}" $API/me     # {"tenant":{"id","name","timeZone","currency"},"scopes":[...]}  (works with any valid key)
```

## 2. Configure

```sh
# Settings (partial). The public key for step 3 comes from here.
curl -s "${H[@]}" -X PATCH $API/settings -d '{"timeZone":"Europe/Amsterdam","minPriorMinutes":60,"maxDays":90}'
curl -s "${H[@]}" -X PUT $API/business-hours -d '{"days":[{"weekday":1,"start":"09:00","end":"18:00"}]}'

# Catalogue
CAT=$(curl -s "${H[@]}" -X POST $API/categories -d '{"name":"Haar"}' | jq -r .id)
SVC=$(curl -s "${H[@]}" -X POST $API/services -d "{\"title\":\"Knippen\",\"categoryId\":\"$CAT\",\"duration\":30,\"price\":25}" | jq -r .id)
# A day-based service (a boat, a room, rented per whole day): add "durationDays": 3 → price × 3 per booking.
# Booked through the public API and the admin; business hours never apply, holidays and existing appointments do.
# POST /appointments takes the local midnight of the first day as start; without end the span is durationDays days.
BOAT=$(curl -s "${H[@]}" -X POST $API/services -d "{\"title\":\"Boot\",\"duration\":1440,\"durationDays\":3,\"price\":150}" | jq -r .id)
STAFF=$(curl -s "${H[@]}" -X POST $API/staff -d '{"fullName":"Anna de Vries","email":"anna@example.com"}' | jq -r .id)
curl -s "${H[@]}" -X PUT $API/staff/$STAFF/services/$SVC -d '{"price":25}'

# Working week (PUT replaces the whole week; a missing weekday = day off; weekday 1 = Monday)
curl -s "${H[@]}" -X PUT $API/staff/$STAFF/schedule \
  -d '{"days":[{"weekday":1,"start":"09:00","end":"17:00","breaks":[{"start":"12:00","end":"12:30"}]}]}'

# Day off: kind once | yearly | exception; staffId null = company-wide
curl -s "${H[@]}" -X POST $API/holidays -d "{\"date\":\"2026-12-25\",\"kind\":\"yearly\",\"staffId\":null}"
```

A service can be booked once it is `public`, has at least one public staff member linked, and that staff member has a schedule.

## 3. Book through the public API (no key, the account's `publicKey`)

```sh
PK=$(curl -s "${H[@]}" $API/settings | jq -r .publicKey); P=https://app.nisebookings.com/api/public/$PK
curl -s "$P/services"
curl -s "$P/slots?service=$SVC&staff=$STAFF&from=2026-10-13&days=7"   # {days:[{date,slots:[{start,time,staffId}]}],hasMore}
curl -s -X POST "$P/bookings" -H 'Content-Type: application/json' \
  -d "{\"items\":[{\"service\":\"$SVC\",\"staff\":\"$STAFF\",\"start\":\"<slot.start>\"}],\"name\":\"Jan\",\"email\":\"jan@example.com\",\"phone\":\"\"}"
```

## 4. Full setup: everything else the admin does

```sh
# Coupons (code stored upper case) and a batch of unique codes from a mask
curl -s "${H[@]}" -X POST $API/coupons -d '{"code":"WELKOM10","discount":10,"usageLimit":100}'
curl -s "${H[@]}" -X POST $API/coupons/generate -d '{"mask":"ZOMER-****","count":20,"discount":15}'

# Extras on a simple service; parts of a compound/collaborative service (replaces all, recalculates duration)
curl -s "${H[@]}" -X POST $API/services/$SVC/extras -d '{"title":"Wassen","price":5,"duration":10}'
curl -s "${H[@]}" -X PUT $API/services/$COMBO/parts -d "{\"parts\":[{\"kind\":\"service\",\"serviceId\":\"$SVC\"},{\"kind\":\"spare_time\",\"minutes\":15}]}"

# Intake questions (replaces all; send an id back to keep it): the widget renders them, the answers ride along
# with the booking item as {"fields":{"<fieldId>":"..."}} and come back on GET /bookings/{id}.
# kind "file" (no options) takes an attachment; its answer is stored as {"id":"<uploadId>","name":"<file>"}
# and the customer uploads through the public API first (POST /api/public/<key>/uploads, ≤5 MB, JPEG/PNG/WebP/PDF).
# showIf {"field":"<earlier id>","is":"<answer>"} makes a question conditional (e.g. only ask the tint when the
# colour is rood); a question whose condition fails is not asked and its answer is not stored.
curl -s "${H[@]}" -X PUT $API/services/$SVC/fields \
  -d '{"fields":[{"label":"Allergieën","kind":"text","required":true,"perPerson":true},{"label":"Kies een kleur","kind":"select","options":["rood","blauw"]}]}'

# Mail templates (codes per type: GET /notifications/codes?type=reminder)
curl -s "${H[@]}" -X POST $API/notifications -d '{"type":"reminder","name":"Herinnering","subject":"Morgen: {service_name}","body":"Tot morgen!","toCustomer":true,"attachIcs":true,"reminderMode":"at_hour","reminderAtHour":18,"reminderDaysBefore":1}'

# Events with ticket types and staff
EVT=$(curl -s "${H[@]}" -X POST $API/events -d '{"title":"Workshop","startAt":"2026-11-20T19:00:00+01:00","endAt":"2026-11-20T21:00:00+01:00","status":"published"}' | jq -r .id)
curl -s "${H[@]}" -X POST $API/events/$EVT/ticket-types -d '{"title":"Standaard","price":25,"quantity":30}'
curl -s "${H[@]}" -X PUT $API/events/$EVT/staff -d "{\"staff\":[{\"staffId\":\"$STAFF\",\"role\":\"organizer\"}]}"

# Customers and appointments
CUS=$(curl -s "${H[@]}" -X POST $API/customers -d '{"fullName":"Jan Jansen","email":"jan@example.com"}' | jq -r .id)
APP=$(curl -s "${H[@]}" -X POST $API/appointments \
  -d "{\"serviceId\":\"$SVC\",\"staffId\":\"$STAFF\",\"customerId\":\"$CUS\",\"start\":\"2026-10-14T09:00:00+02:00\",\"persons\":1,\"notify\":true}")
APP_ID=$(jq -r .id <<<"$APP"); BOOKING=$(jq -r .bookingId <<<"$APP")
curl -s "${H[@]}" -X PATCH $API/appointments/$APP_ID -d '{"start":"2026-10-14T07:00:00+02:00"}'              # 422 warnings (outside schedule)
curl -s "${H[@]}" -X PATCH $API/appointments/$APP_ID -d '{"start":"2026-10-14T07:00:00+02:00","force":true}' # saved anyway
curl -s "${H[@]}" -X PATCH $API/bookings/$BOOKING -d '{"status":"cancelled","notify":true}'
curl -s "${H[@]}" -X DELETE "$API/appointments/$APP_ID?notify=false"
# Bookings on their own: one row per booking with its appointment. Filters: status, from/to (appointment start), customerId, staffId, serviceId
curl -s "${H[@]}" "$API/bookings?customerId=$CUS&status=cancelled"
# A recurring series in one call: 8 weekly appointments sharing a seriesId (the 201 also returns appointmentIds)
curl -s "${H[@]}" -X POST $API/appointments \
  -d "{\"serviceId\":\"$SVC\",\"staffId\":\"$STAFF\",\"customerId\":\"$CUS\",\"start\":\"2026-10-14T09:00:00+02:00\",\"recurrence\":{\"freq\":\"weekly\",\"count\":8}}"

# Packages, payments
curl -s "${H[@]}" -X POST $API/packages -d "{\"customerId\":\"$CUS\",\"serviceId\":\"$PKG_SVC\",\"payment\":\"local\"}"
curl -s "${H[@]}" "$API/payments?status=pending"
curl -s "${H[@]}" -X POST $API/payments/$PAY/complete     # local payment paid at the desk
```

**Warnings and `force`.** Appointment create/update run the admin's checks: overlap with another appointment of the
staff member, duration different from the service, outside the schedule or in a break, on a day off. Any of these →
`422 {"error":{"code":"warnings","fields":{"schedule":"..."}}}` (keys: `overlap`, `duration`, `schedule`, `holiday`).
Resend with `"force": true` to save anyway. Hard limits are not warnings: capacity (`409 capacity_exceeded`), a slot
taken in the meantime (`409 slot_unavailable`), package problems (`422 package_used_up|package_expired|package_invalid`).

**`notify`.** `POST /appointments`, `POST /appointments/{id}/bookings`, `PATCH /bookings/{id}`, `POST /bookings/{id}/give-seat`
and `POST /packages` take `notify` in the body; `DELETE /appointments/{id}?notify=true`. (`PATCH /appointments/{id}` does not mail.)
`true` mails the customer exactly like the admin's "inform the customer" checkbox; staff/admin mails follow the
account's notification templates as in the admin. Default `false`, except `POST /packages` (default `true`, package_new).

**Series.** `POST /appointments` with a `recurrence` object (`freq`, plus `every`/`on`/`monthly`, and `count` ≤ 52
or `until`) creates the whole series in one call: one appointment per occurrence, all sharing one `seriesId`
(returned with `appointmentIds`). Every occurrence is checked like a single creation, so warnings name the date they
are about and `force: true` accepts them; the cap is 52 occurrences. `PATCH /appointments/{id}`, `PATCH /bookings/{id}`
and `DELETE /appointments/{id}` take `scope` `this` (default) | `following` | `series` for recurring bookings.

**Outbox: verify mails.** `GET /outbox` (scope `settings:read`) lists the mails the account sent or queued, newest first:
`id, status, toEmail, toName, subject, text, html, createdAt, sentAt, lastError`. Filters `status` and `to`, `limit` ≤ 100.
Statuses: `pending`, `sending`, `sent`, `failed`, and `suppressed` — a sandbox never delivers mail, so all its rows end there.

```sh
curl -s "${H[@]}" "$API/outbox?to=jan@example.com&limit=5"
```

**Sandbox.** `DELETE /sandbox` (any scope) deletes the calling key's sandbox account and everything in it → `204`; the key
is dead afterwards. On a real account it answers `404`. In a sandbox, Mollie payments use a fake checkout page and
`POST /payments/{id}/refund` succeeds without contacting Mollie. See [Sandbox](https://guide.nisebookings.com/08-sandbox.html).

**Webhooks.** Register an `https://` URL and get a signed `POST` (Standard Webhooks headers `webhook-id`,
`webhook-timestamp`, `webhook-signature`) for `booking.created|updated|cancelled`, `ticket.created|approved|cancelled`
and `payment.completed|failed|refunded`, whatever made the change. Scope `settings:write`; the `secret` (`whsec_…`) is
returned once. Retries with backoff for ~39 h, a deliveries log with manual retry, a test `ping`, secret rotation.
Payloads, verification code and retry rules: [Webhooks](https://guide.nisebookings.com/10-webhooks.html).

```sh
HOOK=$(curl -s "${H[@]}" -X POST $API/webhooks -d '{"url":"https://shop.example.com/hooks/nise","events":["booking.created","booking.cancelled"]}' | jq -r .id)
curl -s "${H[@]}" -X POST $API/webhooks/$HOOK/test                 # sends a `ping`
curl -s "${H[@]}" "$API/webhooks/$HOOK/deliveries?limit=5"          # what was sent, with status and attempts
```

**Mollie key.** `PUT /settings/mollie-key {"key":"test_..."}` (scope `payments:write`) stores it encrypted and returns
only `{"hint"}`. It is write-only: no endpoint ever returns the key. `DELETE /settings/mollie-key` removes it.
Set it before `PATCH /settings {"payMollieEnabled":true}`.

## 5. Or let your coding agent do it: MCP

The same API is available as a hosted MCP server at `https://app.nisebookings.com/api/mcp`, with the same
`nk_` key and scopes. Connect Claude Code, Codex, Cursor or VS Code and ask in plain language:

```sh
claude mcp add --transport http nise-booking https://app.nisebookings.com/api/mcp --header "Authorization: Bearer $NISE_API_KEY"
```

Tool list, the config for each client and the error behaviour: [`mcp.md`](mcp.md).

## Conventions

- **Retries: `Idempotency-Key`.** Every `POST` accepts an `Idempotency-Key` header (1–255 visible ASCII characters;
  a UUID). Retrying with the same key and the same body returns the stored response with `Idempotent-Replayed: true`
  instead of running again, so a timeout never creates a second customer, appointment or payment action. The same key
  with a different body → `422 idempotency_mismatch`; while the first request is still running → `409
  idempotency_in_progress` (`Retry-After: 1`); a malformed key → `400 bad_request`. `5xx` responses are not stored
  (the retry runs for real). Keys are per account and expire after 24 hours. Without the header nothing changes.

  ```sh
  IK=$(uuidgen)
  curl -s "${H[@]}" -H "Idempotency-Key: $IK" -X POST $API/customers -d '{"fullName":"Jan Jansen","email":"jan@example.com"}'
  curl -si "${H[@]}" -H "Idempotency-Key: $IK" -X POST $API/customers -d '{"fullName":"Jan Jansen","email":"jan@example.com"}' | grep -i idempotent-replayed
  ```

- **Versioning and rate limits.** Every request may carry `X-Api-Version: 2026-10-13`; without the
  header the latest version is assumed, an unknown value is `400 bad_request`. Every response carries
  `X-Api-Version`, except that `400` (rejected before a version is resolved). Requests are counted per
  API key at **120/min**; over the limit → `429 rate_limited` with `Retry-After` (seconds) and
  `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`
  (epoch seconds). The counters live in the server process — a restart resets them and extra instances
  multiply the budget. A breaking change gets a new dated version; the previous one stays supported for
  at least six months (`Deprecation`/`Sunset` headers when that happens). The spec as JSON:
  `GET /api/v1/openapi.json` (generated from `openapi.yaml`, `npm run docs:openapi`).
- **JSON, camelCase** field names. Unknown fields are ignored. PATCH merges into the current values.
- **Timestamps** in responses are RFC 3339 in UTC with `Z` (`2026-10-14T07:00:00Z`, `createdAt` may carry
  fractional seconds); dates are `YYYY-MM-DD`, wall-clock times `HH:MM`. Requests accept any offset (`2026-10-14T09:00:00+02:00`).
- **Errors**: `{"error":{"code","message","fields?"}}`. Codes: `bad_request` 400 (body is not a JSON object; or an unknown `X-Api-Version`), `unauthorized` 401,
  `forbidden` 403 (missing scope), `not_found` 404 (also for ids from another account), `conflict` 409 (still in use),
  `idempotency_in_progress` 409, `idempotency_mismatch` 422,
  `validation` 422 (`fields`: camelCase field → message), `warnings` 422 (see above), `capacity_exceeded` /
  `slot_unavailable` 409, `package_*` 422, `rate_limited` 429, `server` 500. Messages are English; `fields` maps each camelCase field to its message.
  (The public API uses its own shape: `{"error":"validation","fields":{...}}`, `409 slot_unavailable`.)
- **Pagination**: list endpoints take `limit` (1–100, default 50) and `offset` and return `{data, total}`.
- Every write that reaches the database is audited per key (Settings → API shows recent entries); a request rejected by the rate limit is not audited, and neither is `DELETE /api/v1/sandbox` (its audit row would be deleted with the tenant). Responses are `Cache-Control: no-store`; no CORS, so call from a server.
- Not available: creating real accounts (only [sandboxes](https://guide.nisebookings.com/08-sandbox.html), via `POST /api/sandbox`), dashboard stats (`/stats`). The calendar is `GET /appointments?from=&to=`.
# MCP server: operate your account from your coding agent

nisebookings runs a hosted [Model Context Protocol](https://modelcontextprotocol.io) server on top of the
[Management API](README.md). Connect Claude Code, Codex, Cursor or VS Code to it and the agent can read
your catalogue, find free times, plan and change appointments, and configure the account with tool calls —
the same operations, scopes and validation as `/api/v1`, without writing HTTP code.

| | |
|---|---|
| Endpoint | `https://app.nisebookings.com/api/mcp` |
| Transport | Streamable HTTP, stateless: `POST` one JSON-RPC message, `application/json` response (no SSE, no session id) |
| Auth | `Authorization: Bearer nk_…` — a Management API key. OAuth is not supported yet. |
| Protocol versions | `2025-06-18` (default), `2025-03-26`, `2024-11-05` |

## 1. Get a key

In the admin, go to **Settings → API → New key** and pick the scopes the agent may use (table in the
[Management API quickstart](README.md#1-get-a-key)). The key is shown **once**. Every tool call is checked
against the key's scopes exactly like the REST call it maps to: a missing scope comes back as a tool
error with status `403`, not as a connection failure, so a read-only key is a safe way to start.

| You want the agent to… | Scopes |
|---|---|
| look around (catalogue, schedules, settings, appointments) | `catalog:read`, `settings:read`, `customers:read`, `bookings:read` |
| plan, move and cancel appointments | add `customers:write`, `bookings:write` |
| set up services, staff, schedules, opening hours, coupons | add `catalog:write`, `settings:write` |
| look at or complete payments | `payments:read` / `payments:write` |

**Just trying it?** `curl -s -X POST https://app.nisebookings.com/api/sandbox` (no auth) returns a 24-hour
[sandbox account](https://guide.nisebookings.com/08-sandbox.html) with an all-scopes `apiKey` — connect MCP with that. At most **5 per hour per IP**; over that you get `429 {"error":{"code":"rate_limited"}}` and both the `Retry-After` header and the message say how long to wait (a sliding window, so usually a minute or two, not a full hour). Its mail is
never delivered; `list_outbox` shows what would have been sent.

Keep the key out of version control: every snippet below reads it from an environment variable or a
prompt. Revoke it in **Settings → API** when you no longer need it; every write that reaches the
database is audited per key (rate-limited rejections and the sandbox delete are not).

## 2. Connect

### Claude Code

```sh
claude mcp add --transport http nise-booking https://app.nisebookings.com/api/mcp \
  --header "Authorization: Bearer $NISE_API_KEY"
```

The shell expands `$NISE_API_KEY` once, so the key is stored in your user config (`~/.claude.json`), not
in the project. To share the server with a team, commit a `.mcp.json` that expands the variable at
start-up instead, so each member uses their own key:

```json
{
  "mcpServers": {
    "nise-booking": {
      "type": "http",
      "url": "https://app.nisebookings.com/api/mcp",
      "headers": { "Authorization": "Bearer ${NISE_API_KEY}" }
    }
  }
}
```

Check with `claude mcp list`, or `/mcp` inside a session.

### Cursor (`.cursor/mcp.json` or `~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "nise-booking": {
      "url": "https://app.nisebookings.com/api/mcp",
      "headers": { "Authorization": "Bearer ${env:NISE_API_KEY}" }
    }
  }
}
```

### Codex (`~/.codex/config.toml`)

```toml
[mcp_servers.nise-booking]
url = "https://app.nisebookings.com/api/mcp"
bearer_token_env_var = "NISE_API_KEY"
```

Codex sends `Authorization: Bearer <value of NISE_API_KEY>`. Export the variable in the shell that starts
Codex. A trusted project can use `.codex/config.toml` instead.

### VS Code / GitHub Copilot (`.vscode/mcp.json`)

```json
{
  "inputs": [
    { "type": "promptString", "id": "nise-api-key", "description": "nisebookings API key (nk_…)", "password": true }
  ],
  "servers": {
    "nise-booking": {
      "type": "http",
      "url": "https://app.nisebookings.com/api/mcp",
      "headers": { "Authorization": "Bearer ${input:nise-api-key}" }
    }
  }
}
```

VS Code asks for the key once and stores it securely; the file itself holds no secret and can be committed.

### Any other client

Any MCP client that supports Streamable HTTP with a custom header works. To check the endpoint by hand:

```sh
curl -s https://app.nisebookings.com/api/mcp -H "Authorization: Bearer $NISE_API_KEY" \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## 3. Tools

Tool names are snake_case; arguments are camelCase and go to the Management API unchanged, so the field
names, defaults and error codes in [`openapi.yaml`](openapi.yaml) and the [quickstart](README.md) apply.
Read-only tools carry `readOnlyHint`; deletes and whole-object replacements carry `destructiveHint`, so
clients can auto-approve reads and ask before anything changes. `whoami` and `find_slots` work with any
valid key. The client gets each tool's full description and JSON Schema from `tools/list`.

Everything else under `/api/v1` — extras, compound-service parts, notification templates, events and
ticket types, packages, coupon edits, payment completion and refunds, the Mollie key, webhook edits,
secret rotation and delivery retries — goes through
**`api_request`** `{method, path, query?, body?}` with `path` relative to `/api/v1` (for example
`{"method":"POST","path":"/services/<id>/extras","body":{"title":"Wassen","price":5}}`). Its description
lists every route.

<!-- tools:start (generated from the server's tool list) -->
| Tool | Does | Scope | Kind |
|---|---|---|---|
| `whoami` | Who am I | any key | read |
| `list_services` | List services | catalog:read | read |
| `get_service` | Get service | catalog:read | read |
| `create_service` | Create service | catalog:write | write |
| `update_service` | Update service | catalog:write | write |
| `list_categories` | List categories | catalog:read | read |
| `list_staff` | List staff | catalog:read | read |
| `get_staff` | Get staff member | catalog:read | read |
| `create_staff` | Create staff member | catalog:write | write |
| `update_staff` | Update staff member | catalog:write | write |
| `get_staff_schedule` | Get staff schedule | catalog:read | read |
| `set_staff_schedule` | Replace staff schedule | catalog:write | write (destructive) |
| `list_staff_services` | List services of a staff member | catalog:read | read |
| `assign_staff_service` | Assign service to staff member | catalog:write | write |
| `unassign_staff_service` | Unassign service from staff member | catalog:write | write (destructive) |
| `get_business_hours` | Get business hours | settings:read | read |
| `set_business_hours` | Replace business hours | settings:write | write (destructive) |
| `list_holidays` | List days off | catalog:read | read |
| `add_holiday` | Add day off | catalog:write | write |
| `delete_holiday` | Delete day off | catalog:write | write (destructive) |
| `get_settings` | Get settings | settings:read | read |
| `update_settings` | Update settings | settings:write | write |
| `list_customers` | List customers | customers:read | read |
| `get_customer` | Get customer | customers:read | read |
| `create_customer` | Create customer | customers:write | write |
| `update_customer` | Update customer | customers:write | write |
| `list_appointments` | List appointments | bookings:read | read |
| `get_appointment` | Get appointment | bookings:read | read |
| `create_appointment` | Create appointment | bookings:write | write |
| `update_appointment` | Reschedule / update appointment | bookings:write | write |
| `delete_appointment` | Delete appointment | bookings:write | write (destructive) |
| `add_customer_to_appointment` | Add customer to appointment | bookings:write | write |
| `update_booking` | Update booking status | bookings:write | write (destructive) |
| `find_slots` | Find free slots | any key | read |
| `list_outbox` | List sent e-mails | settings:read | read |
| `list_payments` | List payments | payments:read | read |
| `get_payment` | Get payment | payments:read | read |
| `list_events` | List events | catalog:read | read |
| `list_coupons` | List coupons | catalog:read | read |
| `generate_coupons` | Generate coupons | catalog:write | write |
| `list_webhooks` | List webhook endpoints | settings:read | read |
| `create_webhook` | Create webhook endpoint | settings:write | write |
| `delete_webhook` | Delete webhook endpoint | settings:write | write (destructive) |
| `test_webhook` | Send test webhook | settings:write | write |
| `list_webhook_deliveries` | List webhook deliveries | settings:read | read |
| `api_request` | Raw management API request | per route | write (destructive) |
<!-- tools:end -->

## 4. Results and errors

- A tool result is the API's JSON response as text (and as `structuredContent` when it is an object).
  A `204` comes back as `ok`.
- An API error is a tool result with `isError: true` and the API's error body plus its HTTP `status`:
  `403 forbidden` (scope missing), `404 not_found`, `409 slot_unavailable` / `capacity_exceeded`,
  `422 validation` (see `fields`) and `422 warnings`.
- **Warnings and `force`.** Creating or moving an appointment runs the admin's checks (overlap, duration,
  outside the schedule or in a break, day off). Any of these returns `422 warnings` with the reasons in
  `fields`. Show them to the human; resend with `force: true` only when they agree.
- **`notify`** defaults to `false` on appointment and booking writes, so the agent never mails a customer
  unless asked.
- Lists take `limit` (1–100, default 50) and `offset` and return `{data, total}`.
- **Webhooks.** `create_webhook` returns the signing `secret` (`whsec_…`) once — hand it to the human or
  store it where the receiver reads it. Then `test_webhook` and, a second later, `list_webhook_deliveries`
  to see whether the receiver answered 2xx. Payloads and verification:
  [Webhooks](https://guide.nisebookings.com/10-webhooks.html).
- A missing or invalid key fails the whole HTTP request with `401` and `WWW-Authenticate: Bearer`; the
  client shows the server as failed to connect.

## 5. Verify the connection

Ask the agent: *"Use nise-booking: who am I, and what are the next free times for the first service?"*
It should call `whoami`, `list_services` and `find_slots`. If the client reports the server as failed,
the key is missing, wrong or revoked (401). If a tool returns `403`, the key lacks that scope.

The whole flow (initialize, tool list, slot search, customer + appointment create/update/delete, scope
check) is covered by an automated end-to-end test.

## Limits

- API keys only; OAuth (and therefore "Connect" buttons in hosted assistants such as claude.ai) is not
  supported yet.
- No resources, prompts or server-sent notifications — tools only, and the tool list does not change.
- One JSON-RPC message per request (no batches). Browser origins other than the app's own are refused.
- MCP calls run through the same handlers in process: `/api/v1` tool calls share the key's
  **120 requests/min** budget (per server process) and always speak the latest API version, while the
  public-API tools (`find_slots`, …) have no client address and are counted per tenant, not per key.
- Not available through MCP either: creating accounts (a sandbox is created with `POST /api/sandbox`, no key)
  and dashboard statistics. Deleting a sandbox early: `api_request` `{"method":"DELETE","path":"/sandbox"}`.
# Admin guide (back office)

The back office lives at `/app` in the application. Everything in this guide is Dutch in the UI; the
Dutch labels are quoted so you can find them. For how the engine behaves underneath, see
[`02-concepts.md`](02-concepts.md).

## Contents

- [Roles and what each one sees](#roles-and-what-each-one-sees)
- [First-time setup](#first-time-setup)
- [Daily work: the calendar](#daily-work-the-calendar)
- [Appointments](#appointments)
- [Services](#services)
- [Staff](#staff)
- [Customers](#customers)
- [Packages](#packages)
- [Events](#events)
- [Payments](#payments)
- [Coupons](#coupons)
- [Notifications](#notifications)
- [Settings](#settings)
- [Public pages your customers see](#public-pages-your-customers-see)
- [Known limitations](#known-limitations)

## Roles and what each one sees

Four roles exist: `owner`, `admin`, `front_desk`, `staff`. The nav shows only what the role may use;
everything else redirects to the role's home (the dashboard, or the calendar for roles without one).

| Menu item (Dutch) | Route | owner | admin | front_desk | staff |
|---|---|---|---|---|---|
| Overzicht | `/app` | ✓ | ✓ | – | – |
| Agenda | `/app/calendar` | ✓ | ✓ | ✓ | ✓ (own agenda) |
| Afspraken | `/app/appointments` | ✓ | ✓ | ✓ | ✓ (own agenda) |
| Klanten | `/app/customers` | ✓ | ✓ | ✓ | – |
| Pakketten | `/app/packages` | ✓ | ✓ | ✓ | – |
| Evenementen | `/app/events` | ✓ | ✓ | view only | – |
| Diensten | `/app/services` | ✓ | ✓ | – | – |
| Medewerkers | `/app/staff` | ✓ | ✓ | – | – |
| Betalingen | `/app/payments` | ✓ | ✓ | ✓ | – |
| Kortingscodes | `/app/coupons` | ✓ | ✓ | – | – |
| Meldingen | `/app/notifications` | ✓ | ✓ | – | – |
| Instellingen | `/app/settings` | ✓ | ✓ | – | – |

Two extra gates:

- **Payment settings and the Mollie key** can only be changed by owner/admin. Everyone else sees the
  payments tab disabled with "Alleen een eigenaar of beheerder kan dit wijzigen."
- A **staff** login is linked to one or more `staff` records (`staff.user_id`); they only see and
  change appointments of those staff members, and cannot move an appointment to another staff member.
  Unlinked they see "Je account is nog niet aan een medewerker gekoppeld."

> There is **no user-management screen yet**: you cannot invite colleagues or change roles in the UI.
> Contact nisebookings to add a colleague (with one of the four roles) or to change a role.

## First-time setup

After signing up (`/signup`) you land on `/onboarding` ("Je bedrijf"): fill in **Bedrijfsnaam**,
**Webadres** (slug: lowercase letters, digits, hyphens) and **Tijdzone**, then "Verder". This creates
your account, makes you owner, and installs the default Dutch e-mail templates. You start with no
services or staff.

Recommended order:

1. **Instellingen → Algemeen** — company name, time zone, time step, how far ahead customers may book.
2. **Instellingen → Openingstijden** — the weekly template that new staff inherit.
3. **Instellingen → Vrije dagen** — company-wide closing days.
4. **Medewerkers** — add the people/resources. Each new staff member gets the opening hours as their
   weekly schedule.
5. **Diensten** — add what can be booked, and tick which staff perform it (Medewerkers → Diensten).
6. **Instellingen → Bedrijf en e-mail** — sender name, reply-to, phone/address/website (used in mails).
7. **Instellingen → Boekingsformulier** — cart, chain, recurrence, occupancy display, waiting list.
8. **Instellingen → Betalingen** — VAT inclusive/exclusive, deposit mode, local/Mollie, Mollie API key.
9. **Instellingen → Insluiten** — copy the embed snippet to your website, restrict allowed websites.
10. Test: book something yourself through the widget, then watch **Meldingen → Verzendlog**.

## Daily work: the calendar

`/app/calendar` — the default landing page for front desk and staff.

- Views: **Dag** / **Week** / **Maand** (week by default). **Vorige** / **Vandaag** / **Volgende**,
  a date field, and selects for **Medewerker** and **Dienst**. Keyboard: ← / → / T (today).
- Click an empty grid cell → **Afspraak maken** prefilled with staff, date and time (snapped to the
  time step).
- Colours follow the booking status; cancelled/rejected appointments are muted and struck through.
  Mixed-status appointments are labelled "Gemengd"; an appointment without customers shows
  "Geen klant"; a recurring appointment carries a "reeks" marker; groups show "N pers."
- Events of staff linked to them appear as blocks ("Evenement").
- A rental (Verhuur ≥ 1 day) fills the whole day on every covered day and is labelled "N dagen"
  instead of a clock time.
- Grey areas are times outside the staff's schedule, breaks, and holidays.
- Week view hides non-business days when *Alleen werkdagen tonen* is on; day view hides staff without
  appointments when *Medewerkers zonder afspraken verbergen* is on; visible hours follow opening hours
  when *Alleen de uren binnen de openingstijden tonen* is on (all in **Instellingen → Agenda**).

## Appointments

### List — `/app/appointments`

Tabs **Komend** / **Voorbij**, status tabs (Alle statussen, In afwachting, Bevestigd, Geannuleerd,
Afgewezen, Afgerond, Wachtlijst). Each row shows date/time, service, staff and note, then per customer:
name, "N personen", a payment badge (Betaald / Aanbetaling / Open), an inline status select, the
**Klant mailen** checkbox (on by default) and **Opslaan**. The appointment itself can be deleted
("Deze afspraak en de boekingen erin verwijderen?"). 50 rows per page.

### Create — `/app/appointments/new`

Needs at least one simple service and one staff member. Fields: **Dienst**, **Medewerker**, **Datum**,
**Begintijd**, **Personen**, **Status** (default = Instellingen → Afspraken), a customer block
("Bestaande klant" from the first 200 matches, or "Nieuwe klant" with Naam/E-mailadres/Telefoon — an
existing e-mail address is matched and reused), **Interne notitie**, and two checkboxes:
**Toch inplannen bij een waarschuwing** and **Klant mailen**.

With `?package=<id>` (from a package page) the service, customer and persons are fixed to the package.

### Edit — `/app/appointments/[id]`

- **Details**: staff, service, date, start and end time (end follows start + service duration until
  you change it), internal note. A rental shows only the date — it always starts at 00:00 and runs the
  service's number of days.
- **Live warnings** after you change something: overlap with another appointment, duration differing
  from the service, outside the schedule/breaks, or a holiday. These are non-blocking: the button
  becomes **Toch opslaan**. Blocking errors are capacity ("Dat past niet: deze medewerker heeft bij
  deze dienst plek voor maximaal N personen, dit worden er M."), end before start, or a staff member
  that does not offer the service.
- **Klanten**: shows "X van maximaal Y plaatsen bezet" (only In afwachting and Bevestigd count) and the
  waiting-list count. Per customer: persons, status, **Klant mailen**, Opslaan, and **Verwijderen**
  (no mail is sent). Under the customer you also see the answers to the service's **Velden**
  ("Vraag: antwoord", per-person answers joined per person; a deleted question shows its raw id).
  A file answer is a link to the upload, opening in a new tab; the link is short-lived, and once the
  file is deleted the stored name is shown without one.
  Waitlisted customers get **Plaats geven** (refused when the slot is full:
  "Er is geen plek: N van M plaatsen zijn bezet."). Adding a customer uses the same existing/new block.
  Empty state: "Nog geen klanten. De tijd blijft wel bezet." — an appointment without bookings still
  blocks its time.
- **Recurring**: when the booking belongs to a series, a scope select appears — **Alleen deze** /
  **Deze en volgende** / **Hele reeks**. Other occurrences shift by the same number of days and adopt
  the new start time, keeping their own duration, staff and service. Partial results are reported
  ("N van M andere afspraken in de reeks gewijzigd; de rest mocht je niet wijzigen of bestond niet meer.").
- **Compound/collaborative**: "Onderdeel van {service} — N delen. Een statuswijziging geldt voor alle delen."
- **Delete**: checkbox **Klanten informeren** (on): approved bookings are cancelled, pending ones
  rejected, each mailed; other statuses get no mail. For series/appointments you choose the scope, and
  a booking that was moved out of the series is kept.

## Services

`/app/services` — grouped by category ("Zonder categorie" for uncategorised). Badges: Samengesteld,
Samenwerkend, Pakket, "Verborgen", "tot N personen". **Dienst toevoegen** starts with a type, which
cannot be changed later:

| Type (UI) | What it is | Needs |
|---|---|---|
| **Gewone dienst** | one appointment with one staff member, optional extras | duration, price, capacity |
| **Samengesteld** | parts one after another (wash → cut → dry), with spare-time rows | ordered parts |
| **Samenwerkend** | parts at the same time by different staff (skipper + boat) | ordered parts, one per staff |
| **Pakket** | prepaid bundle of N appointments of one simple service | base service, size, validity |

Common fields: **Naam**, **Categorie**, **Omschrijving**, **Zichtbaarheid** (Zichtbaar voor klanten /
Verborgen, alleen intern te boeken), **Aanbetaling** ("100%", "30%" or a fixed amount per person),
**Btw-tarief** (21 / 9 / 0 / Ander tarief).

Simple services add: **Duur (minuten)**, **Verhuur (dagen)** (0 = an ordinary appointment with times;
1 or more = whole-day rentals — see below), **Tijdstap (minuten)** ("Leeg = standaard (N min)"),
**Prijs (EUR)**, **Minimaal/Maximaal aantal personen**, **Tijd vooraf** and **Tijd achteraf**
(preparation/cleanup; blocks the calendar but is invisible to customers), **Eén boeking per
tijdslot**, **Herhalen** (Dagelijks / Wekelijks / Om de week / Maandelijks; none ticked = no repeats),
**Wachtlijst (maximaal aantal personen)** (empty = unlimited, 0 = off), and **Als de klant geen
medewerker kiest** (Goedkoopste / Duurste / Volgorde van de medewerkerslijst).

**Verhuur (dagen) ≥ 1** turns the service into a rental: the customer picks a start date, the
appointment covers that whole day plus the following days, and the price is the daily price times the
number of days. Business hours and the weekly schedule never apply to a rental — days off and existing
appointments do. An appointment you make yourself for a rental always starts at 00:00 on the chosen
date; extra's, chains and the waiting list do not apply, and the calendar shows the span as "N dagen"
on every covered day.

Sections below the form:

- **Onderdelen** (compound/collaborative): ordered rows of service or **Vrije tijd (minuten)**, plus
  the flags *Alle onderdelen bij dezelfde medewerker* / *Alle onderdelen even lang bezet*.
- **Extra's** (simple services): Naam, Prijs, Extra minuten, Min., Max., Volgorde. Minimaal 1 makes it
  mandatory. Existing bookings keep the extras they were booked with.
- **Velden** (every service): the intake questions the customer answers in the booking form. Per row:
  **Vraag** (the label), **Soort** (Tekst / Tekstvak / Keuzelijst / Aanvinkvakje / Getal / Datum /
  Bestand), **Keuzes** (one per line, only for a Keuzelijst: 1–20 choices of 1–100 characters),
  **Volgorde**, **Verplicht** (the customer cannot book without an answer) and **Per persoon** (one
  answer per person), plus **Toon alleen als** + **Antwoord**: pick an earlier question and the answer
  that should reveal this one (e.g. "Kleur = rood", a checkbox with "aangevinkt" = `true`, a number as
  `3`). A question whose condition does not hold is not shown, not required and not stored; the
  controlling question must be earlier in the list, unconditional and not per-person or a file.
  Answers show on the appointment and can be mailed with `{fields}`.
  A **Bestand** question takes one file of at most 5 MB (JPG, PNG, WebP or PDF). The file is stored
  with the booking and opens from the appointment page through a short-lived link; in a mail
  `{fields}` shows the file name only. Deleting a question keeps the answers on existing bookings;
  without a label such an answer shows its raw id.
- **Categorieën** (on the list page): rename, delete (services survive), add.

Prices are per staff member (Medewerkers → Diensten); the service price is the fallback.

## Staff

Staff is a generic "bookable resource": a person, a room, a boat, a device. `/app/staff` has **Actief**
and **Gearchiveerd** tabs, with **Verborgen** for private staff.

On a staff page:

- **Gegevens**: naam, e-mail, telefoon, omschrijving, zichtbaarheid.
- **Diensten**: which services this staff member performs, with per-staff **Prijs**, **Min./Max.
  personen** and **Aanbetaling** (empty = follow the service).
- **Rooster**: fixed weekly hours (Open / Van / Tot / Pauzes per weekday). Breaks are written as
  `12:00-12:30`, several separated by commas. A day with Open off is a day off. New staff start with
  the company opening hours — later changes to opening hours do not touch existing staff.
- **Vrije dagen**: per-date rows, "Eenmalig" / "Elk jaar" / "Toch open (uitzondering op een jaarlijkse
  vrije dag)". These come on top of the company holidays. Deleting an archived staff member is not
  possible; archiving keeps history.

## Customers

`/app/customers` — search on name, e-mail or phone. Detail page shows and edits Naam, E-mailadres,
Telefoon, Notities, plus the appointment history and **Klant verwijderen**
("Deze klant en al zijn boekingen verwijderen? Dit kun je niet ongedaan maken.").

Customers are created automatically on booking (matched on e-mail within your account).

## Packages

`/app/packages` lists bought packages: customer, package, staff, scheduled visits, validity
("Vanaf de eerste afspraak" until the first visit is planned).

- **Pakket aanmaken**: package service, optional staff ("Nog niet kiezen"), customer, **Betaling**
  ("Ter plaatse betalen (open betaling)" or "Geen betaling" — an open payment is completed later at
  Betalingen), note, **Klant mailen** (sends the `package_new` mail with the personal link).
- Package detail: **Afspraak inplannen** (only while visits remain and it has not expired) opens
  `/app/appointments/new?package=<id>`; **Persoonlijke link** with a copy button; the visit list.
- Validity starts at the first planned visit: that date + the package's life days. Persons are fixed
  to 1 and only the package's own service can be planned. Errors: "Alle N afspraken van dit pakket
  zijn al ingepland.", "Dit pakket was geldig tot en met {datum}. Kies een eerdere datum."

## Events

`/app/events` — Komend / Voorbij. An event has **Titel**, **Status** (Gepubliceerd, te koop /
Verborgen), **Omschrijving**, **Afbeelding (webadres)**, start/end, **Verkoop stopt op** (empty = until
the start), a **Ticketcode** mask (each `*` becomes a random character, at least 4), and
**Medewerkers** (Niet betrokken / Organisator / Ondersteuning (agenda geblokkeerd)) — organisers simply
show in the calendar; only **Ondersteuning** has their time blocked for bookings while the event runs.

**Tickettypes**: Naam, Prijs, Btw %, Aantal, Gereserveerd ("Gereserveerde tickets worden niet online
verkocht"), Volgorde. Deleting an event is refused once tickets are sold — hide it instead.

**Deelnemers** (`/app/events/[id]/attendees`): Code, Klant, Ticket, Status (Wacht op betaling /
Geldig / Geannuleerd), Betaling. **Annuleren** frees the ticket for resale and sends no mail.

## Payments

`/app/payments` — newest first, filter by status (Open / Voltooid / Mislukt / Terugbetaald) and type
(Ter plaatse / Online (Mollie) / Gratis). Footer totals use the whole filtered set, not just the page.

Payment detail:

- **Betaling voltooien** — local, open payments: marks it fully paid.
- **Terugbetalen** — completed Mollie payments with a reference: refunds through Mollie. Appointments
  are **not** cancelled automatically.
- **Te laat betaald**: the payment arrived after the booking was rejected and the slot is gone. The
  alert says "Te laat betaald: de tijd was al vergeven. Betaal het bedrag terug." — refund it.
- **Bedragen** repeats the stored breakdown (subtotal, discount, gateway surcharge, total, VAT,
  deposit/later te betalen, paid); **Boekingen** links the appointments.

## Coupons

`/app/coupons` — code (case-insensitive), Korting (%) and Aftrek (EUR) (both zero is rejected),
**Aantal keer te gebruiken** (account-wide), **Eén keer per klant**, validity dates (the *booking* date
counts, not the appointment date), min/max appointments per order, and restrictions to services
and/or staff (none ticked = all). **Genereer code** expands a mask like `WELKOM-****`.

## Notifications

`/app/notifications` groups templates by type (Nieuwe afspraak, Statuswijziging, Herinnering,
Wachtlijst, Plek vrij (wachtlijst), Nieuw pakket, Tickets), with an Aan/Uit toggle. The editor covers
recipients (Klant / Medewerker / Beheerders / Andere adressen), status filter, service filter,
reminder timing, subject, body with `{codes}` and `{#if …}` blocks, an optional .ics attachment, a
**Test versturen** button (to your own address) and the code reference. `/app/notifications/log` is the
send log with statuses Verstuurd / In wachtrij / Bezig / Mislukt and retry count.

Full detail: [`06-notifications.md`](06-notifications.md).

## Settings

`/app/settings/<tab>`:

| Tab | What you set |
|---|---|
| **Algemeen** | Bedrijfsnaam, Tijdzone, Tijdstap (minutes between start times), Minimaal vooraf (minutes), Maximaal vooruit (days), Taal van het boekingsformulier (Nederlands / Engels — the language customers see in the widgets; an individual embed can override it with `data-lang`). |
| **Bedrijf en e-mail** | Naam afzender (empty = company name), Antwoordadres, Telefoonnummer, Website, Adres, Verzendmarge herinneringen (uur), Annuleren tot (minutes before the appointment; 0 = until the start). |
| **Afspraken** | Status van nieuwe boekingen (Direct bevestigd / Eerst door jou goedkeuren) and the automatic status change (Van → Naar, after the appointment has passed). |
| **Agenda** | Alleen werkdagen tonen, Alleen de uren binnen de openingstijden tonen, Medewerkers zonder afspraken verbergen. |
| **Boekingsformulier** | Cart, chain ("direct na elkaar boeken"), extras × persons, Herhalende afspraken + Betalen bij een reeks (Hele reeks / Alleen de eerste afspraak), Bezetting tonen (Niet tonen / Bezette plaatsen 3/8 / Vrije plaatsen "nog 5"), Wachtlijst + "Wachtlijst telt mee als bezet", Prijs van samengestelde/samenwerkende diensten (Eigen prijs / Optelsom van de onderdelen) and "Klanten kiezen geen medewerker bij samenwerkende diensten". |
| **Betalingen** | Prijzen inclusief btw, Aanbetaling (alleen aanbetaling / klant kiest, aanbetaling voor / klant kiest, volledig voor), Ter plaatse betalen, Online betalen via Mollie + API-sleutel (write-only, shows a hint afterwards), Toeslag Mollie (%) en vast bedrag, Betaaltermijn (minuten), Status na betaling. Owner/admin only. |
| **Openingstijden** | Weekly template for new staff schedules. |
| **Vrije dagen** | Company-wide closing days. |
| **Insluiten** | Publieke sleutel, HTML snippet (on WordPress, paste it into a **Custom HTML** block; the shortcode shown there is not needed), and **Toegestane websites** (one origin per line; empty = every site may embed). |
| **Webhooks** | Owner/admin. Add an endpoint (URL + the events to send; the signing secret is shown **once**), **Test versturen**, **Uitzetten / Aanzetten**, **Verwijderen**, and the last 20 deliveries per endpoint with status, attempts and error. Rotating the secret and resending a delivery go through the API — see [Webhooks](10-webhooks.md). |
| **API** | Create and revoke API keys for the [management API](../api/README.md): name, scopes (catalogue/settings), shown once, plus the most recent writes per key. Server-side use only — the key is not for browsers. |

## Public pages your customers see

No login, `noindex`, styled minimally in the same design language:

- `/b/<booking token>` — **Je afspraak**: service, date/time, staff, persons, and "Afspraak
  annuleren" while the cancellation window (Instellingen → Bedrijf en e-mail) is open. "Afspraak
  verzetten" offers the next free times of the same service and staff (14 days, max 40 options);
  moving an appointment with several bookings moves them all. Friendly states
  for already cancelled, too late, already started, rejected and done.
- `/p/<package token>` — **Je pakket**: remaining visits, validity, planned visits, and the booking
  widget in package mode to plan the next one.
- `/w/<waitlist token>` — **Plek vrijgekomen**: "Plek innemen", first come first served; states for
  taken ("Helaas, iemand anders was je net voor.") and gone.
- `/o/<order token>` — **Je afspraken**: all appointments of one order with their statuses and one
  button ("Alle afspraken annuleren") that cancels everything still inside the cancellation window;
  appointments that are too late stay and are explained instead.

## Known limitations

- No user/role management UI, no invitations, no account switcher (the first membership wins).
- No CSV import/export, no print views, no activity log, no remembered filters.
- Customer pickers search as you type (20 matches at a time); type more to narrow down, or pick "Nieuwe klant" and enter the e-mail — an existing address is matched and reused.
- Warnings (overlap, schedule, holiday, duration) never block saving — "Toch opslaan" is always possible.
- Language of the admin UI is Dutch only.
# Notifications and e-mail

Every automatic mail is driven by a **template** that a business can edit in the admin
(**Meldingen**). The service renders the mail when the event happens, puts it in an **outbox**, and
sends it from there in the background with retries. Nothing is sent directly
from the request that created the booking — mail failures can never fail a booking.

## Contents

- [Lifecycle](#lifecycle)
- [Types](#types)
- [Recipients](#recipients)
- [Timing](#timing)
- [Template language](#template-language)
- [Codes](#codes)
- [Attachments and reply-to](#attachments-and-reply-to)
- [One mail per order, one per booking](#one-mail-per-order-one-per-booking)
- [Deferred mail for online payments](#deferred-mail-for-online-payments)
- [Delivery, retries and the log](#delivery-retries-and-the-log)
- [Background processing](#background-processing)
- [Admin reference](#admin-reference)
- [Sender and links](#sender-and-links)
- [Not implemented](#not-implemented)

## Lifecycle

```
event (booking, status change, reminder window, waitlist offer, …)
   │
   ├─ match active templates of that type (status filter, service filter)
   ├─ resolve recipients (customer / staff / admins / extra addresses)
   ├─ render subject + body per recipient  ← template codes, business time zone, locale
   ├─ dedupe (a unique dedupe key per recipient + event) and add to the outbox
   ▼
outbox (status pending → sending → sent | failed)
   ▲
   └─ every minute: send what is due → retry with backoff
```

Rendering happens at **enqueue** time, so the mail shows the data as it was at that moment.

## Types

| Type | UI label | Fires when |
|---|---|---|
| `new_booking` | Nieuwe afspraak | a booking/order is created (immediately for local/free orders; after payment for Mollie orders; also on waitlist joins and package purchases the corresponding type is used instead) |
| `status_changed` | Statuswijziging | a booking's status changes (admin action, cancellation, refund-rejection, automatic status change) |
| `reminder` | Herinnering | the reminder window for an upcoming appointment opens |
| `waitlisted` | Wachtlijst | a customer joins a waiting list |
| `waitlist_offer` | Plek vrij (wachtlijst) | a seat frees up and the customer gets a claim link |
| `package_new` | Nieuw pakket | a package is bought or created (mail contains the personal planning link) |
| `event_tickets` | Tickets | an event order is placed (a "codes follow after payment" variant) and again once the order is approved with the actual codes |

New accounts get a default template set for every type on signup (Dutch), so mail works out of the box.

## Recipients

Each template has four recipient switches:

| Switch | Who | Reply-To |
|---|---|---|
| **Klant** (customer) | the booking customer's e-mail | your **Antwoordadres** (`reply_to`), or the platform sender when empty |
| **Medewerker** (staff) | the staff member of the appointment (skipped when archived); for packages the package staff | the customer's e-mail |
| **Beheerders** (admins) | every member of the account with role owner or admin | the customer's e-mail |
| **Andere adressen** (custom) | the newline-separated addresses in the template | the customer's e-mail |

Sender: display name = your **Naam afzender** (or company name), address = the platform's
`MAIL_FROM`. At least one recipient must be enabled; custom recipients require at least one address.

## Timing

**Status filter** (`Bij status`): send only when the booking has that status; *Elke status* matches
everything. Note that *Elke status* in a **reminder** never includes cancelled or rejected bookings.

**Service filter**: all services, or a ticked subset.

**Reminder timing** (only for `reminder`):

- *Een aantal uur van tevoren* — send N hours before the appointment start (default 24; 0 means at
  the appointment time). Evaluated with a tolerance window: your
  **Verzendmarge herinneringen (uur)** (default 2) widens the match, so a reminder is not skipped after a
  short processing delay.
- *Op een vast uur* — send at a fixed local hour (0–23, default 18) a number of days before the
  appointment date (0–30, default 1). "0 = op de dag van de afspraak zelf".

Reminders dedupe on a key that includes the appointment start time, so **rescheduling re-arms the
reminder** while nothing is sent twice for the same booking.

## Template language

Placeholders and conditionals in both subject and body:

```
{client_name},
Je afspraak voor {service_name} is bevestigd op {appointment_date} om {appointment_time}.

{#if extras}
Extra's: {extras}
{/if}
{#if number_of_persons > 1}
We reserveren {number_of_persons} plaatsen.
{/if}
```

Rules:

- `{code}` — unknown or empty codes render as empty text.
- `{#if code}…{/if}` — block, may be nested. A newline directly after a block tag is swallowed.
- Comparisons: `{#if code == value}`, `!=`, `>`, `>=`, `<`, `<=`, `empty` (empty/absent), `!empty`.
  Values are compared as strings/numbers; missing codes are honest about being empty.
- No loops: there is no `{#each}`, so multi-item orders use the pre-joined `{appointment_schedule}` /
  `{extras}` / `{ticket_codes}` codes instead.
- **HTML mode** (the body of HTML mails): inserted values are HTML-escaped, newlines become `<br>`, and
  blank lines become paragraphs. A bad placeholder can therefore never inject HTML into a mail.
  Subjects always use plain text mode.

## Codes

`{code}` list as offered in the editor (Dutch labels in the admin):

**Bedrijf** — `company_name`, `company_phone`, `company_address`, `company_website`
**Klant** — `client_name`, `client_email`, `client_phone`
**Afspraak** — `appointment_date` ("dinsdag 14 oktober 2026"), `appointment_time`,
`appointment_end_time`, `appointment_notes` (the customer's remark), `booking_number`,
`number_of_persons`, `extras` ("Haarmasker (2×), Föhnen"), `extras_total_price`, `order_count`,
`appointment_schedule` (one line per appointment of the order), `online_meeting_url` and
`online_meeting_join_url` (empty unless the appointment has an online meeting), `series_count`,
`status` (Dutch label),
`internal_note` (only for staff/admin recipients), `cancel_appointment_url` (`/b/<token>`),
`cancel_order_url` (`/o/<order token>`),
`cancellation_reason` (currently always empty)
**Dienst** — `service_name`, `service_info`, `service_price`, `service_duration` ("1 uur 30 min"),
`category_name`, `fields` (the booking's answers to the service's Velden, one "Vraag: antwoord" line
per answer; a per-person answer gets one line per person. Empty without answers. A field that was
deleted later keeps showing its old answer, labelled with the field's id. A **Bestand** answer shows
the file name only: its download link is signed and short-lived, and mails are kept.)
**Medewerker** — `staff_name`, `staff_email`, `staff_phone`
**Betaling** — `total_price` (empty when free), `amount_paid`, `amount_due`,
`payment_type` (Ter plaatse / Online / Gratis), `payment_status` (Dutch), `coupon`, `total_tax`
**Wachtlijst** — `waitlist_url` (only `waitlist_offer`)
**Pakket** — `package_url`, `package_name`, `package_size`, `package_remaining`, `package_expires`
(only `package_new`)
**Evenement** — `event_title`, `event_start_date`, `event_start_time`, `event_end_time`, `event_info`,
`attendees_count`, `ticket_codes` (before payment: "Je codes krijg je na betaling."), `order_total`
(only `event_tickets`)

Which codes a template may use depends on its type: package and ticket templates have no appointment,
so they only offer company/client codes plus their own group.

## Attachments and reply-to

**Agenda-bestand (.ics) meesturen** attaches a standards-compliant calendar file (UTC times, escaped,
folded at 75 octets) for booking-based mails. It follows the appointment's current time; rescheduling
does not rewrite already-sent mails.

## One mail per order, one per booking

A single checkout can contain a cart, chain parts, compound/collaborative parts and a whole recurring
series. To keep this readable:

- **Customer, admins and custom recipients** get **one** `new_booking` mail per **order**, using the
  first appointment's codes plus `{appointment_schedule}` and `{order_count}`.
- **Staff** get one mail per appointment of their own.
- `status_changed` and `reminder` stay **per booking** — every cancelled occurrence gets its own mail.

## Deferred mail for online payments

For Mollie orders nothing is mailed at order time: the customer should not receive "your appointment is
confirmed" before paying. The confirmation mail is queued when the payment completes (webhook, return
poll, or the expiry check noticing the payment went through). Local and free orders are mailed
immediately. Ticket orders are the exception: they get a "codes follow after payment" mail right away,
and the codes mail once approved.

## Delivery, retries and the log

- Queued mail is sent within about a minute.
- Retry backoff after a failed send: 1 min, 5 min, 30 min, 2 h, 12 h. After 5 attempts the row becomes
  `failed` (it stays visible in the log with the error text).
- Mail stuck in *Bezig* (sending) for more than 10 minutes is retried automatically.
- **Meldingen → Verzendlog** shows every mail: recipient, subject, status (Verstuurd / In wachtrij /
  Bezig / Mislukt) and attempt count, filterable by status.
- **Test versturen** renders the saved template with sample data and sends it to the signed-in user —
  use it after every template change.

## Background processing

Everything timed runs as one scheduled pass, once a minute: queue the reminders that are due,
expire unpaid payments, apply the automatic status change, send the waiting-list offers, and deliver
queued mail. The service runs this itself — nothing to configure — but it is worth knowing because it
explains the timing you and your customers see:

- A reminder goes out at its chosen moment, with the tolerance window above absorbing a short delay.
- An online payment that is never completed expires after your **Betaaltermijn**; the slot
  then frees up. Until that moment it stays reserved.
- A waiting-list offer is mailed within a minute of a seat freeing up.

## Admin reference

**Meldingen** (`/app/notifications`) — grouped by type with an Aan/Uit switch per template. The editor
fields: Naam, Soort, Actief, Ontvangers (Klant / Medewerker / Beheerders / Andere adressen), Bij status,
Diensten (alle or a selection), reminder timing, Onderwerp, Bericht, Agenda-bestand (.ics) meesturen,
and the code table. Existing templates also have **Test versturen** and **Verwijderen**.

**Verzendlog** (`/app/notifications/log`) — the outbox, newest first, 50 per page.

Relevant settings: **Instellingen → Bedrijf en e-mail** (Naam afzender, Antwoordadres,
Verzendmarge herinneringen, Annuleren tot) and **Instellingen → Algemeen** (Tijdzone — all mail times
use it).

## Sender and links

The display name comes from **Instellingen → Bedrijf en e-mail** (Naam afzender), replies go to the
**Antwoordadres**, and the links in mails point at the pages this service serves (`/b/…`, `/p/…`,
`/w/…`, `/o/…`). Mail is sent from the platform's own sending domain; you do not configure it.

## Not implemented

- SMS, WhatsApp and voice notifications (only e-mail exists).
- `cancellation_reason` is always empty (no reason is captured on cancellation).
- No `{#each}` loops, no attachments other than .ics, no birthday/last-appointment campaigns.
- No per-recipient language: templates are sent in the language they are written in (Dutch by default).
# Data and privacy

What the service stores for a business, what it deliberately does not store, and what is reachable
from outside.

## What is stored

| Data | Contents |
|---|---|
| Customers | name, e-mail address, phone, free-text notes. One record per e-mail address per business. |
| Appointments and bookings | time, service, staff member, number of persons, status, the customer's note, chosen extras |
| Payments | amount, VAT split, status, coupon code, and a frozen snapshot of what was charged |
| Packages and event tickets | planned visits, ticket codes, attendee status |
| Mail | the subject and body of every message sent, with delivery status (the send log in the admin) |
| API keys | name, scopes, the key itself **hashed** (shown once at creation), revocation time, and an entry per write made with it |
| Calendar feed | per staff member an unguessable token for their iCal feed; the feed contains that person's appointments only |
| Online meetings | meeting links are generated per appointment and appear in mails and in the admin |

Not stored: card or bank details. Online payments happen on the payment provider's own page; only the
amount, the status and the provider's reference come back to us — enough to refund and to reconcile.

## Isolation

- Every record belongs to exactly one business. An account can only see its own data, in the admin
  and on every API call.
- The public API is bound to one account by its public key; one key can never read or write another
  account's data.
- A staff login sees only the appointments of the staff members linked to it.
- Payment settings can only be changed by an owner or admin (see the role table in
  [`05-admin-guide.md`](05-admin-guide.md)).

## What is publicly reachable

| URL | Shows | Protections |
|---|---|---|
| `/b/<token>`, `/o/<token>` | one booking, or all appointments of one order: service, date, time, staff, status | 48-character random token, `noindex`, nothing else |
| `/p/<token>` | remaining visits of a package, plus the customer's first name | same |
| `/w/<token>` | a freed seat, first come first served | same |
| public API | the catalogue and free times of the business behind the key | the key holder only; an allowlist of embedding sites per account |
| `/api/ical/<token>` | one staff member's appointments as an iCal feed | 48-character token, `noindex`; revocable per staff member in the admin |

No endpoint returns customer lists, e-mail addresses or payment details.

## Deleting data

- Deleting a customer removes that customer and their bookings; the admin asks for confirmation first.
- Deleting a service removes the appointments for that service.
- Deleting a whole business account is done by nisebookings on request; it removes all of its data.
- Mail that was already sent exists in the recipient's inbox; the send log disappears with the account.
# Sandbox — a throwaway account for testing

One unauthenticated call gives you a complete, bookable business with its own keys. Point the
widget, the public API, the management API or the MCP server at it, make real bookings, read the
mails that *would* have been sent, pay with a fake checkout, and throw it away. Nothing leaves the
sandbox: no mail is delivered and no money moves.

```bash
curl -s -X POST https://app.nisebookings.com/api/sandbox
```

```json
{
  "tenantId": "6f1c…",
  "name": "Sandbox 3fa2",
  "publicKey": "9c2e41…",
  "apiKey": "nk_…",
  "scopes": ["catalog:read", "catalog:write", "settings:read", "settings:write", "customers:read",
             "customers:write", "bookings:read", "bookings:write", "payments:read", "payments:write"],
  "expiresAt": "2026-10-13T09:12:44.000Z",
  "endpoints": {
    "publicApi": "https://app.nisebookings.com/api/public/9c2e41…",
    "managementApi": "https://app.nisebookings.com/api/v1",
    "mcp": "https://app.nisebookings.com/api/mcp",
    "widget": "https://app.nisebookings.com/widget.js"
  }
}
```

The `apiKey` is a normal management-API key with **every scope**. It is shown **once** — keep the
response. The `publicKey` is the sandbox account's public key, exactly as on a real account.

## What is in it

| | |
|---|---|
| Business | `Sandbox <4 hex>`, time zone Europe/Amsterdam, EUR, default mail templates, gateways `local` and `mollie` both enabled |
| Staff | **Anna** and **Ben**, Monday–Saturday 09:00–17:00 (opening hours the same) |
| Services (category "Demo") | **Knippen** 30 min €25 (Anna and Ben) · **Kleuren** 90 min €65 with a €20 deposit rule (Anna; whether it applies follows the deposit mode in the settings) · **Groepsles** group class, 6 seats, 60 min €15 (Ben) |
| Events | one event a week ahead with one ticket type |

The data is fictional. Change anything you like through the management API or MCP — it is your account
until it expires. There is no admin login for a sandbox: use the API, MCP and the widget.

## Limits

| Limit | Value |
|---|---|
| Lifetime | **24 hours** from creation (`expiresAt`), then the account and everything in it is deleted |
| Creation rate | **5 sandboxes per hour** per client address (the rightmost `x-forwarded-for` hop our edge appends, else `x-real-ip`) → `429 {"error":{"code":"rate_limited"}}` with `Retry-After` |
| Capacity | a global cap on live sandboxes → `429 {"error":{"code":"capacity"}}` with `Retry-After` |
| E-mail | **never delivered**; every mail is recorded with status `suppressed` (see below) |
| Payments | **never real**; the Mollie gateway goes to a fake checkout page (see below) |

## Connect

```bash
eval "$(curl -s -X POST https://app.nisebookings.com/api/sandbox |
  jq -r '"export PK=\(.publicKey) NISE_API_KEY=\(.apiKey)"')"
```

**Widget** — embed it on any page (a sandbox has no allowed-sites list, so every origin works):

```html
<script src="https://app.nisebookings.com/widget.js" defer></script>
<nise-booking data-key="9c2e41…"></nise-booking>
```

**Public API** — [`examples/headless.mjs`](examples/headless.mjs) runs against it unchanged:

```bash
KEY=$PK node headless.mjs
```

**Management API** — `Authorization: Bearer $NISE_API_KEY` on [`/api/v1`](../api/README.md):

```bash
curl -s -H "Authorization: Bearer $NISE_API_KEY" https://app.nisebookings.com/api/v1/me
```

**MCP** — connect your coding agent to the [hosted MCP server](../api/mcp.md) with the same key:

```bash
claude mcp add --transport http nise-sandbox https://app.nisebookings.com/api/mcp \
  --header "Authorization: Bearer $NISE_API_KEY"
```

## Verify mails: the outbox

Every mail the sandbox would have sent — confirmations, staff notices, cancellations — is kept with
status `suppressed`. Read them with `GET /api/v1/outbox` (or the `list_outbox` MCP tool), newest first:

```bash
curl -s -H "Authorization: Bearer $NISE_API_KEY" \
  "https://app.nisebookings.com/api/v1/outbox?to=ada@example.com"
```

```json
{
  "data": [
    { "id": "…", "status": "suppressed", "toEmail": "ada@example.com", "toName": "Ada Jansen",
      "subject": "Je afspraak is bevestigd", "text": "…", "html": "…",
      "createdAt": "2026-10-12T09:14:02.000Z", "sentAt": null, "lastError": null }
  ],
  "total": 1
}
```

Filters: `status` (`pending`, `sending`, `sent`, `failed`, `suppressed`), `to` (exact address,
case-insensitive); pagination `limit` (≤ 100) and `offset`. Mails are written by the background
worker, so a row can appear a minute after the booking that caused it; poll rather than assert once.
The endpoint exists on real accounts too (scope `settings:read`), where it shows what was actually sent.

## Fake payments

Book with `gateway: "mollie"` and a `returnUrl` exactly as on a real account. The response's
`payment.checkoutUrl` points to a nise test page, `https://app.nisebookings.com/sandbox/pay/<token>`,
instead of Mollie. It shows the amount and description with two buttons:

- **Betalen** — the payment becomes `completed`, the bookings are confirmed and the confirmation mail is recorded.
- **Mislukt** — the payment becomes `rejected` and so do its bookings, as with a failed Mollie payment.

Both redirect to your `returnUrl` with `?nb_pay=<token>`, so your return page and its
`GET /api/public/<key>/payments/<token>` polling work exactly as in production. Refunds
(`POST /api/v1/payments/{id}/refund`, scope `payments:write`) succeed locally without contacting Mollie.

## Delete it

A sandbox deletes itself after 24 hours. To delete it now, with its own key:

```bash
curl -s -X DELETE -H "Authorization: Bearer $NISE_API_KEY" https://app.nisebookings.com/api/v1/sandbox
```

`204` on success; the keys stop working immediately (`401`). On a real account this endpoint answers
`404` — it can never delete a business.
# Webhooks — get told when something changes

Register an HTTPS URL and the service `POST`s a small signed JSON message to it whenever a booking,
ticket or payment changes — no matter where the change came from: the widget, the public API, the
admin, the management API, the MCP server, or a scheduled job (a payment that expires, an automatic
status change). Webhooks replace polling `GET payments/<token>` or the appointment list.

- Managed with the [management API](../api/README.md) (scope `settings:read` / `settings:write`), the
  MCP tools `list_webhooks`, `create_webhook`, `delete_webhook`, `test_webhook`,
  `list_webhook_deliveries`, or the admin (*Instellingen → Webhooks*).
- Signed per the [Standard Webhooks](https://www.standardwebhooks.com/) spec: any of its libraries
  verifies our messages, or use the 15 lines of plain Node below.
- Delivery is **at least once**, in no guaranteed order. Deduplicate on `webhook-id`.
- Messages are **thin**: ids and status fields only. Fetch the details you need from `/api/v1`.

## Contents

- [Event types](#event-types)
- [Register an endpoint](#register-an-endpoint)
- [The message](#the-message)
- [Verify the signature](#verify-the-signature)
- [Responding, retries and the deliveries log](#responding-retries-and-the-deliveries-log)
- [Test, rotate, disable](#test-rotate-disable)
- [Write an idempotent consumer](#write-an-idempotent-consumer)
- [Endpoint reference](#endpoint-reference)

## Event types

| `type` | Sent when |
|---|---|
| `booking.created` | A booking is made (widget, public API, admin, management API, MCP) |
| `booking.updated` | A booking's status or number of persons changes, or its appointment is moved (start time, staff member, service) |
| `booking.cancelled` | A booking becomes `cancelled` or `rejected` (customer link, admin, API, unpaid payment expiring) |
| `ticket.created` | An event ticket (attendee) is created |
| `ticket.approved` | A ticket is approved (free order, payment completed, or marked paid at the desk) |
| `ticket.cancelled` | A ticket is cancelled |
| `payment.completed` | A payment is completed (Mollie paid, a free order, or marked paid in the admin / API) |
| `payment.failed` | A payment is rejected: Mollie reports it failed, cancelled or expired, or it timed out unpaid |
| `payment.refunded` | A payment is refunded |
| `ping` | You pressed *Test* (or called `POST /webhooks/{id}/test`). Always sent, whatever the subscription |

`GET /api/v1/webhooks/events` returns the same list with descriptions. An endpoint subscribes to a
list of types; subscribe to what you handle and ignore unknown types (new ones may be added).

A booking that is cancelled sends `booking.cancelled`, not also `booking.updated`.

## Register an endpoint

```sh
export API=https://app.nisebookings.com/api/v1 KEY=nk_...
H=(-H "Authorization: Bearer $KEY" -H 'Content-Type: application/json')

curl -s "${H[@]}" -X POST $API/webhooks -d '{
  "url": "https://shop.example.com/hooks/nise",
  "events": ["booking.created", "booking.cancelled", "payment.completed"],
  "description": "shop sync"
}'
```

```json
{
  "id": "5b0d…", "url": "https://shop.example.com/hooks/nise",
  "events": ["booking.created", "booking.cancelled", "payment.completed"],
  "description": "shop sync", "active": true,
  "createdAt": "2026-10-12T09:00:00.000Z", "updatedAt": "2026-10-12T09:00:00.000Z",
  "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
}
```

The **`secret` is shown once** — store it with your other credentials. No endpoint returns it again;
lost it? [Rotate](#test-rotate-disable).

URL rules: `https://` only, at most 2048 characters, no user name or password in it; the host must resolve to a public address (no
loopback, private, link-local or carrier-grade NAT ranges — checked at registration and again
before every send). Redirects are not followed: point the URL at the final address. An account can
have up to 10 endpoints.

## The message

```http
POST /hooks/nise HTTP/1.1
Content-Type: application/json
webhook-id: 0f8e3c1a-6d2b-4b7e-9a51-3c2d1e0f9a87
webhook-timestamp: 1791795600
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
```

```json
{
  "id": "0f8e3c1a-6d2b-4b7e-9a51-3c2d1e0f9a87",
  "type": "booking.cancelled",
  "createdAt": "2026-10-12T09:15:00Z",
  "tenantId": "6f1c…",
  "data": {
    "bookingId": "c41e…",
    "appointmentId": "8a07…",
    "customerId": "0d2b…",
    "serviceId": "82ef…",
    "staffId": "6a4c…",
    "persons": 1,
    "status": "cancelled",
    "previousStatus": "approved",
    "start": "2026-10-14T09:30:00Z"
  }
}
```

`data` per event family:

| Types | `data` fields |
|---|---|
| `booking.*` | `bookingId`, `appointmentId`, `customerId`, `serviceId`, `staffId`, `persons`, `status`, `previousStatus` (`null` on created), `start`; when the appointment was moved also `previousStart`, `previousStaffId`, `previousServiceId` |
| `ticket.*` | `ticketId`, `eventId`, `ticketTypeId`, `orderId`, `customerId`, `paymentId`, `status`, `previousStatus` |
| `payment.*` | `paymentId`, `customerId`, `type` (`local` / `mollie` / `free`), `status`, `previousStatus` |
| `ping` | `endpointId` |

- `id` = the `webhook-id` header = the event id. The same event redelivered (retry, manual retry)
  keeps its id.
- `data` holds ids and status fields only — never names, e-mail addresses or prices. Read the rest
  with the matching `/api/v1` call (`GET /appointments/{appointmentId}`, `GET /payments/{paymentId}`,
  `GET /events/{eventId}/attendees`), which also gives you the *current* state rather than the state at
  the time of the event.
- Field names are camelCase; times are ISO 8601 UTC.

## Verify the signature

The signature is `base64(HMAC-SHA256(key, webhook-id + "." + webhook-timestamp + "." + raw body))`,
where `key` is the base64-decoded part of the secret after `whsec_`. The header may carry several
space-separated `v1,<signature>` values; accept the message when any one matches. Reject timestamps
more than 5 minutes from your clock (replay protection). Always verify against the **raw** request
body — re-serialising parsed JSON changes the bytes.

Plain Node (no dependencies):

```js
import { createServer } from 'node:http';
import { createHmac, timingSafeEqual } from 'node:crypto';

const SECRET = process.env.NISE_WEBHOOK_SECRET; // whsec_…

export function verify(secret, headers, rawBody, toleranceSeconds = 300) {
  const id = headers['webhook-id'], ts = headers['webhook-timestamp'], sigs = headers['webhook-signature'];
  if (!id || !ts || !sigs) return false;
  if (Math.abs(Date.now() / 1000 - Number(ts)) > toleranceSeconds) return false;
  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const expected = createHmac('sha256', key).update(`${id}.${ts}.${rawBody}`).digest();
  return sigs.split(' ').some((s) => {
    const [version, sig] = s.split(',');
    const got = Buffer.from(sig ?? '', 'base64');
    return version === 'v1' && got.length === expected.length && timingSafeEqual(got, expected);
  });
}

createServer((req, res) => {
  let raw = '';
  req.on('data', (c) => (raw += c));
  req.on('end', () => {
    if (!verify(SECRET, req.headers, raw)) return res.writeHead(401).end();
    const event = JSON.parse(raw);
    res.writeHead(204).end();              // acknowledge first …
    handle(event).catch(console.error);     // … then do the work (dedupe on event.id)
  });
}).listen(8080);
```

The official Standard Webhooks libraries (`standardwebhooks` for JavaScript, Python, Go, Ruby, PHP,
…) accept the same `whsec_` secret and headers.

## Responding, retries and the deliveries log

- Answer **2xx within 10 seconds**. Any other status, a timeout, a redirect or a connection error is a
  failed attempt. Do slow work after you answered (queue it).
- Failed attempts are retried after **1 min, 5 min, 30 min, 2 h, 12 h and 24 h** — 7 attempts over
  about 39 hours. After the seventh the delivery is marked `failed` and not tried again
  automatically.
- Every delivery is logged per endpoint, with its attempt count and the result of the last attempt:

```sh
curl -s "${H[@]}" "$API/webhooks/$HOOK/deliveries?status=failed&limit=20"
```

```json
{
  "data": [{
    "id": "e2a1…", "endpointId": "5b0d…", "eventId": "0f8e…", "type": "booking.cancelled",
    "status": "failed", "attempts": 7, "nextAttemptAt": "2026-10-12T00:15:00Z",
    "lastStatus": 500, "lastError": "HTTP 500: Internal Server Error",
    "createdAt": "2026-10-10T09:15:00Z", "deliveredAt": null, "payload": { "…": "…" }
  }],
  "total": 1
}
```

  Statuses: `pending` (waiting for `nextAttemptAt`), `sending`, `delivered`, `failed`. `lastStatus`
  is the HTTP status of the last attempt (`null` when the connection failed or timed out; `lastError`
  says why). Fixed your receiver? Send a delivery again — same event id, same payload, a fresh
  signature and a fresh retry schedule (`409` while that delivery is being sent):

```sh
curl -s "${H[@]}" -X POST "$API/webhooks/$HOOK/deliveries/$DELIVERY/retry"
```

The admin shows the last 20 deliveries per endpoint with the same information. Delivered and failed
deliveries are kept for 30 days, then deleted; pending ones stay until they finish.

## Test, rotate, disable

```sh
curl -s "${H[@]}" -X POST $API/webhooks/$HOOK/test             # 202: queues a `ping` and sends it right away
curl -s "${H[@]}" -X POST $API/webhooks/$HOOK/rotate-secret    # the endpoint + "secret":"whsec_…" — shown once
curl -s "${H[@]}" -X PATCH $API/webhooks/$HOOK -d '{"active":false}'   # pause (no new deliveries)
curl -s "${H[@]}" -X DELETE $API/webhooks/$HOOK                # remove it and its delivery log
```

**Rotating** takes effect immediately: every message sent after the call, including retries of older
events, is signed with the new secret only. To rotate without dropping messages, let your receiver
accept either secret for a few minutes (try the new one, then the old), deploy that, rotate, then
remove the old secret.

A paused endpoint (`active: false`) receives nothing: events that happen while it is paused are not
queued for it, and deliveries that were already waiting for a retry resume when you switch it back on.

## Write an idempotent consumer

Retries mean you will sometimes get the same event twice; ordering is not guaranteed (a
`booking.updated` can arrive before its `booking.created` when the first attempt of the latter
failed).

1. Store every processed `webhook-id`; when you see it again, answer 2xx and do nothing.
2. Treat the message as a *hint*: re-read the object from `/api/v1` and act on its current state.
   Then order does not matter.
3. Answer quickly; failures in your own processing should not turn into 5xx loops.

Sandboxes send webhooks like any other account — the quickest way to build a receiver is a
[sandbox](08-sandbox.md) plus a public tunnel to your laptop.

## Endpoint reference

All under `https://app.nisebookings.com/api/v1`, scope `settings:read` for `GET`, `settings:write`
for the rest. Full schemas: [`openapi.yaml`](../api/openapi.yaml).

| Call | Does |
|---|---|
| `GET /webhooks/events` | Event types with descriptions |
| `GET /webhooks` | List endpoints (`{data, total}`, never the secret) |
| `POST /webhooks` | `{url, events, description?, active?}` → `201` with `secret` (once) |
| `GET /webhooks/{id}` | One endpoint |
| `PATCH /webhooks/{id}` | Change `url`, `events`, `description`, `active` |
| `DELETE /webhooks/{id}` | Remove the endpoint and its deliveries → `204` |
| `POST /webhooks/{id}/rotate-secret` | New secret → the endpoint with `secret` (once) |
| `POST /webhooks/{id}/test` | Queue and send a `ping` → `202` with the delivery |
| `GET /webhooks/{id}/deliveries` | Delivery log, newest first; `status`, `limit` (≤ 100), `offset` |
| `POST /webhooks/{id}/deliveries/{deliveryId}/retry` | Send that delivery again → `202` with the delivery |
# Next.js

Two ways in, both fine: the **widget** (fastest, no booking code of your own) or your **own UI**
against the public API. This page is the Next.js-specific part — the behaviour of the widget itself
is [the widget reference](03-widget-reference.md), the API is [the public API](04-public-api.md).

Everything below is one runnable app in [`examples/nextjs/`](examples/nextjs/README.md) (App Router,
tested with Next 16 / React 19). Both pages point at `https://app.nisebookings.com`.

## 1. A key

The public key goes in the browser — it is public by design (it reads the catalogue and creates
bookings, nothing else). Copy it from **Instellingen → Insluiten**, or get a 24-hour test account:

```bash
curl -s -X POST https://app.nisebookings.com/api/sandbox    # → { publicKey, apiKey, … }
```

```bash
# .env.local
NEXT_PUBLIC_NISE_KEY=<the public key>
```

Never put a **management** key (`nk_…`) in a `NEXT_PUBLIC_*` variable or in client code: that key can
change your whole account.

## 2. The widget, in one client component

`app/layout.tsx` — nothing special, but this is where `lang` and the stylesheet live:

```tsx
import type { ReactNode } from 'react';
import './globals.css';

export const metadata = { title: 'Salon Vlek' };

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="nl">
      <body>
        {children}
        {/* React hoists and dedupes this; the element below upgrades itself when the script runs. */}
        <script async src="https://app.nisebookings.com/widget.js" />
      </body>
    </html>
  );
}
```

`app/booking-widget.tsx`:

```tsx
'use client';
import type { DetailedHTMLProps, HTMLAttributes } from 'react';

// React renders an unknown tag as-is, but TypeScript needs the attribute types once.
declare module 'react' {
  namespace JSX {
    interface IntrinsicElements {
      'nise-booking': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement> & { 'data-key': string };
    }
  }
}

/** The widget path: the script lives in app/layout.tsx; this is just the element it upgrades. */
export function BookingWidget() {
  const key = process.env.NEXT_PUBLIC_NISE_KEY;
  if (!key) return <p>Set NEXT_PUBLIC_NISE_KEY in .env.local (see 08-sandbox.md for a test key).</p>;
  return <nise-booking data-key={key} />;
}
```

Use it from any page — a server component is fine:

```tsx
import Link from 'next/link';
import { BookingWidget } from './booking-widget';

export default function Home() {
  return (
    <main>
      <h1>Salon Vlek</h1>
      <p>Knippen, kleuren en groepslessen. Boek direct online:</p>
      <BookingWidget />
      <p><Link href="/headless">Zelfde afspraak, maar met eigen UI →</Link></p>
    </main>
  );
}
```

Why it is this small:

- **A plain `<script async src=…>` in the layout.** React hoists and dedupes it, so it loads once per
  page and the element upgrades itself when it arrives — independent of whether your own components
  have hydrated yet. `next/script` is the Next-specific alternative; note that it injects the tag from
  the client runtime, so a page that has not hydrated does not load it.
- **The element is a custom element with a shadow DOM.** React renders it as an ordinary unknown tag;
  page CSS cannot reach inside it. Style it with the host's design tokens instead
  (`--nb-accent`, `--nb-radius`, … — full list in the [widget reference](03-widget-reference.md#styling)):
  set them on `:root` or on a wrapping element.
- Attributes are strings: `data-key` is required; `data-lang`, `data-service`, `data-staff`,
  `data-package` and `data-api` are optional.

## 3. Your own UI on the public API

Two components: the server fetches the catalogue, the client fetches times and books.

`app/headless/page.tsx`:

```tsx
import { BookingForm } from './booking-form';

export type Service = { id: string; title: string; duration: number; price: number };

/** Availability changes by the minute, so this page is not prerendered. */
export const dynamic = 'force-dynamic';

async function listServices(): Promise<Service[]> {
  const res = await fetch(`https://app.nisebookings.com/api/public/${process.env.NEXT_PUBLIC_NISE_KEY}/services`, { cache: 'no-store' });
  if (!res.ok) throw new Error(`services answered ${res.status}`);
  const { services } = await res.json();
  return services.map(({ id, title, duration, price }: Service) => ({ id, title, duration, price }));
}

export default async function Headless() {
  const services = await listServices();
  return (
    <main>
      <h1>Boek online</h1>
      <p>Deze pagina haalt de diensten server-side op en boekt via de publieke API — geen widget.</p>
      <BookingForm services={services} />
    </main>
  );
}
```

`app/headless/booking-form.tsx`:

```tsx
'use client';
import { useState } from 'react';
import type { Service } from './page';

type Slot = { start: string; time: string; staffId: string };

const API = 'https://app.nisebookings.com';

/** Own UI on the public API: availability first, then a booking. The server re-checks everything. */
export function BookingForm({ services }: { services: Service[] }) {
  const [service, setService] = useState(services[0]?.id ?? '');
  const [slots, setSlots] = useState<Slot[] | null>(null);
  const [message, setMessage] = useState('');
  const [form, setForm] = useState({ name: '', email: '' });

  const key = process.env.NEXT_PUBLIC_NISE_KEY;

  async function loadSlots() {
    setMessage('');
    const today = new Date().toISOString().slice(0, 10);
    const res = await fetch(`${API}/api/public/${key}/slots?service=${service}&from=${today}&days=7`);
    const body = await res.json();
    setSlots(body.days?.flatMap((d: { slots: Slot[] }) => d.slots) ?? []);
    if (!res.ok) setMessage(`Tijden laden lukte niet (${res.status}).`);
  }

  async function book(slot: Slot) {
    setMessage('Bezig…');
    const res = await fetch(`${API}/api/public/${key}/bookings`, {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({ items: [{ service, staff: slot.staffId, start: slot.start }], ...form, phone: '', notes: '' }),
    });
    const body = await res.json();
    if (res.status === 201) return setMessage(`Geboekt: ${new Date(slot.start).toLocaleString('nl-NL')}.`);
    // 409 slot_unavailable = someone was first. Never retry the same slot; fetch fresh times.
    if (res.status === 409) { setMessage('Dat tijdslot was net bezet. Kies een nieuw tijdstip.'); return void loadSlots(); }
    const field = body.fields && Object.keys(body.fields)[0];
    setMessage(field ? `${field}: ${body.fields[field]}` : `Boeken lukte niet (${res.status}).`);
  }

  if (!services.length) return <p>Deze account heeft nog geen diensten.</p>;
  return (
    <section>
      <label>
        Dienst:{' '}
        <select value={service} onChange={(e) => { setService(e.target.value); setSlots(null); }}>
          {services.map((s) => <option key={s.id} value={s.id}>{s.title} — {s.duration} min</option>)}
        </select>
      </label>
      <p>
        <label>Naam <input value={form.name} onChange={(e) => setForm({ ...form, name: e.target.value })} /></label>{' '}
        <label>E-mail <input type="email" value={form.email} onChange={(e) => setForm({ ...form, email: e.target.value })} /></label>
      </p>
      <p><button onClick={loadSlots}>Toon vrije tijden</button></p>
      {slots && (
        <ul>
          {slots.map((s) => (
            <li key={s.start}>
              <button onClick={() => book(s)} disabled={!form.name || !form.email}>
                {new Date(s.start).toLocaleString('nl-NL', { weekday: 'short', day: 'numeric', month: 'short', hour: '2-digit', minute: '2-digit' })}
              </button>
            </li>
          ))}
          {!slots.length && <li>Geen vrije tijden in de komende week.</li>}
        </ul>
      )}
      {message && <p role="status">{message}</p>}
    </section>
  );
}
```

What the code is careful about:

- **`staff: slot.staffId`** — pass back the staff member the slot was offered for; the server resolves
  `"any"` for you, but a slot belongs to one agenda.
- **`409 slot_unavailable`** — somebody else booked that time. Re-fetch, do not retry the same slot.
  `409 capacity_exceeded` means the same thing for a group.
- **Prices come from the API**, never from your own arithmetic: `POST /quote` takes the same items as
  `POST /bookings` and returns the total, including extras, day services and coupons.
- **422** field messages are per field id — see [errors](04-public-api.md#cors-and-errors); intake
  questions come with the service's `fields`.
- The booking goes **straight from the browser** to `app.nisebookings.com`. That works because every
  account reflects the request origin when **Toegestane websites** is empty (default) or contains your
  site; otherwise the API answers `403 origin_not_allowed`. Proxying through a route handler is
  possible but not necessary.

## 4. Pitfalls specific to Next.js

- Do not wrap the widget in a `<form>` — it has its own submit flow, and a nested form is invalid HTML.
- Do not render `<nise-booking>` inside `dangerouslySetInnerHTML`: the widget upgrades elements it
  finds when the script loads, and React must own the node.
- A dynamic import (`next/dynamic` with `ssr: false`) is not needed; the element is inert until the
  script runs.
- Don't cache JSON responses of `slots` (`cache: 'no-store'` or `revalidate: 0`): stale availability
  produces 409s.

## 5. Run the example

```bash
git clone --depth 1 https://github.com/spoetnik/nisebookings.git   # or copy examples/nextjs
cd examples/nextjs && cp .env.example .env.local                    # paste the key
npm install && npm run dev                                          # http://localhost:3000
```

Next steps: [notifications and webhooks](10-webhooks.md) for reacting to bookings in your backend,
[the widget reference](03-widget-reference.md) for every attribute and token, and
[the sandbox](08-sandbox.md) if you want to test without touching a real account.
# 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.