# Booking (/docs/app/booking)

> Study: a study of the work. Defines nothing. No package exists.

> App study: where a Business that sells time turns perishable capacity into attended, paid visits under policies that carry money.



A booking App is the App where a Business that sells time turns perishable capacity into attended, paid visits. The capacity is a person's hour, a chair, a room, a table at 19:30 or a campsite for three nights.

An unsold hour never sells later, and a no-show destroys the hour and the demand turned away for it. Every part serves three numbers: utilization, show rate, and revenue per unit of capacity.

Any Business that sells time ships one: a salon, a clinic, a law firm's consults, a restaurant, a plumber, a campground. It differs from scheduling a sales call.

If a no-show loses revenue a policy can recover, the Business needs this type; if it loses only a conversation, a scheduling link is enough.

This type serves the booker's side of a slot. A performer taking a slot, such as a shift with a Site, a Time Window, check-in grace and a show-up minimum, works in the [Worklist](https://next.mdxui.dev/docs/app/worklist). Both read the same availability and the same hold. The study describes the work; how an App is defined is open, see [What every App needs](https://next.mdxui.dev/docs/app/every-app).

## Actors

| Actor | Relation | Work here |
| --- | --- | --- |
| Booker | Requester; accepts the policy; often the payer | Books, usually as a guest with no account |
| Attendee | The person, child, pet or vehicle the time is for | Owns their own intake answers |
| Proxy | A parent, caregiver or assistant under a grant | Books on someone's behalf |
| Payer | A payment holder, insurer, employer or package owner | Owns the balance or instrument |
| Provider | Performs the visit | Owns their own hours inside the Business's |
| Front desk, dispatcher | Operates the day on bookings it does not own | Books callers, takes walk-ins, checks in, charges or waives fees with a reason |
| Owner, location manager, franchise admin | Owner and steward of menu, prices and policy | A location only tightens what HQ sets |
| Resource steward, bookkeeper, integrator | Rooms and equipment; deposits and package liability; channels and widgets | |

Agents: the booker's agent reads the menu and policy, searches, holds, books and cancels under a delegated grant. The front-desk agent answers phone, SMS and chat, books, takes deposits, reminds and fills cancellations from the waitlist. Others run reminders, payments, intake triage, calendar sync, retention and schedule optimization behind an approval queue.

## Interfaces

