ProductFees & Finance

Fees & Finance

One-line: Define what a school charges, bill each student, record payments, and hand back a PDF receipt — with parents and students seeing their own dues on mobile.

What it does

Fees & Finance covers the full money-in lifecycle for a school:

  • Fee structures — named bundles of charges (Tuition, Transport, Activity…) for an academic year.
  • Student invoices — per-student fee records generated from a structure, or standalone itemized invoices.
  • Payments — record cash, cheque, DD, or online payments against a student’s dues, with running balances.
  • Receipts — downloadable PDF receipts and invoices generated on the server.

Who uses it

  • Finance / office staff — create structures, generate student fees, and record payments from the admin-web finance pages. All gated under the finance.* permission prefix.
  • Students / parents — a read-only self-view of their own outstanding fees and due dates on the mobile app. They hold no finance.* permission; their dues are surfaced self-scoped through the student dashboard.

Key concepts

  • Fee component — one named charge with an amount and frequency (monthly, quarterly, annual, one-time), e.g. “Tuition Fee — 5000/quarter”.
  • Fee structure — a set of components for an academic year (e.g. “Annual Fees 2024-25”).
  • Class assignment — links a structure to specific classes or a whole grade, so it applies to the right students.
  • Student invoice / student fee — the per-student record generated from a structure, with one line item per component and a paid / partial / unpaid / overdue status.
  • Payment — a single transaction against a student fee or invoice; updates the paid amount and balance.
  • PDF receipt — a branded receipt/invoice rendered server-side via WeasyPrint (school logo, student details, line items, status).
  • Payment idempotency key — a per-attempt UUID a client sends so a retried request never charges twice.

How it works

1. Define fee components        (name, amount, frequency, due date)
2. Group them into a structure  (per academic year)
3. Assign the structure         (to classes or a grade)
4. Generate student fees        (one record + line items per student)
5. Record payments              (validated against remaining balance)
6. Issue receipts               (PDF download / print)

Alongside structure-driven billing, staff can also create standalone itemized invoices for a single student (auto-numbered, e.g. INV-2025-001) and email reminders to parents.

Students see their own fees through a self-scoped view that supports server-side pagination plus a summary aggregate (total outstanding, paid, overdue count) computed over all matching rows — not just the visible page — so totals stay correct as they page.

Rules & edge cases

  • Plan gating — the whole module is gated by the fees_management plan feature key. Schools without it get no fees module.
  • Tenant scoping — every structure, invoice, payment, and receipt is scoped to the tenant; one school can never see another’s financial data. Branch-restricted sub-admins only touch fees of students in their own units.
  • Payment idempotency — clients send a fresh idempotency_key (UUID) per payment attempt; a repeat with the same key returns the original payment instead of double-charging.
  • Money is stored as DECIMAL, never float — avoids rounding drift in balances and totals.
  • Server-side pagination on the student-fees list is opt-in (page / page_size, max 100); without it the full set returns unchanged for back-compat.
  • Online fee collection is planned, not built. The payment schema is gateway-ready (a payment_method of online and reference fields exist), but there is no live payment-gateway / Razorpay flow yet — online payments today are recorded manually by staff, not collected in-app.

Where it lives

  • Backend: server/modules/finance/ (fee structures, student fees, payments; /api/finance) and server/modules/fees/ (invoices, receipts; /api/fees)
  • Admin-web: finance pages — summary dashboard, fee structures, invoices, payments
  • Plan feature key: fees_management

Related

AcademicsTimetable & Schedule