Bookable resources: sell time slots and reservations

Some products are sold as a slot of time rather than a unit of stock. A meeting room, a piece of rental equipment, a fitness class, a consultation, a car hire — the shopper is not buying one of many identical items from a warehouse, they are reserving a specific window during which that resource is theirs.

Booking turns an ordinary product into a bookable resource. Instead of tracking how many units remain in stock, Crystallize tracks when the product is free: it reads availability for a requested window, holds the slot while the shopper checks out, and records the result as a reservation. This page is the overview — it explains the moving parts and how they fit together, then points you to the pages that cover each one in depth.

You meet four things, in this order:

A reusable set of time rules: how much buffer to leave around each reservation, how far ahead a shopper may book, how late a booking may still be cancelled, and how long a held slot survives before it is released. You create policies once, under Settings, and reuse them across many products.

A product becomes bookable when you open its Booking section, pick a policy, and define its pool — the thing being booked. One policy can back many products.

Once the product is published, the storefront reads availability for a requested window and places a hold on the slot while the shopper checks out. Availability and holds are served by the Shop API.

The Reservations view is where staff see everything that has been booked, on a calendar or a list, and where they can cancel a booking or block time by hand.

A pool is what a bookable product actually books against, and every bookable product has exactly one of two kinds:

• Capacity pool — a number of interchangeable slots. Use it when the shopper only cares that a slot is free, not which one: ten seats in a class, five identical loan bikes.
• Unit pool — a set of named units, each with its own id and optional metadata (a floor, a seat-map coordinate, a size). Use it when units are distinguishable and a shopper or staff member may pin a booking to a specific one: Room A, Table 12, Van 3.

You choose the kind in the product's Booking section. Switching from one to the other replaces the pool, so a product is only ever a capacity pool or a unit pool — never both.

Every held or booked slot is a reservation, and it moves through a small set of states:

• Pending — the slot is held but not yet committed. A storefront hold starts here and carries an expiry.
• Confirmed — the booking is committed. Confirmation is an explicit step; a hold that is never confirmed simply expires.
• Completed — a confirmed reservation whose window has passed.
• Expired — a pending hold reached its deadline before being confirmed, and the slot was released.
• Cancelled — the booking was cancelled: by the shopper while the cancellation window is still open, or by staff at any time.

The happy path is Pending → Confirmed → Completed. A hold that is left uncommitted lapses to Expired and frees the slot; a cancellation takes an active reservation to Cancelled. Only storefront holds expire — staff blocks have no deadline and stay until they are cancelled.

Every reservation records its source, which tells you who put it there:

• Cart — a shopper holding a slot through the storefront during checkout. These are the only reservations that expire.
• Staff blocks — time set aside in the app rather than sold: Maintenance, Staff hold, Partner allocation and Other. Staff create these from the Reservations view to take a unit or some capacity out of circulation; they have no expiry and remain until cancelled.

In the Crystallize app, every policy duration is entered as a value plus a unit — seconds, minutes, hours or days. Across the APIs the same durations are expressed as a whole number of seconds. Booking windows — the start and end of a reservation — are always in UTC.

In the app, two permissions gate the feature: booking policies (create, read, update, delete), which controls the Settings editor, and product booking (read, update), which controls a product's Booking section and the Reservations view. A user who cannot read product booking sees neither.

On the storefront and admin side, access to the Shop API is scoped by token. Reading availability and placing holds during checkout need a token scoped to cart, order and booking; the administrative surfaces — staff blocks and the reservation calendar — additionally need the booking:admin scope.

Each part has its own page:

• Booking policies — create and manage the reusable time rules.
• Bookable products — make a product bookable, choose a policy, and define its pool.
• Reservations — view, filter and manage bookings, and block time by hand.
• Booking APIs — read availability, hold slots, confirm bookings and run admin operations over the Shop API.

For storefront integration — reading availability, holding a slot through the cart, and confirming a booking — see the Shop API pages.