PRD: Booking-Based Package Type

Overview

NeetoCal packages currently support only duration-based limits (e.g., "120 minutes of coaching"). This enhancement introduces a second package type: booking-based packages (e.g., "4 coaching sessions"). Both types coexist. A host selects the type when creating or editing a package.

---

Motivation

Duration-based packages work well for variable-length appointments, but many use cases are session-oriented — a client purchases N sessions and redeems them one at a time. Supporting booking-based packages removes the need for hosts to mentally calculate total minutes and gives customers a clearer understanding of what they are purchasing.

---

Feature Details

1. Package Creation & Editing (Admin)

A new required "Package type" section is added to the package form, implemented as two radio button cards with a title and description each:

• Duration based — existing behavior. Description: "Clients can use this package until the total package duration is exhausted."

• Bookings based — new. Description: "Clients can make a fixed number of bookings using this package."

The section header reads: "Choose whether this package is redeemed by total minutes or by a fixed number of bookings."

Neither option is selected by default on the create page. When the user attempts to save without selecting, an error message appears: "Select how clients can redeem this package before saving."

The selected card is highlighted with a green border and background (neeto-ui-border-success-500, neeto-ui-bg-success-100). The radio indicator fills with green when selected. Clicking a card selects it and expands an inline section with the relevant input fields.

Depending on the selected type, the expanded section shows:

Validation rules:

• Package type is required; an error is shown if saved without selecting.

• Duration-based: Duration is required, must be a positive integer.

• Booking-based: Total bookings is required, must be a positive integer (minimum 1).

• Duration-specific validations (e.g., "duration must be evenly divisible by meeting duration" for Stripe packages, and "all meetings must have the same duration") are skipped for booking-based packages.

• The save button is always enabled (not disabled when the form is pristine); it is only disabled while a submission is in progress.

• On failed submission, the page scrolls smoothly to the first visible error message.

2. Booking Deduction

• Duration-based (unchanged): Each booking deducts the meeting's duration (in minutes) from the purchase's remaining duration.

• Booking-based: Each booking deducts 1 booking from the purchase's remaining bookings, regardless of the meeting's duration.

3. Recurring Bookings

For recurring bookings with N occurrences, N bookings are deducted (one per occurrence), not 1.

4. Multi-Spot Group Bookings

When a customer reserves multiple spots in a group meeting, the deduction is multiplied by the number of spots reserved. This applies to both package types and all flows (booking, cancellation, rejection, recurring).

5. Cancellation

When a booking is cancelled:

• Duration-based: The meeting's duration (× number of spots) is restored to the purchase.

• Booking-based: The number of spots is restored to the purchase.

6. Booking Rejection (Approval Flow)

When a host rejects a booking that required approval:

• Duration-based: The meeting's duration (× number of spots) is restored to the purchase.

• Booking-based: The number of spots is restored to the purchase.

7. Awaiting Approval

When a booking is created that requires host approval:

• The booking count (or duration) is deducted at the time of booking creation, not at the time of approval. This is the same behavior as confirmed bookings.

• If the host later rejects the booking, the value is refunded (see above).

8. Purchase Code Validation

When a customer enters a package purchase code on the scheduling link:

• Duration-based: Code is valid if remaining duration >= meeting's duration.

• Booking-based: Code is valid if remaining bookings >= 1.

9. Admin Purchase Management

On the admin purchase detail page, hosts can manually adjust a purchase's remaining value:

Validation: Cannot deduct more than the remaining value.

10. Package Purchase (Customer Side)

When a customer purchases a booking-based package:

• The purchase is created with bookings_remaining set to the package's total_bookings.

• Code expiry works identically for both package types (independent of type).

UI Changes

Package Form (Create/Edit) — Admin

Package List Table — Admin

Package Show Page (Details Card) — Admin

Purchase History Table (Package Show Page) — Admin

Admin Purchase Detail Page

Public Package Page (Live Booking Page)

Intro Page (Package Cards)

Purchase Confirmation Page (Customer-Facing)

Discount / Purchase Code Section (Live Booking Payment Page)

---

Activity Tracking

New Activity Types

Modified Activity

---

Email Changes

Purchase-related emails (purchase confirmation to customer and host):

---

Text & Label Changes (Complete List)

---

Edge Cases & Scenarios

---

Design Decisions

1. Unified terminology: "Package limit" and "Remaining limit": All labels use unified terms regardless of package type. "Package limit" is used for the total value (list table, show page, purchase detail, purchase confirmation). "Remaining limit" is used for the remaining value. "Update remaining limit" is used for the modal title. The values themselves are type-specific (e.g., "2 hours" for duration, "5 bookings" for booking-based), but the labels are always the same.

2. Duration display supports minutes and hours: Package durations are displayed in the most natural unit. Values evenly divisible by 60 are shown in hours (e.g., 120 minutes → "2 hours"), otherwise in minutes (e.g., 90 minutes → "90 minutes"). This matches the behavior of meeting duration display elsewhere in the application.

3. Radio button cards instead of dropdown: The package type selector uses two radio button cards rather than a dropdown. Cards remain fully visible at all times, showing the type name and a short description. The selected card is highlighted with a green border and background; its inline input fields expand below the description. This avoids the "hidden option" problem of a collapsed dropdown and gives users immediate visual context about both options before choosing.

Neither card is pre-selected on the create page. If the user tries to save without selecting, an inline error message is shown beneath the cards.

4. Duration input retains hours/minutes dropdown: The duration input keeps the hours/minutes dropdown from the existing form, since durations are now displayed in both minutes and hours.

5. Calendar icon for booking-based: On the live package page, the clock icon is semantically tied to time/duration. For booking-based packages, a Calendar icon is used instead to represent discrete sessions.

6. Duration and price on purchase confirmation scheduling links: The meeting cards on the purchase confirmation page now show the meeting's duration (with a clock icon) and either the price or "Free" below the meeting name. Previously only the name and "Book now" button were shown. This gives the customer enough context to choose which scheduling link to book without leaving the page.

7. Pre-fill via URL params: When a customer clicks "Book now" on the purchase confirmation page, their name and email are passed as URL parameters to the scheduling link. The scheduling link's pre-fill feature handles the rest, so the customer doesn't have to re-enter their information.

8. Booking deduction at creation time: For bookings that require approval, the booking count is deducted when the booking is created (not when approved). If the host rejects it, the count is restored. This prevents overbooking during the approval wait period.

9. Per-occurrence deduction for recurring: Each occurrence of a recurring booking deducts from the booking count based on the number of spots reserved. A 4-session recurring booking with 1 spot deducts 4 bookings; with 2 spots it deducts 8. This ensures the booking count accurately reflects the number of sessions consumed.

10. Group booking spots multiply deductions: For group meetings where a customer reserves multiple spots, the deduction is always multiplied by the number of spots — for both duration-based and booking-based packages. This applies consistently across booking, cancellation, rejection, and recurring flows.