Fee setup and invoicing

This guide covers the complete fee management workflow—from defining fee structures to generating invoices through billing runs. The finance module supports multiple fee types, flexible scoping, late fees, discounts, and integration with payment tracking.

What this guide covers

• Fee structure planning and configuration
• Creating and managing school fees
• Billing run execution and scope targeting
• Invoice generation and management
• Fee assignment strategies (grade, class, individual)
• Late fees, discounts, and scholarship eligibility

---

Before you start

Required setup

Requirement	Location	Purpose
Academic year	Foundation → Academic Years	Fee period context
Terms	Foundation → Terms	Term-based billing
Grade levels	Foundation → Grade Levels	Grade-specific fees
Class divisions	Foundation → Class Divisions	Class-specific fees
Students	People → Students	Invoice recipients

Required permissions

Permission	Description
finance.fees.create	Create fee definitions
finance.fees.edit	Modify fee configurations
finance.billing_runs.create	Execute billing runs
finance.invoices.view	View generated invoices

---

Fee lifecycle overview

┌────────────────┐    ┌─────────────────┐    ┌────────────────┐    ┌────────────────┐
│  Create fee    │ → │  Run billing    │ → │   Generate     │ → │   Collect      │
│  definitions   │    │  batch          │    │   invoices     │    │   payments     │
└────────────────┘    └─────────────────┘    └────────────────┘    └────────────────┘

---

Navigation paths

Function	Path
Fees	Finance → Fees
Billing runs	Finance → Billing Runs
Invoices	Finance → Invoices
Payments	Finance → Payments
Receipts	Finance → Receipts

---

Part 1: Fee configuration

Fee types

Configure different fee categories:

Fee type	Description	Examples
Tuition	Core academic instruction	Term tuition, annual fees
Registration	Enrollment processing	New student registration, re-enrollment
Boarding	Residential accommodation	Boarding fees, hostel charges
Transport	School transportation	Bus fees, route charges
Examination	Assessment fees	ZIMSEC levies, mock exam fees
Activity	Extracurricular programs	Sports, clubs, trips
Material	Learning materials	Textbooks, stationery, uniforms
Development	Infrastructure contributions	Building fund, IT levy

Fee categories

Category	Description
Mandatory	Required for all applicable students
Optional	Opt-in fees for specific services
Once-off	Single payment (e.g., registration)
Recurring	Repeated each term/year

Creating a fee

Navigate to Finance → Fees → Create Fee

Basic information

Field	Required	Description
Fee name	Yes	Descriptive name (e.g., "Term 1 Tuition 2024")
Fee code	No	Short code for reference
Fee type	Yes	Tuition, Registration, Boarding, etc.
Fee category	Yes	Mandatory, Optional, etc.
Academic year	Yes	Year the fee applies to
Term	No	Specific term (leave blank for annual)

Amounts & currency

Field	Description
Amount	Fee value
Currency	Currency code (default: school currency)
Payment frequency	Termly, Monthly, Annual, Once-off
Billing cycle	When invoices are generated

Due dates

Field	Description
Due date	Default payment deadline
Payment deadline	Final cutoff date
Grace period days	Days after due date before late fees

Applicability

Field	Description
Applies to	All students, Specific grades, Specific classes
Grade levels	Select applicable grades
Classes	Select applicable class divisions
Student type	Regular, Boarding, Day, etc.

Late fee configuration

Enable late fees for overdue payments:

Field	Description
Has late fee	Toggle to enable
Late fee type	Fixed amount or Percentage
Late fee amount	Fixed value if type is Fixed
Late fee percentage	Percentage if type is Percentage
Late fee starts after days	Days after due date
Maximum late fee	Cap on late fee accumulation

Discount configuration

Configure early payment and sibling discounts:

Field	Description
Has discount	Toggle to enable
Early payment discount %	Percentage for early payment
Early payment deadline	Cutoff for early payment discount
Sibling discount %	Discount for multiple siblings

Scholarship and subsidy

Field	Description
Scholarship eligible	Can be covered by scholarships
Subsidy applicable	Can receive government subsidy
Subsidy description	Details of subsidy program

---

Part 2: Billing runs

Billing runs generate invoices for groups of students based on fee definitions and scope targeting.

Billing run scope types

Scope type	Description	Use case
School	All students in school	School-wide fees (registration, development)
Grade level	Students in specific grades	Grade-specific tuition
Class division	Students in specific classes	Class-specific fees
Subject class	Students in subject groups	Subject-specific fees
Student list	Explicitly listed students	Individual or special billing

Creating a billing run

Navigate to Finance → Billing Runs → Create Billing Run

Scope selection

Field	Required	Description
Scope type	Yes	School, Grade level, Class, Student list
Grade level	If scope is grade	Target grade level
Class division	If scope is class	Target class
Student IDs	If scope is list	Specific students

Fee selection

Field	Required	Description
School fee	Yes	Fee definition to invoice
Academic year	Recommended	Context for billing
Term	Recommended	Term context

Billing dates

Field	Description
Billing period start	Start of billing period
Billing period end	End of billing period
Invoice date	Date on invoices
Due date	Payment due date

Options

Field	Description
Dry run	Preview without creating invoices
Force regenerate	Regenerate existing invoices
Idempotency key	Prevent duplicate runs

Billing run statuses

Status	Description
pending	Run created, not yet started
queued	Waiting to be processed
processing	Currently generating invoices
completed	Successfully completed
failed	Encountered errors
cancelled	Manually cancelled

Billing run results

After execution, the run shows:

Metric	Description
Total students	Students in scope
Processed students	Students processed
Successful invoices	Invoices created
Failed students	Students that couldn't be billed
Failure summary	Breakdown of failure reasons

Failure codes