| Reader | Screens | Renderings |
| --- | --- | --- |
| Booker | Booking flow (location, service, provider or any, time in the booker's zone, add-ons, then party, intake, policy acceptance, payment, confirmation); a hold countdown; confirmation; manage by magic link with the fee that applies now; waitlist join and a claim page with a timer; account with balances and family members; intake and waivers per attendee; check-in; post-visit receipt, tip, review, rebook | Email with ICS; SMS with reply keywords (C, R, STOP); a voice receptionist; a "Book" button on maps and social profiles |
| Booker's agent | none | MCP and OpenAPI: menu, versioned policy, availability search, hold with an expiry, book with an idempotency key, reschedule, cancel returning the fee, waitlist, check-in, intake; events back |
| Provider | My day with client notes and gaps; my availability; my clients; close the visit | Daily digest; push on changes; a one-way feed into a personal calendar |
| Front desk | A day grid by staff, room or table with drag to move and conflicts shown (restaurants use a floor plan with table states); quick book; walk-in queue; arrivals board; checkout; fee actions; a two-way message inbox | Kiosk self check-in |
| Dispatcher | Technicians by time with a map, unassigned queue, arrival windows, emergency inserts into held-back capacity | |
| Owner | Service menu; resources; hours; booking rules; policies; packages and memberships; routing; notifications; payments; staff pay; channels; import; utilization, show rate and revenue per unit of capacity by location, resource and service | |

## Records and actions

| Record | States |
| --- | --- |
| Hold | active, then converted, released or expired; shown to others only as busy |
| Booking (attendance) | requested (approval mode only), pending payment, confirmed (acknowledged or not), rescheduled under the same id with the policy re-checked; canceled, late-canceled, canceled by the Business, no-show; arrived, in service, completed, closed |
| Payment, per booking | none; saved method, authorized, deposit paid, prepaid or credit reserved; captured, applied or released; refunded, fee charged or waived; disputed |
| Waitlist entry | waiting, offered with a time limit, claimed or lapsed and cascaded to the next |
| Package credit | purchased, active, redeemed per visit, exhausted or expired, frozen, refunded |
| Field job | booked, dispatched, en route, on site, estimated, approved, working, invoiced, paid, closed |
| Policy | draft, published as version n, superseded; a booking points to the version it accepted, forever |

Verbs:

- **Availability and holds:** search (computed, read-only), hold, extend, release.
- **Booking:** book (consumes the hold, applies the policy version, takes payment), request and approve, assign, reschedule, cancel.
- **The visit:** remind, confirm attendance, check in, mark no-show, rebook.
- **Money:** charge or waive a fee; take, apply and refund a deposit; redeem and restore a credit.
- **Capacity:** join, offer and claim from the waitlist; block a resource; sync a calendar.
- **Field work:** dispatch, estimate, invoice.

### Terms

| Term | In startupbuilder.dev | Definition, quoted from [startupbuilder.dev](https://startupbuilder.dev) or the gap |
| --- | --- | --- |
| Worker | [Worker](https://startupbuilder.dev/business/nouns/worker) | "A Worker is a Human or an Agent that fills a Role and acts on Tasks." Fits the provider. |
| Order | [Order](https://startupbuilder.dev/business/nouns/order) | "An Order is a Customer's commitment to buy one or more Offers once, moving from placed to paid, fulfilled, and closed." It lacks authorization, setup and fee states. |
| Service, as a menu item | collides | startupbuilder.dev's Service warrants an outcome under an Outcome Contract; a haircut on a menu is an Offer. |
| Booking | lacks | startupbuilder.dev has the Verb on Meeting, a sales call, and Registration for a place at a Gathering. |
| Hold | collides | Three startupbuilder.dev senses already: a Startup lifecycle state, a spend state, and a held disputed amount. The type's most important transient record has no free word. |
| Waitlist, visit, calendar event | collide | startupbuilder.dev's Waitlist is Leads waiting for an Offer; Visit is a web-analytics span; Event is the immutable record. |
| Location, resource, availability rule, slot, check-in, gift balance | lack | |
| Cancellation policy | splits | The rule is a Policy; the booker's acceptance is closer to an Agreement or Consent. |

## Workflows

1. **Onboarding.** Set up locations with time zones and holidays, and a service menu with durations, processing gaps and prices. Add providers with hours and a busy-only calendar import, then resources. Write rules and policies, versioned from day one. Onboard payments, email, then SMS once registration clears, and the channels and agent door. Import from the incumbent, queuing future-booking conflicts and never deleting them.
2. **The core loop.** Discover, choose, then search, computed in the location's zone and shown in the booker's. Hold every capacity the slot needs at once, with a time limit. Take intake, show and record the exact policy, pay by policy, then confirm and notify. Remind at about 72, 24 and 2 hours; a reply of C confirms and R opens rescheduling. Arrive, deliver, check out with the deposit applied and the package drawn down, then follow up.
3. **Unhappy paths.** Two bookers pick one slot: the second hold fails and alternatives show. A hold can expire during 3-D Secure or an agent's round trip to its human. Then extend it, or void and search again; never capture for an expired hold. Payment succeeds and booking fails: an idempotency key and a sweep. A provider falls sick: mass reschedule with no fees for Business-initiated cancels.
4. **Money that depends on time.** A fee depends on when the cancel happened, which policy version was accepted, and who cancelled. A payment authorization lasts about 7 days online, so a booking three weeks out needs a saved method and a later charge. Deposits and unredeemed packages are liabilities until earned.
5. **Disputes.** A no-show fee draws chargebacks. The evidence is the accepted policy version with its time and actor or grant, the reminder delivery logs and the absent check-in.

## Boundaries

- Bookers see availability as free time only: never why a slot is busy, who else booked, or a provider's personal events.
- Intake belongs to the attendee. An adult's health intake never shows to the person who paid.
- A provider working for several Businesses shows each one busy only; event titles from personal calendars never enter a tenant.
- Fee charges, large refunds and policy overrides are separate permissions; clinical content can be hidden from the front desk.
- The platform never sees payment numbers, clinical intake or notes. In a clinic, the existence of a sensitive booking is itself health information.
- A reminder for a sensitive service says "your appointment at 3pm", not the service.
- An agent-placed booking is labelled, and its grant names the Business, the Verbs, a spend cap, policy-acceptance authority and an expiry.
- Utilization and show rate are legitimate over rooms, chairs, locations and Businesses. Over a natural person, such as utilization per stylist under an employer, they fall under the measurement policy and are not this type's default.

## Agents

Agents compute and offer availability, hold and book within published rules, confirm and remind, and reschedule on request. They fill cancellations from the waitlist, route to providers, collect intake and check insurance. They sync calendars, nudge rebooking, propose optimizations and answer the phone.

Humans keep:

- no-show and late-cancel fees where the Business chooses that, with an agent preparing the charge and its evidence;
- waivers and exceptions, and large or disputed refunds;
- clinical red flags: an agent never books past chest pain at a dental booking;
- legal conflict checks before a consult;
- mass reschedules, blocking a client and dispatch overrides;
- new prices and policies.

When the booker is an agent, the Business needs three things. It needs proof of delegation, a machine-readable acceptance of the policy version, and a payment mandate if money is due. Missing any one, the booking is only held pending the human.

## Hard parts

1. **Availability is computed, not listed.** Start from location hours, intersected with provider hours and every required resource. Subtract bookings with their buffers and travel, holds, blocks and synced busy time. Intersect with rules: notice, advance, caps, pacing, holdback. "Any provider" is a union; "all of these" is an intersection.
2. **Concurrency.** A booking claims several capacities atomically. External calendars lag, so some double-booking is unavoidable and must be detected. Overbooking can be deliberate, which makes it a rule, not a bug.
3. **Time.** Three time zones (location, provider, booker), daylight-saving gaps and repeats, recurring rules expanded in local time, floating check-in times for stays.
4. **Sequences and gaps.** A color process frees the stylist while the chair stays booked; travel between jobs makes availability depend on the previous job.
5. **Regulation.** Fee disclosure before booking, SMS consent and registration, health privacy, licensure in the patient's state for telehealth, fair-workweek law where the Business schedules staff.
6. **Migration and lock-in.** Future bookings, package balances, gift balances and stored payment methods, which move only processor to processor.
7. **Scale.** Slot computation across providers, days, increments and resource combinations, recomputed on every change; reminders spike at the top of the hour.
8. **One hold, two sides.** A booker's hold on a slot and a performer's claim on a shift race for the same capacity. One hold primitive with a time limit serves both, or they double-book each other.

## Day one

For any Business with one location, day one holds:

- hours, time zone and holidays, and a service menu with duration, price and buffer;
- a few providers with weekly hours, and busy-only calendar import;
- computed availability with notice, advance and buffers;
- a booking page and embed, and holds with a time limit;
- confirmation with ICS and a manage link;
- one versioned cancellation and no-show policy, shown and accepted;
- a saved payment method or a deposit;
- email reminders, then SMS;
- a provider day, a minimal front-desk view and an owner screen;
- the agent door, with webhooks.

| Need | Turns on later |
| --- | --- |
| Revenue kept | Waitlist auto-fill, confirmation replies, packages, memberships, gift balances, checkout |
| Capacity | Resources, multi-resource services, processing gaps, classes with seats |
| Teams | Round robin and routing forms, multiple locations and franchise floors, staff pay |
| Reach | Two-way SMS, a voice receptionist, external booking channels |
| Field and health | Dispatch, arrival windows, an offline technician app, insurance-aware availability, telehealth |

The Startup layer splits two founders. One whose Startup is booking-shaped ships the API and agent door first, then a booking page. One who needs bookings only for demos and consults needs a scheduling link, not this type.

## Related studies

## Prototypes this study needs