Billing & Packages
NIVAA uses a prepaid package model -- parents purchase session bundles, and each approved session deducts from their balance. Coordinator billing and payout UI is currently frozen for the beta period, so the sidebar entry remains visible but disabled and active workspace monetary values are hidden.
Coordinator billing routes remain documented here for system reference, but the current workspace UI intentionally disables /admin/billing and hides live money values until the finance scope is re-opened.
Monthly Billing Run
POST /billing/run-monthly -- triggers invoice and payout generation for a billing period. Creates one invoice per parent and one payout record per tutor for all approved sessions in the period.
The billing run aggregates all Approved sessions within the specified period, calculates totals using the pricing catalog, and generates PDF invoices stored in R2. This runs automatically via Cloudflare Cron Triggers at the start of each month, but coordinators can trigger it manually for corrections.
Month-to-Date Summary
GET /billing/mtd -- returns aggregated billing data for the current month. Includes total sessions, total revenue, and per-tutor/per-parent breakdowns.
Billing Records
GET /billing/records/me -- admin view returns all billing records across all users. Supports filtering by date range, parent, and tutor.
Core Billing Endpoints
| Endpoint | Method | Description |
|---|---|---|
/billing/run-monthly | POST | Run monthly billing -- creates invoices and payouts |
/billing/mtd | GET | Month-to-date aggregated billing summary |
/billing/records/me | GET | All billing records (admin sees all users) |
/payout | GET | List all payout records |
/payout/:id | PATCH | Update payout status (mark as paid, hold, etc.) |
/payout/generate | GET | Generate payout summary for a period |
/admin/package-ledgers | GET | Sessions purchased/redeemed/remaining per customer |
/admin/pricing/catalog | GET | All pricing plans by service line, level, duration |
/admin/matches/:id/incentive | PUT | Set per-match tutor incentive bonus |
Payout Cycles
Payouts are generated alongside invoices during the monthly billing run. Each tutor receives a payout record summarizing their sessions and earnings for the period.
GET /payout-- list all payout records, filterable by status and period.PATCH /payout/:id-- update a payout (mark as paid, add notes, hold for review).GET /payout/generate-- preview payout summary before committing.
Frontend page: /admin/billing/payouts
Package Ledgers
GET /admin/package-ledgers -- shows sessions purchased, redeemed, and remaining for each parent. Use this to identify parents running low on sessions.
Frontend page: /admin/billing/packages
Low Package Alerts
Parents with < 20% sessions remaining in their package are flagged automatically. These alerts appear in the parent alert system and on the coordinator dashboard.
The alert system computes sessions_remaining / sessions_purchased for each active package. When the ratio drops below 0.20, a low-package alert is generated. Coordinators should reach out to the parent to discuss renewal.
Pricing Catalog
GET /admin/pricing/catalog -- returns all pricing plans organized by service line, level, and duration. Each plan includes the per-session rate and package pricing tiers.
Tutor Incentives
Coordinators can set per-match incentive bonuses for tutors to encourage quality and retention.
PUT /admin/matches/:id/incentive -- set or update the bonus amount for a specific tutor-student match.
PDF Generation
Invoices and payout summaries are generated as PDFs using pdf-lib directly inside the Cloudflare Worker. Generated PDFs are stored in the nivaa-pdfs R2 bucket and linked to the corresponding billing record.
Frontend Pages
| Route | Purpose |
|---|---|
/admin/billing/invoices | View and manage parent invoices |
/admin/billing/payouts | View and manage tutor payouts |
/admin/billing/cycles | Billing cycle history and management |
/admin/billing/packages | Package ledgers and session balances |