2026-07-28 18:35:36 +00:00
15 changed files with 465 additions and 26 deletions
@@ -13,6 +13,13 @@ each change under the current top section as you work.

 ## [1.2.3]

+### Changed
+- A **monthly group class is now billed its price once per month**, however many times the class meets in that month. Previously the monthly charge multiplied the price by the number of sessions in the month — a class priced at `40.00 CAD` meeting weekly was billed `160.00 CAD` on the 1st — which no studio could quote honestly on a class card. A monthly **private lesson** is unchanged: its price is a per-lesson fee and the month is still billed one fee per lesson, which is why it is quoted per lesson. Studios running a monthly group class should check the class price now reads as the monthly fee they intend to charge.
+
+### Added
+- Every price a student sees now says **when** it is due. Lesson types in the booking form read `50.00 CAD at booking`, and group-class cards read `120.00 CAD up front`, `40.00 CAD weekly` or `40.00 CAD monthly` — the offering's billing mode, in the student's words. A monthly **private lesson** is quoted per lesson (`50.00 CAD per lesson monthly`), since its monthly charge covers every lesson booked that month; a monthly group class is quoted as the monthly figure it is. A free offering still just reads **Free**.
+- Booking a lesson and enrolling in a class now take a **second confirmation that the student agrees to pay**. Above the Confirm button the form restates the price with its cadence, spells out how it is collected ("Charged on the 1st of each month, for that month's lessons"), adds the studio's HST so the figure matches the total actually billed, and requires a tick on "I agree to pay 56.50 CAD at booking." before it will submit — separate from, and in addition to, the studio policies the student accepts above it. Reserving a time weekly quotes the per-lesson fee and the most it can add up to ("up to 12 lessons, 678.00 CAD in total"), since a week another student takes first is simply not booked. Free offerings have nothing to agree to and show no price block.
+
 ## [1.2.2]

 ### Added
@@ -241,6 +241,47 @@
    opacity: 0.4;
 }

