Grade Student Fees

The Student Fees module serves as the primary interface for managing individual student financials, payments, and invoices. It centralizes all fee-related activities, ensuring that educational institutions can securely track, allocate, and manage student fee structures on a per-student or per-parent basis.

Handling student fees manually creates administrative bottlenecks and risks of financial discrepancies. This module automates the billing process and provides a consolidated dashboard for authorized staff to quickly review a student's standing. As part of the Student Affairs suite, the data manages payment statuses, invoice generation, and custom fee allocation.

Follow these steps to reach the Student Fees module from anywhere in the system: ---

Manage Student Fees Form

When creating or managing a student's fees, the interface provides a comprehensive control panel:

[!IMPORTANT] Note on Evaluation Periods The financial data, fee allocations, and attendance records displayed in this module are heavily dependent on the selected Evaluation Period. Ensure that the correct evaluation period is chosen from the filter, as all student fee invoices, reports, and attendance summaries dynamically adjust to reflect only the data relevant to that specific timeframe.

Management Tabs

The module is divided into four main tabs for comprehensive management:

1. Student Fees: Displays and manages the allocated fee components and installments.
2. Payment & Invoices: Handles the generation of invoices and tracking of payments (Paid, Unpaid, Partial).
3. Reports: Provides financial summaries and collection reports for the selected student.
4. Attendance: A quick view of the student's attendance records, which can sometimes impact certain fee structures or billing.

The main list page (powered by a server-side DataTable) shows every student together with their fee position for the current academic year.

Columns

Available Filters

Grade-Aware Evaluation Period Selector

The Grade and Evaluation Period filters are linked:

• Selecting a Grade dynamically reloads the list of Evaluation Periods that belong to it.
• On page load, the system automatically pre-selects the period marked as "today's period," or falls back to any previously selected period, or the first available period.
• Changing either filter automatically re-triggers the DataTable and totals refresh (filter:changed event).

Totals Footer

Below the grid, the system calculates and displays live aggregate totals across all matching students (not just the current page):

• Total Amount — sum of fees + approved discounts (i.e., pre-discount value).
• Total Discount — sum of all approved discounts.
• Total After Discount — fees due after discount is applied.
• Paid Amount — total collected.
• Remaining Amount — max(0, Total After Discount − Paid Amount).

[!NOTE] Two Calculation Paths If a student already has installments generated, totals are computed from the installment records directly. If a student has no installments yet, the system falls back to the grade's default fee for the primary fee category (the category flagged is_primary, or one titled "Primary," or simply the first category for the academic year).

The module offers several PDF outputs, all rendered via mPDF:

Additional report filters available on printReport only:

• Fee Category
• Payment Status: paid (fully paid, no unpaid installments), unpaid (nothing paid yet), partial (some paid, some still outstanding)
• Discount Status: recalculated here using a raw SQL comparison between installment totals and grade_fees (amount minus discount), rather than the discount_histories table used on the main listing

Discounts are tracked in a separate discount_histories table and go through a status lifecycle:

1. Save Discount (saveDiscount) — records a discount (before/after amount, reason) tied to a student and fee category, typically starting in a pending state.
2. Update Status (updateDiscountStatus) — moves a discount between pending, approved, or declined.
3. Update Approval (updateDiscountApproval) — a dedicated endpoint for approvers to formally approve/reject a discount request.
4. Get Discount History (getDiscountHistory) — retrieves a student's discount records, optionally scoped by fee category and evaluation period.

[!IMPORTANT] Only discounts with a status of approved are ever counted toward the "Discount," "After Discount," or "Remaining Amount" figures shown on the listing, reports, and invoices. Pending or declined discounts have no financial effect.

• Auto-Generation (generateInstallments): Splits a total fee amount evenly across a configurable number of months (default 3), starting from a given date, producing one installment per month.
• Manual Entry: Existing installments can also be edited directly (due date, amount, paid status) via the form's installments / existing_installments arrays.
• Persistence (saveInstallments): Installments are upserted per student, academic year, evaluation period, installment number, and fee category — so re-saving the form updates existing rows instead of duplicating them. Marking an installment as paid automatically assigns it a receipt/invoice number.
• Student-Level Metadata: Saving fees also updates the student's fee_category (cash vs. installment), number of months, and start date.

• Voucher Creation: Every successful payment (cash invoice, installment payment, or API-driven payment) creates a corresponding Receipt voucher in the finance module via FinService::createVoucher, linked to the student as the ledger entity.
• VAT Calculation: Standard invoices apply a VAT percentage (system default 14% if not otherwise configured) on top of the subtotal to compute the net total.
• External Reconciliation API (finInstallmentsApi): A dedicated endpoint that lets external finance/POS systems mark an installment as paid by matching ledger_id, amount, and an unpaid/unassigned installment, then creates the corresponding voucher. If voucher creation fails, the installment's paid status is automatically rolled back to prevent inconsistent records.

• Restricted Access: Parents can only view or act on their own linked children — every parent-facing endpoint (create, installments, paymentHistory, printGroupByDate, printInstallmentPdf, printFullPaymentHistory, parentFees) verifies the requested student ID belongs to the authenticated parent (auth('parent_web')) before returning any data, otherwise aborting with a 403.
• Selected Child Filter: When a parent has multiple children, the listing can be scoped to a single selected child via a session-based "selected student" preference.
• Parent Fee View (parentFees): A simplified, read-only summary page for parents showing total fees, total paid, and remaining balance for one child.

Only administrators holding the core system admin role or having specific permissions can manage this module: > [!TIP] > Discount approvals are typically restricted to finance leads or administrators in practice — confirm with your permissions matrix which role is mapped to the approval endpoints if you need to lock this down further.