Code	Description	Resolution
duplicate_invoice	Invoice already exists	Use force regenerate or skip
invoice_creation_failed	System error creating invoice	Check logs, retry
validation_failed	Data validation error	Fix student data
no_student_matches	No students in scope	Verify scope settings

---

Part 3: Invoice management

Invoice structure

Each invoice contains:

Component	Description
Invoice number	Unique reference
Student	Billed student
Guardian	Bill-to contact
Line items	Fee breakdowns
Subtotal	Sum before adjustments
Tax amount	If applicable
Discount amount	Any discounts applied
Total amount	Final amount due
Due date	Payment deadline
Status	Current invoice state

Invoice statuses

Status	Description
draft	Being prepared
pending	Awaiting payment
partially_paid	Partial payment received
paid	Fully paid
overdue	Past due date
cancelled	Cancelled/voided
refunded	Payment refunded

Invoice line items

Each line item includes:

Field	Description
Description	Fee description
Quantity	Usually 1
Unit amount	Per-unit price
Total amount	Line total
Tax rate	If applicable
Discount	Line-level discount
GL account	Accounting code
Cost center	Cost center code

Viewing invoices

Navigate to Finance → Invoices

Filter by:

• Student name or number
• Invoice status
• Date range
• Academic year/term
• Grade level
• Amount range

Invoice details

Opening an invoice shows:

1. Header — Invoice number, dates, student info
2. Bill-to — Guardian/payer details
3. Line items — Fee breakdown
4. Totals — Subtotal, tax, discount, total
5. Payment history — Associated payments
6. Status timeline — Status changes

---

Part 4: Fee assignment strategies

Strategy 1: School-wide fees

For fees that apply to all students:

1. Create fee with Applies to: All students
2. Create billing run with Scope: School
3. Execute billing run

Strategy 2: Grade-specific fees

For grade-based tuition differentiation:

1. Create separate fee for each grade level
2. Set Applies to: Specific grades
3. Select applicable grade levels
4. Create billing run with Scope: Grade level

Strategy 3: Class-specific fees

For class-based fees:

1. Create fee with Applies to: Specific classes
2. Select applicable class divisions
3. Create billing run with Scope: Class division

Strategy 4: Individual billing

For special cases:

1. Create fee definition
2. Create billing run with Scope: Student list
3. Enter specific student IDs
4. Execute billing run

---

Part 5: Workflow examples

Example: Term tuition billing

1. Create fee

   • Name: "Term 1 Tuition 2024"
   • Type: Tuition
   • Category: Mandatory
   • Amount: $500
   • Academic year: 2024
   • Term: Term 1
   • Applies to: All students

2. Create billing run

   • Scope: School
   • Fee: Term 1 Tuition 2024
   • Invoice date: January 5, 2024
   • Due date: January 20, 2024

3. Review and execute

   • Use dry run first to preview
   • Execute to generate invoices
   • Verify in Invoices list

Example: Grade-specific boarding fees

1. Create fees per grade

   • "Form 1 Boarding - Term 1" — $300
   • "Form 2 Boarding - Term 1" — $320
   • "Form 3 Boarding - Term 1" — $340

2. Set applicability

   • Each fee: Specific grade level
   • Student type: Boarding

3. Create billing runs per grade

   • One run per fee/grade combination

Example: Late registration fee

1. Create once-off fee

   • Name: "Late Registration Fee"
   • Type: Registration
   • Category: Once-off
   • Amount: $50

2. Identify late registrants

   • Filter students by enrollment date

3. Billing run with student list

   • Scope: Student list
   • Enter late registrant IDs

---

Fee reconciliation

Balance verification

For each student, verify:

Check	Location
Total invoiced	Student profile → Finance tab
Total paid	Payment history
Current balance	Outstanding amount

Batch verification

After billing runs:

1. Navigate to Finance → Invoices
2. Filter by billing run date
3. Verify invoice count matches expected
4. Spot-check amounts
5. Review any failed students

---

Common issues

Billing run shows no students

Problem: Billing run completes with 0 students

Causes:

• Fee applicability doesn't match scope
• No students in selected grade/class
• Students already have invoices (without force regenerate)

Solution: Verify fee applicability matches billing scope

Duplicate invoice error

Problem: Billing run fails with duplicate invoice errors

Solution:

• Enable Force regenerate to recreate invoices
• Or skip students with existing invoices

Wrong amount on invoice

Problem: Invoice amount doesn't match fee definition

Causes:

• Fee amount changed after invoice creation
• Discount or scholarship applied
• Line item modifications

Solution: Review invoice line items and adjustments

Student missing from billing run

Problem: Student not included in billing run

Causes:

• Student not in specified scope (grade/class)
• Student enrollment status not active
• Fee applicability excludes student type

Solution: Verify student's grade, class, and enrollment status

---

Best practices

Fee setup

• Name fees clearly with year/term
• Use consistent fee codes
• Set appropriate due dates
• Configure late fees to encourage timely payment
• Enable early payment discounts where applicable

Billing runs

• Always use dry run first for new fee types
• Verify scope before executing
• Check failed students after each run
• Document billing run schedule

Ongoing management

• Review overdue invoices weekly
• Reconcile payments regularly
• Archive old academic year invoices
• Audit fee assignments each term

---

Outcome

After completing fee setup and invoicing:

• ✅ Fee structure configured for the school
• ✅ Fees assigned to appropriate student groups
• ✅ Billing runs executed successfully
• ✅ Invoices generated and accessible
• ✅ Students can view and pay invoices
• ✅ Balance tracking enabled

---

Related guides

• Record payment and issue receipt — Processing payments
• Initial setup checklist — Foundation setup
• Create academic year and term — Academic structure
• Record first payment — Quick start for payments