+/* The price and pay agreement on a booking / enrolment form. */
+.us-price {
+    border: 1px solid #ddd;
+    border-radius: 4px;
+    padding: 12px 16px;
+    margin: 16px 0;
+}
+
+.us-price h4 {
+    margin: 0 0 8px;
+}
+
+.us-price p {
+    margin: 0 0 4px;
+}
+
+.us-price-amount strong {
+    font-size: 1.15em;
+}
+
+.us-price-cadence {
+    margin-left: 4px;
+}
+
+.us-price-tax,
+.us-price-note {
+    font-size: 0.9em;
+    opacity: 0.8;
+}
+
+.us-price-agree {
+    display: block;
+    margin-top: 12px;
+    font-weight: 600;
+}
+
+/* The cadence-carrying price on a group-class card. */
+.us-class-price {
+    font-weight: 600;
+}
+
@media (max-width: 640px) {
    .us-week-grid {
        grid-template-columns: 1fr;
@@ -360,13 +360,27 @@
            </div>`;
    }

-    // "Piano Lesson (60 min — $50.00 CAD)" / "Trial Lesson (Free)"
+    // "Piano Lesson (60 min — 50.00 CAD at booking)" / "Trial Lesson (Free)"
    function offeringLabel(o) {
        const duration = o.duration_minutes ? `${o.duration_minutes} min — ` : '';
-        const price = Number(o.price) > 0
-            ? `$${Number(o.price).toFixed(2)} ${o.currency}`
-            : 'Free';
-        return `${o.title} (${duration}${price})`;
+        return `${o.title} (${duration}${window.usPricing.priceLabel(o)})`;
+    }
+
+    // How many lessons a weekly reservation can claim, mirroring
+    // BookingEndpoint::MAX_WEEKLY_OCCURRENCES so the quoted total is never
+    // higher than the server will actually charge for.
+    const MAX_WEEKLY_OCCURRENCES = 12;
+
+    // The open times a weekly reservation of this slot would claim: every
+    // still-unbooked slot of its recurring group, capped the way the server
+    // caps it. Some may be taken by another student first, so this is the
+    // upper bound on what will be booked, not a guarantee.
+    function weeklyOccurrences(slot) {
+        if (!slot.recurrence_group) return 1;
+
+        const inGroup = allSlots.filter((s) => s.recurrence_group === slot.recurrence_group).length;
+
+        return Math.min(Math.max(inGroup, 1), MAX_WEEKLY_OCCURRENCES);
    }

    function openRegistration(slot) {
@@ -443,6 +457,7 @@
                    <div id="us-questions"></div>
                    ${policies.map(policyField).join('')}
                    ${weekly}
+                    <div id="us-price-summary"></div>
                    <p>
                        <button type="submit" class="us-book-btn">Confirm Booking</button>
                        <button type="button" id="us-cancel" class="us-cancel-btn">Back</button>
@@ -458,6 +473,27 @@
        let questions  = [];

        const questionsBox = document.getElementById('us-questions');
+        const priceBox     = document.getElementById('us-price-summary');
+        const weeklyEl     = document.getElementById('us-weekly');
+
+        // What the booking will cost and the agreement to pay it, restated
+        // whenever the choices that decide the amount change: the lesson type
+        // carries the price, and a weekly reservation multiplies a per-lesson
+        // one-time price by every week it claims. A slot tied to a type the
+        // catalog no longer carries has no price to quote, so it shows nothing
+        // rather than a figure it cannot stand behind.
+        function renderPrice() {
+            const offering = selectedId ? catalog.find((o) => Number(o.id) === selectedId) : null;
+            priceBox.innerHTML = offering
+                ? window.usPricing.summaryHtml({
+                    price: offering.price,
+                    currency: offering.currency,
+                    billing_mode: offering.billing_mode,
+                    kind: offering.kind,
+                    occurrences: weeklyEl && weeklyEl.checked ? weeklyOccurrences(slot) : 1,
+                })
+                : '';
+        }

        function loadQuestions() {
            questions = [];
@@ -475,10 +511,14 @@
            document.getElementById('us-offering').addEventListener('change', (e) => {
                selectedId = Number(e.target.value) || 0;
                loadQuestions();
+                renderPrice();
            });
        }

+        if (weeklyEl) weeklyEl.addEventListener('change', renderPrice);
+
        loadQuestions();
+        renderPrice();

        document.getElementById('us-cancel').addEventListener('click', loadSlots);
        document.getElementById('us-register-form').addEventListener('submit', (e) => {
@@ -487,6 +527,10 @@
                showError('Please choose a lesson type.');
                return;
            }
+            if (!window.usPricing.agreed(e.target)) {
+                showError(window.usPricing.AGREE_REQUIRED);
+                return;
+            }
            submitBooking(e.target, slot, selectedId, questions);
        });
    }
@@ -152,7 +152,7 @@
                ${o.instructor_name ? `<p class="us-class-instructor">With ${escHtml(o.instructor_name)}</p>` : ''}
                ${o.schedule_note ? `<p>${escHtml(o.schedule_note)}</p>` : ''}
                ${!singleOfferingId && o.description ? `<p>${escHtml(o.description)}</p>` : ''}
-                <p>${escHtml(Number(o.price).toFixed(2))} ${escHtml(o.currency)}</p>
+                <p class="us-class-price">${escHtml(window.usPricing.priceLabel(o))}</p>
                ${!enrolledMap.has(Number(o.id)) && isEnrollmentOpen(o) && enrolmentDeadline(o)
        ? `<p class="us-enrol-deadline">Enrol by ${escHtml(formatDate(enrolmentDeadline(o)))}</p>`
        : ''}
@@ -204,6 +204,7 @@
                <form id="us-enrol-form">
                    ${questions.map(questionField).join('')}
                    ${policies.map(policyField).join('')}
+                    ${window.usPricing.summaryHtml(offering)}
                    <p>
                        <button type="submit" class="us-enrol-btn">Confirm Enrolment</button>
                        <button type="button" id="us-group-cancel" class="us-cancel-btn">Back</button>
@@ -214,6 +215,10 @@
        document.getElementById('us-group-cancel').addEventListener('click', loadClasses);
        document.getElementById('us-enrol-form').addEventListener('submit', (e) => {
            e.preventDefault();
+            if (!window.usPricing.agreed(e.target)) {
+                showError(window.usPricing.AGREE_REQUIRED);
+                return;
+            }
            submitEnrolment(e.target, offering, questions);
        });
    }
@@ -0,0 +1,170 @@
+/* global usScheduler */
+(function () {
+    'use strict';
+
+    // Cadence wording for each offering billing mode, in the phrasing a student
+    // sees beside a price. Mirrors Offering::VALID_BILLING_MODES.
+    const CADENCE = {
+        one_time: 'at booking',
+        full_term: 'up front',
+        weekly: 'weekly',
+        monthly: 'monthly',
+    };
+
+    // How each cadence is actually collected, spelled out beneath the price so
+    // the one-word cadence is never the only thing a student has to go on.
+    const CADENCE_NOTE = {
+        one_time: 'Charged once, when you book.',
+        full_term: 'Charged once, up front, for the whole term.',
+        weekly: 'Charged for each lesson, 24 hours before it starts.',
+        monthly: 'Charged on the 1st of each month, for that month’s lessons.',
+    };
+
+    // The billing modes whose price is a per-lesson fee billed again and again,
+    // rather than a single charge. Mirrors Offering::SCHEDULED_BILLING_MODES.
+    const RECURRING = ['weekly', 'monthly'];
+
+    function escHtml(str) {
+        return String(str)
+            .replace(/&/g, '&amp;')
+            .replace(/</g, '&lt;')
+            .replace(/>/g, '&gt;')
+            .replace(/"/g, '&quot;');
+    }
+
+    function mode(billingMode) {
+        return CADENCE[billingMode] ? billingMode : 'one_time';
+    }
+
+    // A monthly charge rolls up every lesson that falls in the month, so a
+    // private lesson's monthly price is quoted *per lesson* — the fee is
+    // multiplied by the lessons booked that month. A group class is enrolled in
+    // once, as one schedule, so its monthly figure is quoted as it stands.
+    function isPerLessonMonthly(billingMode, kind) {
+        return 'monthly' === billingMode && 'group_class' !== kind;
+    }
+
+    // "50.00 CAD" — amount then currency code, the format used throughout the
+    // ledger, receipts and payment notices.
+    function money(amount, currency) {
+        return `${(Number(amount) || 0).toFixed(2)} ${String(currency || '')}`.trim();
+    }
+
+    // The studio's HST rate as a percentage, frozen onto every payment at
+    // booking time (comped students are the one exception — they are not taxed).
+    function taxRate() {
+        return Number(usScheduler.taxRate) || 0;
+    }
+
+    // Tax on a pre-tax amount, rounded the same way PaymentService does.
+    function tax(amount) {
+        return Math.round((Number(amount) || 0) * taxRate()) / 100;
+    }
+
+    function total(amount) {
+        return (Number(amount) || 0) + tax(amount);
+    }
+
+    // "50.00 CAD at booking" / "50.00 CAD per lesson monthly" / "Free" — the
+    // catalogue label, always carrying the cadence so a price is never shown
+    // without saying when it is due.
+    function priceLabel(offering) {
+        const price = Number(offering.price) || 0;
+        if (price <= 0) {
+            return 'Free';
+        }
+
+        const billingMode = mode(offering.billing_mode);
+        const perLesson   = isPerLessonMonthly(billingMode, offering.kind) ? 'per lesson ' : '';
+
+        return `${money(price, offering.currency)} ${perLesson}${CADENCE[billingMode]}`;
+    }
+
+    // The price block shown on a booking/enrolment form, followed by the
+    // agreement the student must tick to confirm they will pay it. A free
+    // offering has nothing to agree to, so it renders nothing at all.
+    //
+    // opts: { price, currency, billing_mode, kind, occurrences }
+    // `occurrences` is how many lessons a one-time price is charged for in this
+    // one registration (a weekly reservation claims several at once); it is
+    // ignored for the other modes, whose price is charged per period regardless.
+    function summaryHtml(opts) {
+        const price = Number(opts.price) || 0;
+        if (price <= 0) {
+            return '';
+        }
+
+        const billingMode = mode(opts.billing_mode);
+        const currency    = opts.currency;
+        const each        = total(price);
+        const count       = 'one_time' === billingMode ? Math.max(1, Number(opts.occurrences) || 1) : 1;
+
+        const taxLine = taxRate() > 0
+            ? `<p class="us-price-tax">${escHtml(`Plus ${taxRate()}% HST — ${money(each, currency)}${count > 1 ? ' per lesson' : ''}.`)}</p>`
+            : '';
+
+        return `
+            <div class="us-price">
+                <h4>Price</h4>
+                <p class="us-price-amount">
+                    <strong>${escHtml(money(price, currency))}</strong>
+                    <span class="us-price-cadence">${escHtml(cadenceLabel(billingMode, opts.kind))}</span>
+                </p>
+                ${taxLine}
+                <p class="us-price-note">${escHtml(count > 1
+                    ? 'Charged once, when you book — for every week reserved.'
+                    : CADENCE_NOTE[billingMode])}</p>
+                <label class="us-price-agree">
+                    <input type="checkbox" class="us-price-accept" required>
+                    ${escHtml(agreeText(each, currency, billingMode, count, opts.kind))}
+                </label>
+            </div>`;
+    }
+
+    // The cadence as it reads beside an amount: a private lesson billed monthly
+    // adds "per lesson", since the month's charge is that fee times the lessons
+    // it covers.
+    function cadenceLabel(billingMode, kind) {
+        return isPerLessonMonthly(billingMode, kind)
+            ? `per lesson ${CADENCE[billingMode]}`
+            : CADENCE[billingMode];
+    }
+
+    // What the student is ticking: the amount actually billed (tax included),
+    // and when. A weekly reservation is charged per lesson for every week it
+    // claims, and the claim can come up short when another student takes one of
+    // the times first — so its total is stated as a ceiling, never a promise.
+    function agreeText(each, currency, billingMode, count, kind) {
+        if (RECURRING.indexOf(billingMode) !== -1) {
+            // A monthly group class is enrolled in once and quoted as it stands;
+            // everything else recurring is a per-lesson fee.
+            return 'monthly' === billingMode && !isPerLessonMonthly(billingMode, kind)
+                ? `I agree to pay ${money(each, currency)} monthly.`
+                : `I agree to pay ${money(each, currency)} per lesson, billed ${CADENCE[billingMode]}.`;
+        }
+
+        if (count > 1) {
+            return `I agree to pay ${money(each, currency)} per lesson at booking — `
+                + `up to ${count} lessons, ${money(each * count, currency)} in total.`;
+        }
+
+        return `I agree to pay ${money(each, currency)} ${CADENCE[billingMode]}.`;
+    }
+
+    // Whether the payment agreement has been ticked. A form without one (a free
+    // offering) has nothing outstanding, so it counts as agreed.
+    function agreed(root) {
+        const box = root.querySelector('.us-price-accept');
+
+        return !box || box.checked;
+    }
+
+    // Shared by the booking and group-class flows so a price reads the same
+    // wherever a student meets it.
+    window.usPricing = {
+        priceLabel,
+        summaryHtml,
+        agreed,
+        AGREE_REQUIRED: 'Please confirm you agree to pay the amount shown.',
+    };
+}());
@@ -38,12 +38,13 @@ shows "You are enrolled in this class." instead of the Enrol button (the
 server would reject the duplicate with `409 already_enrolled` regardless — a
 cancelled enrolment does not block re-enrolling).

-1. Student opens a group class from the offering catalog.
+1. Student opens a group class from the offering catalog. Each class card shows its price with the **cadence** it is billed on — `120.00 CAD up front`, `40.00 CAD monthly`, and so on.
 2. Student answers the offering's questions (`GET /offerings/{id}/questions`).
 3. Student accepts the current published policy versions (`GET /policies`) — required to continue.
-4. Full-term payment is taken per the student's billing method (card by default; `pending` for e-transfer; skipped for comp). See `payments.md`.
-5. `POST /enrollments` creates the enrolment (`status = active`), records answers and policy acceptances, and links the payment — but only if the offering's `capacity` has not been reached.
-6. On successful payment (or comp) a receipt is emailed.
+4. The enrolment form restates the price (with HST) and requires a second, separate agreement to pay that amount before it will submit. See **Price Display and the Pay Agreement** in `payments.md`.
+5. Full-term payment is taken per the student's billing method (card by default; `pending` for e-transfer; skipped for comp). See `payments.md`.
+6. `POST /enrollments` creates the enrolment (`status = active`), records answers and policy acceptances, and links the payment — but only if the offering's `capacity` has not been reached.
+7. On successful payment (or comp) a receipt is emailed.

 Capacity is enforced at enrolment time by counting `active` rows for the offering;
 a class at capacity rejects further enrolments.
@@ -25,11 +25,12 @@ Students register for a private lesson by choosing an offering, picking a time (
 3. For a `weekly` reservation, the same weekday/time is held for the rest of the offering's term.
 4. Student answers the offering's questions (`GET /offerings/{id}/questions`).
 5. Student accepts the current published policy versions (`GET /policies`) — required to continue.
-6. Payment is taken per the student's billing method (card by default; `pending` for e-transfer; skipped for comp). See `payments.md`.
-7. `POST /bookings` creates the lesson row(s) (`status = pending`), records answers and policy acceptances, marks `us_availability.is_booked = 1`, and links the payment. A booking with nothing owed (a free offering) creates no payment and is `confirmed` immediately.
-8. On successful payment (or comp) the lesson is `confirmed` and a receipt is emailed.
-9. Instructor sees the booking under **My Lessons** and may update status via `PATCH /bookings/{id}/status`.
-10. The booking page also shows the student their upcoming lessons (`GET /bookings`) — each with the booked offering's name and length, when it happens, a per-lesson status badge (pending payment / confirmed), and a **Cancel** button. Only the soonest five are shown; a **Show all** control reveals the rest. `GET /bookings` includes `offering_title` and `duration_minutes` for each lesson so the list needs no extra request.
+6. Student is shown what the booking costs — the offering's price with its **cadence** (at booking / up front / weekly / monthly), plus HST — and must tick a second, separate agreement to pay that amount before the form will submit. A weekly reservation quotes the per-lesson fee and the ceiling on the total it can claim. A free offering shows no price block. See **Price Display and the Pay Agreement** in `payments.md`.
+7. Payment is taken per the student's billing method (card by default; `pending` for e-transfer; skipped for comp). See `payments.md`.
+8. `POST /bookings` creates the lesson row(s) (`status = pending`), records answers and policy acceptances, marks `us_availability.is_booked = 1`, and links the payment. A booking with nothing owed (a free offering) creates no payment and is `confirmed` immediately.
+9. On successful payment (or comp) the lesson is `confirmed` and a receipt is emailed.
+10. Instructor sees the booking under **My Lessons** and may update status via `PATCH /bookings/{id}/status`.
+11. The booking page also shows the student their upcoming lessons (`GET /bookings`) — each with the booked offering's name and length, when it happens, a per-lesson status badge (pending payment / confirmed), and a **Cancel** button. Only the soonest five are shown; a **Show all** control reveals the rest. `GET /bookings` includes `offering_title` and `duration_minutes` for each lesson so the list needs no extra request.

 ## Lesson-Type Filter
 Not every open slot can be booked as every private-lesson type — a slot tied to
@@ -33,7 +33,12 @@ An offering is anything a student can register for: a private-lesson type (30 or
 - `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).
+- `monthly` — **not** charged at registration; on the **1st of each month** a single pending payment is generated for that month. A **private lesson**'s price is a per-lesson fee, so the month is billed (#lessons in the month) × fee; a **group class**'s price is the monthly fee itself, billed once for the month however many times the class meets in it.
+
+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
@@ -98,6 +98,59 @@ After booking, the destination on a payment can be corrected per booking:
 | `created_at`               | DATETIME         | Insertion time                                        |
 | `paid_at`                  | DATETIME         | When marked `paid`; NULL otherwise                    |

+## Price Display and the Pay Agreement
+Every price a student is shown on the front end carries its **cadence** — the
+offering's `billing_mode` in the words the student needs:
+
+| `billing_mode` | Shown as                          | Explained beneath as                                       |
+|----------------|-----------------------------------|------------------------------------------------------------|
+| `one_time`     | `at booking`                      | Charged once, when you book.                               |
+| `full_term`    | `up front`                        | Charged once, up front, for the whole term.                |
+| `weekly`       | `weekly`                          | Charged for each lesson, 24 hours before it starts.        |
+| `monthly`      | `per lesson monthly` / `monthly`  | Charged on the 1st of each month, for that month's lessons.|
+
+So a lesson type reads `50.00 CAD at booking` in the booking form's type picker,
+and a group class card reads `120.00 CAD up front`. A free offering shows `Free`.
+
+**`monthly` reads differently per offering kind, because it *bills* differently.**
+A private lesson's price is a per-lesson fee and its monthly charge is that
+month's lessons × the fee, so the fee is quoted **per lesson**
+(`50.00 CAD per lesson monthly`). A monthly group class is priced **per month** —
+`ScheduledBillingRunner::billGroupMonthly()` charges the fee once for the month
+however many times the class meets in it — so its figure is quoted as it stands
+(`120.00 CAD monthly`). The display split is `isPerLessonMonthly()` in
+`assets/js/pricing.js`; the billing split is the one place the monthly rule
+differs between the two kinds.
+
+Before a booking or enrolment can be submitted, the form shows the price again as
+a summary block with a **required agreement checkbox** — the second confirmation,
+distinct from the policy acceptances above it:
+
+> ☐ I agree to pay 56.50 CAD at booking.
+
+The agreed figure is the amount actually billed, so the studio **HST rate** is
+added to it (`usScheduler.taxRate`, localized from `us_hst_rate`) and broken out
+above the checkbox — matching the total `Payment::total()` charges. A comped
+student is not taxed and is not charged at all, so for them the quoted figure is
+an upper bound. A free offering has nothing to agree to and shows no block.
+
+Cadence-specific wording:
+
+- **Weekly reservation of a `one_time` lesson type** — the fee is charged once per
+  week claimed, so the agreement states the per-lesson amount and the total as a
+  ceiling ("up to 12 lessons, 678.00 CAD in total"). The occurrence count mirrors
+  `BookingEndpoint::MAX_WEEKLY_OCCURRENCES`; a slot another student takes first is
+  simply not claimed, so the real charge can come in under it.
+- **`weekly` / `monthly`** — nothing is taken at registration, so the agreement is
+  to the recurring charge: "I agree to pay 56.50 CAD per lesson, billed monthly."
+  A monthly **group class** agrees to its monthly figure instead ("I agree to pay
+  138.00 CAD monthly."), matching how its price is quoted on the card.
+
+All of this lives in `assets/js/pricing.js` (`window.usPricing`), shared by the
+booking and group-class flows so a price reads the same wherever it is met. The
+script is registered as `us-scheduler-pricing` and is a dependency of both
+`us-scheduler` and `us-scheduler-group`.
+
 ## Payment Flow
 1. During registration the front-end calls `POST /payments/intent` — but only when the registration response carried a `payment` summary (unpriced registrations return `payment: null` and skip the payment step). The intent call creates a Stripe PaymentIntent for a `card` student and returns the client secret. (`etransfer` returns a `pending` payment; `comp` returns none.)
 2. The browser confirms the card payment with Stripe.
@@ -139,8 +192,10 @@ See `payment-reporting.md` for the monthly report and CSV export endpoints.
 - Receipts: `Unsupervised\Schedular\Payment\ReceiptMailer`
 - Settings page: `Unsupervised\Schedular\Payment\StudioSettings`
 - REST endpoint: `Unsupervised\Schedular\Payment\PaymentEndpoint`
+- Front-end price display + pay agreement: `assets/js/pricing.js` (`window.usPricing`), registered and localized with `taxRate` by `Unsupervised\Schedular\ShortcodeRegistrar`

 ## Tests
+- `tests/Unit/ShortcodeRegistrarTest.php` (pricing helper registration + localized `taxRate`)
 - `tests/Unit/Payment/PaymentRepositoryTest.php`
 - `tests/Unit/Payment/PaymentTest.php`
 - `tests/Unit/Payment/StripeGatewayTest.php`
@@ -6,7 +6,9 @@ payments on a recurring schedule:

 - **`weekly`** — one payment per lesson, due **24 hours before** that lesson.
 - **`monthly`** — one payment per calendar month, due on the **1st**, covering every
-  lesson that falls in the month (4 lessons ⇒ 4 × fee).
+  lesson that falls in the month. A **private lesson**'s fee is per lesson, so the
+  month costs (#lessons) × fee. A **group class**'s fee is per month: the class is
+  billed that fee once for the month, however many times it meets in it.

 Both apply to **private lessons** and **group classes**. At registration the
 booking/enrolment succeeds with `payment: null` (no payment step); the lesson is
@@ -29,7 +31,7 @@ method resolution, e-transfer freezing, comp auto-pay reused) with a `due_date`
 | **Private weekly** | lesson `start_dt` ≤ now + 24h | 1 × fee | `us_lessons.payment_id` set on the lesson |
 | **Private monthly** | the lesson's month's 1st ≤ today | (#lessons in month) × fee | `payment_id` set on every lesson in the month |
 | **Group weekly** | session (from `Offering::sessionWindows()`) − 1 day ≤ now | 1 × fee | `us_payments.period_key` = session date |
-| **Group monthly** | the month's 1st ≤ today | (#sessions in month) × fee | `period_key` = `YYYY-MM` |
+| **Group monthly** | the month's 1st ≤ today | 1 × fee (a monthly class is priced per month, not per session) | `period_key` = `YYYY-MM` |

 - Private lessons dedup on `us_lessons.payment_id IS NULL` — a lesson with no payment is
  unbilled. A monthly group links its earliest lesson via `createForRegistration` and the
@@ -118,11 +118,13 @@ class BlockPreview {
 			: '<p>' . esc_html__( 'A sample class shown so the page can be styled.', 'unsupervised-schedular' ) . '</p>';

 		return sprintf(
-			'<div id="us-group-app">%s<div id="us-group-list"><div class="us-class"><h3>%s</h3><p class="us-class-when">%s</p>%s<p>25.00 CAD</p><p class="us-enrol-deadline">%s</p><button type="button" class="us-enrol-btn" disabled>%s</button></div></div></div>',
+			'<div id="us-group-app">%s<div id="us-group-list"><div class="us-class"><h3>%s</h3><p class="us-class-when">%s</p>%s<p class="us-class-price">%s</p><p class="us-enrol-deadline">%s</p><button type="button" class="us-enrol-btn" disabled>%s</button></div></div></div>',
 			self::note( $note ),
 			esc_html__( 'Beginner Group Class', 'unsupervised-schedular' ),
 			esc_html__( 'Saturdays 10:00 AM–11:00 AM', 'unsupervised-schedular' ),
 			$description,
+			// Prices on the live page always carry their cadence, so the sample does too.
+			esc_html__( '25.00 CAD up front', 'unsupervised-schedular' ),
 			esc_html__( 'Enrol by Sep 6, 2026', 'unsupervised-schedular' ),
 			esc_html__( 'Enrol', 'unsupervised-schedular' )
 		);
@@ -251,11 +251,18 @@ class ScheduledBillingRunner {
 	/**
 	 * Bill one payment per calendar month of a group class, once its 1st arrives.
 	 *
+	 * A monthly group class is priced **per month**, not per session: the fee is
+	 * charged once for the month however many times the class meets in it. This is
+	 * what the student is quoted and agrees to on the way in ("40.00 CAD monthly"),
+	 * and it is the one place the monthly rule differs from private lessons, whose
+	 * per-lesson fee is multiplied by the lessons that fall in the month.
+	 *
 	 * @param list<array{start: string, end: string}> $windows
 	 * @param array<int, list<array{payment: Payment, label: string}>> $buckets
 	 */
 	private function billGroupMonthly( \DateTimeImmutable $now, string $today, Enrollment $enrollment, Offering $offering, array $windows, array &$buckets ): void { // phpcs:ignore Generic.CodeAnalysis.UnusedFunctionParameter.Found
-		// Count this enrolment's sessions per calendar month.
+		// Count this enrolment's sessions per calendar month. The count does not
+		// price the month — it names it on the student's notice ("3 sessions").
 		$months = [];
 		foreach ( $windows as $window ) {
 			$start                             = new \DateTimeImmutable( $window['start'] );
@@ -278,7 +285,7 @@ class ScheduledBillingRunner {
 				(int) $enrollment->id,
 				$enrollment->studentId,
 				$enrollment->instructorId,
-				$offering->price * $count,
+				$offering->price,
 				$offering->currency,
 				$offering->etransferEmail,
 				$monthStart,
@@ -64,14 +64,20 @@ class ShortcodeRegistrar {
 			'nonce'       => wp_create_nonce( 'wp_rest' ),
 			'stripeKey'   => $settings->publishableKey(),
 			'startOfWeek' => Val::int( get_option( 'start_of_week', 1 ) ),
+			// The studio HST rate, so a price quoted to a student on the way in
+			// matches the total they are actually billed.
+			'taxRate'     => $settings->hstRate(),
 		];

 		// Attach the shared config to the payment helper so it is defined before the
 		// booking/group scripts (which depend on it) run.
 		wp_localize_script( 'us-scheduler-payment', 'usScheduler', $data );

-		wp_register_script( 'us-scheduler', USC_PLUGIN_URL . 'assets/js/booking.js', [ 'us-scheduler-payment' ], USC_VERSION, true );
-		wp_register_script( 'us-scheduler-group', USC_PLUGIN_URL . 'assets/js/group-classes.js', [ 'us-scheduler-payment' ], USC_VERSION, true );
+		// Price formatting and the pay agreement, shared by booking and enrolment.
+		wp_register_script( 'us-scheduler-pricing', USC_PLUGIN_URL . 'assets/js/pricing.js', [ 'us-scheduler-payment' ], USC_VERSION, true );
+
+		wp_register_script( 'us-scheduler', USC_PLUGIN_URL . 'assets/js/booking.js', [ 'us-scheduler-pricing' ], USC_VERSION, true );
+		wp_register_script( 'us-scheduler-group', USC_PLUGIN_URL . 'assets/js/group-classes.js', [ 'us-scheduler-pricing' ], USC_VERSION, true );

 		// Progressive enhancement for the two-step registration form (no dependencies).
 		wp_register_script( 'us-scheduler-register', USC_PLUGIN_URL . 'assets/js/register.js', [], USC_VERSION, true );
@@ -187,7 +187,12 @@ class ScheduledBillingRunnerTest extends TestCase
        $this->runner->run();
    }

-    public function testGroupMonthlyBillsMonthTotal(): void
+    /**
+     * A monthly group class is priced per month, not per session: the same fee
+     * is charged whether the class meets four times in the month or once. This
+     * is what the class card quotes and what the student agrees to pay.
+     */
+    public function testGroupMonthlyBillsTheMonthlyFeeOnceHoweverManySessions(): void
    {
        $this->now('2026-07-15 09:00:00');
        $enrollment = new Enrollment(offeringId: 9, studentId: 5, instructorId: 3, id: 44);
@@ -197,10 +202,32 @@ class ScheduledBillingRunnerTest extends TestCase

        $this->payments->shouldReceive('scheduledPaymentExists')->with(Payment::REG_ENROLLMENT, 44, '2026-07')->andReturn(false);

-        // One payment: 4 sessions x 20, due on the 1st.
+        // One payment of the monthly fee — not 4 x 20 — due on the 1st.
        $this->payments->shouldReceive('createForRegistration')
            ->once()
-            ->with(Payment::REG_ENROLLMENT, 44, 5, 3, 80.0, 'CAD', null, '2026-07-01', '2026-07')
+            ->with(Payment::REG_ENROLLMENT, 44, 5, 3, 20.0, 'CAD', null, '2026-07-01', '2026-07')
+            ->andReturn($this->pending(800, '2026-07-01'));
+
+        $this->runner->run();
+    }
+
+    /**
+     * The per-month fee does not shrink for a short month either — a month with
+     * a single session is billed the same as a month with four.
+     */
+    public function testGroupMonthlyBillsTheSameFeeForAMonthWithOneSession(): void
+    {
+        $this->now('2026-07-15 09:00:00');
+        $enrollment = new Enrollment(offeringId: 9, studentId: 5, instructorId: 3, id: 44);
+        $this->enrollments->shouldReceive('findActiveByBillingModes')->andReturn([ $enrollment ]);
+        // A single July session.
+        $this->offerings->shouldReceive('findById')->with(9)->andReturn($this->groupOffering(Offering::BILLING_MONTHLY, '2026-07-07', '2026-07-07'));
+
+        $this->payments->shouldReceive('scheduledPaymentExists')->with(Payment::REG_ENROLLMENT, 44, '2026-07')->andReturn(false);
+
+        $this->payments->shouldReceive('createForRegistration')
+            ->once()
+            ->with(Payment::REG_ENROLLMENT, 44, 5, 3, 20.0, 'CAD', null, '2026-07-01', '2026-07')
            ->andReturn($this->pending(800, '2026-07-01'));

        $this->runner->run();
@@ -23,6 +23,9 @@ class ShortcodeRegistrarTest extends TestCase
    /** @var array<string, callable> */
    private array $shortcodes = [];

+    /** @var array<string, mixed> */
+    private array $localized = [];
+
    protected function setUp(): void
    {
        parent::setUp();
@@ -84,6 +87,69 @@ class ShortcodeRegistrarTest extends TestCase
        self::assertSame('group', $this->shortcodes['us_group_classes'](''));
    }

+    /**
+     * The booking and group-class scripts both read prices through the shared
+     * pricing helper, so it must be registered ahead of them (and behind the
+     * payment helper, which carries the localized config it reads).
+     */
+    public function testPricingHelperIsRegisteredAheadOfTheBookingAndGroupScripts(): void
+    {
+        $scripts = $this->captureEnqueuedAssets();
+
+        self::assertSame(['us-scheduler-payment'], $scripts['us-scheduler-pricing']);
+        self::assertSame(['us-scheduler-pricing'], $scripts['us-scheduler']);
+        self::assertSame(['us-scheduler-pricing'], $scripts['us-scheduler-group']);
+    }
+
+    /**
+     * The studio HST rate reaches the front end so a price quoted on a booking
+     * form matches the total the student is actually billed.
+     */
+    public function testStudioTaxRateIsLocalizedToTheFrontEnd(): void
+    {
+        $this->captureEnqueuedAssets();
+
+        self::assertSame(13.0, $this->localized['taxRate']);
+    }
+
+    /**
+     * @return array<string, array<int, string>> Registered script handle => dependencies.
+     */
+    private function captureEnqueuedAssets(): array
+    {
+        $scripts   = [];
+        $localized = &$this->localized;
+
+        Functions\when('wp_register_style')->justReturn(true);
+        Functions\when('rest_url')->justReturn('https://example.test/wp-json/us-scheduler/v1/');
+        Functions\when('wp_create_nonce')->justReturn('nonce');
+        Functions\when('get_option')->alias(
+            static fn (string $name, mixed $default = false): mixed => match ($name) {
+                'us_hst_rate' => '13',
+                'start_of_week' => 1,
+                default => $default,
+            }
+        );
+        Functions\when('wp_register_script')->alias(
+            static function (string $handle, string $src, array $deps = []) use (&$scripts): bool {
+                $scripts[$handle] = $deps;
+
+                return true;
+            }
+        );
+        Functions\when('wp_localize_script')->alias(
+            static function (string $handle, string $object, array $data) use (&$localized): bool {
+                $localized = $data;
+
+                return true;
+            }
+        );
+
+        $this->registrar->enqueueAssets();
+
+        return $scripts;
+    }
+
    public function testShortcodeAttributesArePassedThroughUnchanged(): void
    {
        $this->registrar->register();