Billing & Packages
NIVAA uses a prepaid session package model. Parents purchase packages of sessions upfront, and each approved session is deducted from their balance. Billing and payout frontend surfaces are currently frozen for the beta period, so active workspace routes show disabled billing nav items and unavailable placeholders instead of live money values.
Billing and payout UI is intentionally disabled in the parent, tutor, and coordinator workspaces during the current beta phase. The underlying worker endpoints still exist, but the active product surface does not expose live monetary values.
Session Packages
Parents buy packages containing a fixed number of sessions. Each package tracks:
| Field | Description |
|---|---|
total_sessions | Number of sessions included in the package |
used_sessions | Number of sessions consumed (Approved status) |
remaining | Computed: total_sessions - used_sessions |
price_per_session | Cost per session (may vary by package size) |
status | Active | Exhausted | Expired |
Low Package Alerts
When a parent's remaining sessions fall below 20% of their total package, the system generates a low-package alert. This alert appears in the parent dashboard, the coordinator alerts view, and the Telegram bot (/lowpackages).
Billing Cycles
Monthly billing cycles are triggered manually by coordinators via POST /billing/run-monthly. When a cycle is run:
- 1 Session aggregation: All
Approvedsessions in the billing period are counted per tutor. - 2 Invoice generation: Invoices are created for each parent with outstanding charges (PDF generated via pdf-lib).
- 3 Payout calculation: Tutor payouts are computed based on their rate and the number of approved sessions.
- 4 Cycle close: The billing cycle is marked as closed, locking the numbers.
Invoices
Invoices are generated as PDFs within the Worker using pdf-lib and stored in R2. Each invoice includes:
- Parent and child details
- Session list with dates, times, and tutors
- Package usage (sessions used / total)
- Total amount and any applied discounts
- Payment status
Tutor Payouts
Tutors can check their current month's billing summary via the web dashboard or Telegram (/mypay). Payout details include:
| Field | Description |
|---|---|
| Sessions completed | Count of Approved sessions in the billing period |
| Rate per session | Agreed rate for this tutor |
| Add-on sessions | Extra sessions logged with billed_as_addon=1 |
| Gross amount | Total before any deductions |
| Payout status | Pending | Processed | Paid |
Admin Billing Views
Coordinators access billing through sub-routes under /admin/billing/:
| Route | Purpose |
|---|---|
/admin/billing/invoices | All generated invoices with search, filter by status |
/admin/billing/payouts | Tutor payout records, mark as paid |
/admin/billing/cycles | Monthly billing cycle management, open/close cycles |
/admin/billing/packages | All session packages, usage tracking, create new packages |