How-To Do This

How to build Reservations

Build bookable products, capacity, assignments, calendars, tenant-controlled payments, and pre/post-service follow-up.

Reservations is a reservations and booking operations pattern. This guide turns the product concept into a buildable first release using BuildWithHQ records, pages, workflows, permissions, integrations, AI, and exact-version packaging.

Define the outcome before the screens

Let an authenticated customer or operator select a bookable product, protect capacity, create or reuse the Contact, place the service on the Calendar, assign an eligible tenant user or resource, coordinate tenant-controlled payment, and deliver scheduled follow-up.

1. Create the smallest useful data model

In the Developer Console, create or select the SaaS app and model these as application record types and relationships. The page editor composes React components and validated data bindings, which call the platform APIs for these records.

Relationship rule: Keep Contacts, Calendar, payment orchestration, communications, tenant users, Locations, and resources canonical, with the Reservation as the lifecycle record that links them.

2. Build the working screens

Start with task-oriented pages instead of a page for every table. The first navigation should contain:

• Bookable-product setup.
• Availability and authenticated booking flow.
• Reservation list and detail workspace.
• Calendar, assignment, and capacity view.
• Payment state and pre/post-service follow-up queue.

Use Puck for the normal visual experience. Keep stable block identity when using Monaco advanced JSON mode so future template upgrades can merge safely.

3. Set access before adding automation

• Separate operator, assigned provider, manager, and customer User Type experiences.
• Scope reservations by DataRole, Location, assignment, and Contact relationship.
• Protect payment references, internal notes, and customer fields independently.
• Require explicit permissions for product setup, assignment, cancellation, payment actions, and override.

User Type menus establish eligible page routes for each audience. They do not grant the records or actions on those pages. The server derives the account, SaaS app, user, DataRole, and location scope from the verified identity on every data request.

4. Add the core workflows

• Select product/time -> validate availability -> protect capacity -> create reservation.
• Create or reuse Contact -> assign eligible user/resource -> create Calendar event.
• Free booking -> confirm; paid booking -> tenant-controlled charge intent and synchronized state.
• Before-service due time -> queue and send configured reminder/follow-up.
• Completion/cancellation -> release capacity and schedule or cancel after-service communication.

Make each mutation a narrow, reviewed action with explicit inputs, allowed states, correlation evidence, and an idempotent retry policy where retries are possible. Pages, integrations, and agents all reach the same application service and stored-procedure contract through supported APIs.

5. Connect channels and outside systems

• Use tenant-owned payment configuration and provider orchestration; keep credentials and provider calls server-side.
• Use Calendar and communications workers for durable schedules and delivery evidence.
• Use authenticated inbound endpoints and signed webhooks for external channel/provider state.

Use managed connections, OAuth connectors, inbound endpoints, and webhooks. Put specialized SDKs or private processing behind a declared appliance endpoint; never expose provider credentials to a page.

6. Add AI as a governed layer

Use AI only where it improves permitted scheduling, customer-service, or follow-up work. It may summarize context or draft a message, but it cannot invent availability, confirm a charge, or bypass reservation state rules.

• Retrieve only permitted Contact, Reservation, product, and communication context.
• Treat capacity and payment state as deterministic service results, not model output.
• Bind drafts and suggestions to the current reservation/activity version.
• Require policy or human approval for customer-facing or material actions.

AI and retrieval must apply CanAiReadRecords, tenant, DataRole, field, and location security before context is assembled. Planning and research remain read-only. Customer-facing or material changes use an action suggestion and the configured policy or human approval before execution.

7. Ship one complete vertical slice

Recommended first release: Configure one paid service, book it for an existing or new Contact, protect one capacity slot, assign one tenant user, create its Calendar event and charge intent, then deliver one before- and one after-service follow-up.

1. Create the minimum record types and seed representative, non-production data.
2. Build the primary list/queue and one complete detail page.
3. Implement one state-changing workflow and its denial/error states.
4. Add the narrowest useful integration or inbound channel.
5. Add one permission-aware AI read or suggestion only if it improves that workflow.
6. Test as an owner, a normal operator, a restricted user, and an unauthorized user.

8. Validate, package, and operate

• Test cross-tenant, DataRole, Location, assignment, and Contact denials.
• Test concurrent capacity claims, buffers, party limits, and stale reservation versions.
• Prove booking, charge-intent, provider-state, and follow-up retries are idempotent.
• Trace reservation, calendar, payment reference, and communication evidence by correlation ID.

Publish a reviewed exact version as a template when the pattern is reusable. If you sell it, complete the marketplace preparation checks. Template installs are version snapshots; upstream edits must never silently mutate a tenant copy.

Built-in data path: React components and data bindings call authenticated APIs; typed application services execute reviewed stored procedures and return bounded results with audit and correlation evidence.