unsupervised-scheduler/docs/features/offerings.md

Feature: Offerings

Overview

An offering is anything a student can register for: a private-lesson type (30 or 60 minutes, single or weekly) or a group class. Offerings carry pricing, billing mode, and the intake questions a registrant must answer. They are the catalog the booking calendar and group-class pages are built from.

Data Model — {prefix}us_offerings

Column	Type	Notes
id	BIGINT UNSIGNED	Primary key
instructor_id	BIGINT UNSIGNED	WordPress user ID of the owning instructor
kind	VARCHAR(20)	private_lesson or group_class
title	VARCHAR(191)	Display name
description	TEXT	Optional longer description
duration_minutes	SMALLINT	Private lessons only (e.g. 30, 60); NULL for group classes
price	DECIMAL(10,2)	Price in dollars
currency	VARCHAR(3)	ISO 4217, e.g. CAD
billing_mode	VARCHAR(20)	one_time, full_term, weekly, or monthly (see Billing Mode below)
allow_weekly	TINYINT(1)	Private only — may be reserved weekly for the term
capacity	SMALLINT	Group only — max enrolments; NULL for private
term_start	DATE	Group / term offerings — first day; NULL otherwise
term_end	DATE	Group / term offerings — last day; NULL otherwise
class_time	TIME	Group only — time of day each session starts; NULL otherwise
enrollment_deadline	DATE	Group only — last day students may enrol; NULL defaults to term_start (the first class day)
withdrawal_deadline	DATE	Group only — last day a student may withdraw themselves; NULL keeps self-withdrawal open indefinitely
schedule_note	VARCHAR(191)	Group only — human-readable schedule, e.g. "Tuesdays 4:00pm"
cancellation_cutoff_hours	SMALLINT UNSIGNED	Optional per-offering cancellation cutoff in hours; NULL inherits the studio default (see cancellation-cutoff.md)
access_mode	VARCHAR(20)	public (listed in the catalog) or invite_only (group classes hidden from the catalog — see group-classes.md)
is_active	TINYINT(1)	0 = hidden from registration, 1 = bookable
created_at	DATETIME	Insertion time

Billing Mode

• one_time — charged once at booking (a single private lesson).
• full_term — charged in full upfront at registration (a weekly private reservation or a year-long group class). See payments.md.
• weekly — not charged at registration; a pending payment for one lesson's fee is generated 24 hours before each lesson by the daily billing scan.
• monthly — not charged at registration; on the 1st of each month a single pending payment is generated for every lesson that falls in that month (4 lessons ⇒ 4 × fee).

Students see the mode as a cadence beside every price on the front end — at booking, up front, weekly, monthly — and confirm it explicitly before a booking or enrolment goes through. See Price Display and the Pay Agreement in payments.md.

weekly and monthly are scheduled billing (Offering::isScheduledBilling()): the booking/enrolment succeeds with no payment step, and payments are created later by the daily us_generate_due_payments cron scan. See scheduled-billing.md and payments.md.

Term Dates

Group classes carry a term: term_start is the date of the first class and term_end the last. The add-offering form takes a start date plus a sessions control — one-off (the term ends the day it starts) or weekly for N sessions (term_end = term_start + (N−1) weeks, computed by Offering::weeklyTermEnd()). Dates are validated by Offering::normalizeDate() (strict Y-m-d); an invalid start date leaves both term columns NULL. The student-facing class card shows the date (one-off) or the date range with the weekly session count.

Class Time and Sessions

A group class also carries class_time — the time of day each session starts — validated by Offering::normalizeTime() (strict H:i/H:i:s; garbage leaves it NULL). class_time + term_start/term_end + duration_minutes together define the concrete session windows: Offering::sessionWindows() returns one {start, end} per session (weekly across the term, or a single window for a one-off), and returns an empty list unless date, time, and a positive duration are all set. These windows drive availability reconciliation (see Instructor assignment below and group-classes.md).

Enrolment deadline

