Booking

Upstream overview

From the upstream package documentation.

A Convex component for booking rooms, people and equipment. It manages timezone-aware availability, prevents conflicting bookings and reserves several resources atomically. It supports equipment pools, confirmation, cancellation, rescheduling and token-based booking management. Use the backend API for custom interfaces or the included React Booker for single-resource booking flows.

Use cases

From the upstream package documentation.

• Prevent overlapping bookings for meeting rooms, studios, and other exclusive resources.
• Manage equipment rental pools with quantity-based availability for interchangeable items.
• Coordinate appointments that require several resources, such as a staff member, room, and equipment, in one atomic booking.
• Add a public booking page with date selection, available time slots, and contact capture using the included React Booker.
• Let customers cancel or reschedule through token-based management links, with optional email notifications through Resend.

How it works

From the upstream package documentation.

Register the component in convex/convex.config.ts with app.use(booking), then expose booking operations through your own Convex functions. Browser clients call these host functions, which check authorization and your booking policies before delegating to components.booking.*. The component keeps booking records and inventory in its own tables and uses transactional checks to prevent conflicting reservations.

Configure resources and schedules with weekly hours, date overrides and IANA timezones, then link resources to the event types that define how they can be booked. Inventory is tracked on a 15-minute grid. Equipment pools and bookings that need several resources use the multi-resource API, which reserves every requested resource atomically.

Bookings, moves and confirmations check one set of rules: the event type and its resources exist, are active, are linked to each other and belong to the event type's organization. Expected failures throw ConvexError({ code, message }) with documented codes, so your host functions can map them to their own messages. Read-only maintenance audits list stored data that needs attention after an upgrade.

For the React UI, wrap your page in BookingProvider with your host's public API and render <Booker />. It handles date, duration and slot selection, contact details and confirmation for one exclusive resource, and shows booking errors itself. onBookingComplete receives the booking, including its UID, so you can link to your booking management pages.

The backend supports confirmation, cancellation and atomic rescheduling. Token-based management links let customers cancel or move their bookings. Your host controls booking policies and the expiry of provisional bookings, and optional Resend integration adds email notifications.