docs(wiki): subscription recurring billing + party ledger — design only
Subscription page: the one-window model can't express prepaid/postpaid, calendar or anniversary anchoring, grace or an expiry notice; and renewal is OFF-BOOK today (a PUT that appends no payment — the same hole closed for the first sale on 2026-06-20). Designed: plan billing rule, per-day pricing so both anchors share one formula, open- ended agreement, subscription_periods where each period is a ledger charge and a renewal = paying the next period, one subscriptionAccess() gate function, expiry notice derived not stored. New decision page party-ledger: a counterparty sub-ledger for who-owes-whom across modules — parties + signed charge / settlement / write_off events, balance derived never stored, aging + statements + CSV; lands postpaid subscriptions, hotel guest-nights, fleet washes on account, supplier/utility bills. Sub-ledger only: no bookkeeping, a statement is not a fiscal invoice, parties per appliance. validation-sponsorship's sponsor table marked superseded; open-questions #17; index. Claude-Session: https://claude.ai/code/session_01FWncR69HgGPuei1dLrW3cU
This commit is contained in:
@@ -2,7 +2,7 @@
|
||||
type: entity
|
||||
tags: [parking, domain, business, subscriptions, identity, pricing]
|
||||
sources: []
|
||||
updated: 2026-06-20
|
||||
updated: 2026-09-08
|
||||
aliases: [subscription-plan]
|
||||
status: open
|
||||
---
|
||||
@@ -90,6 +90,15 @@ subscription row, one window. The amount the operator should collect is **N × t
|
||||
`now` ∈ [validFrom, validTo]** — so a 3-month window simply stays valid for three months.
|
||||
- An explicit **`validTo` override** is still accepted (manual end date) when `months` isn't used.
|
||||
|
||||
> ⚠ **Renewal is OFF-BOOK (found 2026-09-08).** "Renewing is just editing the window" means a
|
||||
> renewal goes through `PUT /api/subscriptions/:id`, which by design **never re-sells and appends
|
||||
> nothing to the ledger**. The first sale was put on the chain on 2026-06-20 precisely because
|
||||
> 27,000 ALL had gone off-book; **every renewal since takes the same off-book path** — the
|
||||
> operator collects the next month's fee and moves `validTo`, with no `payment` event. The
|
||||
> recurring-billing design below closes this: a renewal becomes *paying the next billing period*,
|
||||
> a signed `payment`. Until then, a renewal should be taken as a **new sale** (new subscription
|
||||
> row), not an edit.
|
||||
|
||||
### v2 — quantity, plan timeframes (tariff bridge), reserved spots (built 2026-06-20)
|
||||
|
||||
Three enhancements driven by real scenarios (migration `0011`):
|
||||
@@ -356,6 +365,106 @@ Intended behaviour (to design + build later):
|
||||
> **Explicitly postponed.** For now this is documentation only — no schema, no enforcement. A
|
||||
> subscription is valid whenever it is active and within `validFrom`/`validTo`, all day.
|
||||
|
||||
## Recurring billing — prepaid / postpaid, calendar or anniversary — DESIGN 2026-09-08
|
||||
|
||||
**Design only, nothing built.** Captured from a design conversation with the user (2026-09-08):
|
||||
"a subscriber should prepay or postpay every month, on the 1st or on the day the subscription
|
||||
began; a subscription fixed by a daily tariff, e.g. 300 ALL/day; for prepaid, a notice that a
|
||||
subscription is about to expire so the owner/operator warns the subscriber to pay or lose access."
|
||||
The financial side of this grew into its own page — the [[party-ledger]] — because a postpaid
|
||||
subscriber is a *debtor*, and the site has other debtors (hotels, fleets) and creditors
|
||||
(suppliers). This section is the subscription-shaped part.
|
||||
|
||||
### What is wrong with the one-window model
|
||||
|
||||
A subscription today is **one coverage window** (`validFrom`/`validTo`) sold once: a hotel model.
|
||||
There is no recurring agreement, no due date, no grace, no unpaid balance; prepaid vs postpaid is
|
||||
not expressible, and calendar-anchored billing can only be faked with hand-picked dates. And
|
||||
renewal is off-book (callout above).
|
||||
|
||||
### Split the one row into three concepts
|
||||
|
||||
**1. Plan** — the catalog and versioning stay; a plan version gains a **billing rule**:
|
||||
|
||||
```
|
||||
billing: {
|
||||
mode: "prepaid" | "postpaid",
|
||||
cycle: "day" | "week" | "month", // how often a period is billed
|
||||
anchor: "calendar" | "start", // the 1st of the month, or the sale's anniversary
|
||||
graceDays: number, // access continues this long past due
|
||||
noticeDays: number // "about to expire" window
|
||||
}
|
||||
```
|
||||
|
||||
Recurring plans are **priced per day** (`period: "day"`): a calendar month costs
|
||||
`daysInMonth × 300 ALL`, a partial first month is simply the days left, and **calendar and
|
||||
anniversary anchoring share one formula** (proration falls out for free). Fixed-price monthly
|
||||
plans (`period: "month"`) stay for sites that want a flat number. The hotel "N nights" sale is
|
||||
unchanged (a `"day"` plan over a span, no billing rule).
|
||||
|
||||
**2. Agreement** — the `subscriptions` row: holder, credentials, cars, `validFrom`; for a
|
||||
recurring plan **no `validTo`** (open-ended, ends by revoke/suspend). Fixed spans keep `validTo`.
|
||||
The holder is (or is linked to) a **party** ([[party-ledger]]) — the payer, which for a hotel is
|
||||
the hotel, not the guest.
|
||||
|
||||
**3. Billing periods** — one row per cycle, and each is a **`charge`** on the party ledger:
|
||||
|
||||
```
|
||||
subscription_periods id, subscriptionId, periodFrom, periodTo,
|
||||
amountMinor (from the plan version), currency, dueAt,
|
||||
status {due|paid|overdue|waived}, chargeEventId, paymentEventId?
|
||||
```
|
||||
|
||||
- **Paying a period** = the existing signed **`payment`** with `subscriptionSale: true` plus the
|
||||
period/charge reference — drawer and Z-report keep working with no new summing
|
||||
(§Collecting the fee). **Renewal is just paying the next period.** This closes the off-book hole.
|
||||
- **Waiving** a period is a signed **$0 payment with a reason** — the same rule the Car Wash uses
|
||||
for a comp ([[venue-modules]]: a comp never opens the barrier, sign the $0 payment) — or a
|
||||
`write_off` on the party ledger; admin-gated either way.
|
||||
- The next period is **generated ahead** (prepaid: before the current one ends, so it can be paid
|
||||
early; postpaid: at period end, due `dueAt`), by a daily tick or lazily on read.
|
||||
|
||||
### The gate asks one function
|
||||
|
||||
The entry flow stops reading `validTo` for recurring plans and asks
|
||||
`subscriptionAccess(sub, periods, now) → { ok, reason, accessUntil, daysLeft }`:
|
||||
|
||||
- **prepaid** — allowed while `now ≤ paidThrough + graceDays` (the next period must be paid
|
||||
before it starts, plus grace);
|
||||
- **postpaid** — allowed while no period is unpaid past `dueAt + graceDays`;
|
||||
- both collapse to one derived **`accessUntil`** and **`daysLeft`** per subscriber (never stored).
|
||||
|
||||
This also answers the long-open **lapsed-mid-stay** question for recurring subs: a period ending
|
||||
while a car is parked falls into **grace**, so nobody is trapped; only a subscriber still parked
|
||||
past grace becomes a transient at exit (the tariff-bridge machinery above already prices that).
|
||||
Revoked/suspended behaviour is unchanged.
|
||||
|
||||
### "About to expire" — derived, not stored
|
||||
|
||||
One endpoint (e.g. `GET /api/subscriptions/attention`) lists subscribers whose `accessUntil` falls
|
||||
within the plan's `noticeDays`, those in grace, and those overdue. Surfaced in three places:
|
||||
|
||||
1. a **counter on the booth console** ([[booth-console]]);
|
||||
2. a **badge in the subscriber list**;
|
||||
3. a **line in the live feed when such a subscriber scans in** — "expires in 3 days" at the moment
|
||||
the person is at the gate (a slip can print, best-effort like the window-charge notice).
|
||||
|
||||
Contacting the subscriber stays with the operator/owner by phone (`contact` field). SMS/email
|
||||
is off-appliance ([[cloud-service-saas]]) — a separate decision.
|
||||
|
||||
### Not built, deliberately
|
||||
|
||||
Automatic card charging, invoices, dunning, auto-suspension without grace. **The operator still
|
||||
never types a price.**
|
||||
|
||||
### Build order (after [[party-ledger]] step 1)
|
||||
|
||||
1. Billing rule on the plan version + `subscription_periods` (migration); period generation.
|
||||
2. Pay-period route (signed `payment` + charge reference) and the `subscriptionAccess` gate
|
||||
function in `subscription-flow.ts`; `PUT` stops moving `validTo` on recurring subs.
|
||||
3. Attention endpoint + the three UI surfaces.
|
||||
4. Wiki + [[booth-console]] docs.
|
||||
|
||||
## Data model (as-built 2026-06-18)
|
||||
|
||||
Tables (mutable master data; every *use* still produces a signed `vehicle_entry`/`vehicle_exit`):
|
||||
@@ -420,10 +529,15 @@ subscription** (card/QR credential, or a bound plate) — otherwise to the trans
|
||||
1. **Reader hardware** — confirm the RF reader and QR/optical reader models (procurement; [[bom]],
|
||||
[[open-questions]]).
|
||||
2. **Lapsed-mid-stay & revoked** policy (fall back to transient [[tariff]] vs. refuse) — confirm.
|
||||
3. ~~**Subscription-fee collection**~~ — **RESOLVED + BUILT 2026-06-20.** Selling a priced
|
||||
subscription appends a signed `payment` (`subscriptionSale` flag, `priceMinor × months`,
|
||||
operator-chosen tender) that folds into the drawer/Z-report. Remaining sub-question: should a sale
|
||||
be **hard-blocked without an open shift** (it isn't today — it warns instead)? See "Collecting the
|
||||
fee".
|
||||
3. ~~**Subscription-fee collection**~~ — **RESOLVED + BUILT 2026-06-20** for the *first* sale
|
||||
(signed `payment`, `subscriptionSale` flag, operator-chosen tender, folds into the
|
||||
drawer/Z-report). **REOPENED 2026-09-08 for RENEWALS**: a renewal is a `PUT` that appends
|
||||
nothing (see the callout under "Multi-month"). Closed by the recurring-billing design (a renewal
|
||||
= paying the next period). Remaining sub-question: should a sale be **hard-blocked without an
|
||||
open shift** (it isn't today — it warns instead)?
|
||||
4. **Time-of-day access windows** (overnight subscribers) — design + build; boundary-case policy
|
||||
above (see the design note).
|
||||
5. **Recurring billing** (prepaid/postpaid, calendar/anniversary anchor, grace, expiry notice) —
|
||||
**designed 2026-09-08, not built**; see §Recurring billing and [[party-ledger]]. To refine: is
|
||||
the next period generated by a daily tick or lazily; does a waived period sign a $0 `payment` or
|
||||
a `write_off` (pick one); whether `noticeDays` is per plan or per site.
|
||||
|
||||
Reference in New Issue
Block a user