A group class carries an optional enrollment_deadline the instructor sets on the offering form (blank leaves it NULL). Offering::effectiveEnrollmentDeadline() resolves it to the stored date, or to term_start (the first class day) when unset, so a class with no explicit deadline still closes to new enrolments once the first class arrives. Offering::isEnrollmentOpen($today) compares a Y-m-d "today" against that effective deadline (inclusive — the deadline day is still open). The enrolment endpoint enforces it (403 enrollment_closed) and the front-end group-class list mirrors the same rule; see group-classes.md.

Withdrawal deadline

A group class also carries an optional withdrawal_deadline — the last day a student may withdraw themselves from the class. Unlike the enrolment deadline it has no implicit default: Offering::isWithdrawalOpen($today) treats an unset (NULL) deadline as always open, so a class only closes to self-withdrawal once the instructor sets a date and it passes (comparison is inclusive — the deadline day is still open). A withdrawal made while open frees the seat and voids any still-pending payment but never issues an account credit (credits are reserved for cancelled lessons; see credits.md). Once the deadline passes the student must contact the studio, and an admin withdraws them by hand from the student detail page — the admin path is never subject to the deadline. The student endpoint enforces it (403 withdrawal_closed) and the front-end group-class list mirrors the rule; see group-classes.md.

Instructor assignment

Every offering has an owning instructor_id. A studio admin (manage_instructors) sees an Instructor picker on the offering form and may assign a group class to any instructor; a plain instructor never sees the picker and always owns the classes they create (the posted value is ignored for them, and updates never reassign the owner otherwise). When a group class is saved with an assigned instructor and a full schedule, Offering\ClassSlotReconciler clears that instructor's open availability slots overlapping each session so students can't book them, and reports any already-booked lesson that clashes as a conflict for the studio to resolve by hand (a booked lesson is never deleted). The result is surfaced as an admin notice after saving.

Admin Interface

Studio admin and instructors manage offerings under Offerings in wp-admin.

• Studio admin (manage_offerings) manages offerings for any instructor.
• Instructor (manage_offerings) manages only their own.
• Each offering's intake questions are edited from the offering screen (see registration-questions.md).
• The offerings list shows each offering's ID (needed for [us_group_classes offering="…"]) and its term dates.
• Edit on a row reloads the page (?usc_edit=<id>) with the form prefilled; saving posts usc_action=update. Owner and currency are always preserved on update, so a form submission can never reassign an offering. Non-admin instructors can only load and update their own offerings.
• The form includes a description textarea and an Active — open for registration checkbox (unchecking hides the offering from students without deleting it — the admin-UI counterpart of the REST is_active flag).

REST API

Method	Endpoint	Permission
GET	/wp-json/us-scheduler/v1/offerings	book_lesson or manage_offerings (active offerings only)
POST	/wp-json/us-scheduler/v1/offerings	manage_offerings
PATCH	/wp-json/us-scheduler/v1/offerings/{id}	manage_offerings + owner
DELETE	/wp-json/us-scheduler/v1/offerings/{id}	manage_offerings + owner

GET supports query params: instructor_id, kind.

Implementation

• Repository: Unsupervised\Schedular\Offering\OfferingRepository
• Model: Unsupervised\Schedular\Offering\Offering (normalizeTime, sessionWindows, effectiveEnrollmentDeadline, isEnrollmentOpen)
• Admin controller: Unsupervised\Schedular\Offering\OfferingController
• REST endpoint: Unsupervised\Schedular\Offering\OfferingEndpoint (public listing includes instructor_name)
• Availability reconciliation: Unsupervised\Schedular\Offering\ClassSlotReconciler (uses Availability\AvailabilityRepository::findOverlapping)

Tests

• tests/Unit/Offering/OfferingControllerTest.php
• tests/Unit/Offering/OfferingRepositoryTest.php
• tests/Unit/Offering/OfferingTest.php
• tests/Unit/Offering/OfferingEndpointTest.php
• tests/Unit/Offering/ClassSlotReconcilerTest.php