Core Concepts
A booking answers three questions: what is being reserved, when it is available, and what kind of appointment the customer wants. The component models these as resources, schedules and event types.
Resources
A resource is something with limited availability: a room, a person or equipment.
It has your chosen external id, an organizationId, a name and a timezone.
| Resource | Configuration | Inventory behavior |
|---|---|---|
| A meeting room | Exclusive resource, quantity one | One booking at a time |
| Four interchangeable cameras | isFungible: true, quantity: 4 | Up to four units at a time |
Pools use the multi-resource API, even when a booking only needs units from one pool. The ordinary Booker flow is for an exclusive resource. Quantities and capacities are positive safe integers.
Schedules
A schedule describes weekly opening hours in an IANA timezone, such as weekdays
09:00–17:00 in America/New_York. Date overrides close a particular day or replace
its hours, for example for a holiday.
Attach a schedule to an event type using scheduleId. The reference host gateway
combines the schedule with occupied inventory to produce bookable slots. Keep
that same policy check on writes so a direct API call cannot book outside the
hours shown in the calendar.
Event Types
An event type describes the appointment: its title, duration, allowed locations and whether it needs approval. For example, a room might offer both a 30-minute meeting and a 90-minute workshop.
Link each event type to the resources it can use. Creating both records is not enough; the link makes the combination bookable.
| Field | Meaning |
|---|---|
lengthInMinutes | Default duration |
lengthInMinutesOptions | Optional duration choices |
slotInterval | Spacing between offered start times |
requiresConfirmation | Create a pending booking for approval |
minNoticeMinutes, maxFutureMinutes | Notice and horizon settings enforced by the host gateway |
bufferBefore, bufferAfter | Stored settings; your host must enforce any gap |
Inventory and Time
Inventory uses a 15-minute grid. A 60-minute booking occupies four consecutive slots. Exclusive resources track occupied slots; pools track the reserved quantity per slot. Creating a bundle reserves all its resources in one transaction.
Booking timestamps are Unix milliseconds. Schedules use local dates and IANA timezones; slot strings returned for the UI are ISO timestamps. Keep timezone conversion at these boundaries, especially around midnight and daylight saving changes.
The component looks up inventory for the requested dates instead of scanning all historical bookings. Work still grows with the date range and number of resources requested.
Booking Lifecycle
A booking is confirmed immediately, or pending when its event type requires
approval. Both occupy inventory. A provisional booking also occupies inventory
while a host-controlled confirmation step is outstanding; arrange expiry in your
host flow if it is not completed.
Cancellation or decline releases the booking's inventory. Repeating a terminal operation cannot release inventory belonging to a later booking. Rescheduling creates a new booking, retains its status and resource quantities, and cancels the original in the same transaction.
A management token authorizes guest access to the booking's management actions. Treat it as a secret and share it only with the booker. See booking management links.
Presence
Presence tells visitors that someone else is looking at a slot. It uses short-lived heartbeats and helps the UI show temporary selections, including selections that span several 15-minute slots.
It is a best-effort UI signal. The booking mutation is the final inventory check; a presence heartbeat does not guarantee a reservation.
Your Host App
The component owns inventory and booking records. Your app owns authentication,
organization access, opening-hours policy and abuse limits. It calls the
component through components.booking.* from host queries and mutations.
Start with the quickstart, then review the host policies and authorization guide before exposing your own public functions.