Version: Current

Student billing lifecycle

Student billing converts approved pricing configuration into student-specific obligations. In Makronexus, the lifecycle is not “create a fee and money is owed.” A fee remains reusable configuration until an invoice is created for an eligible student and billing period.

Audience: bursars, credit controllers, accountants, school administrators, implementers, reviewers, and support analysts
Learning time: 35–45 minutes
Product route family: /finance/fees, /finance/billing-runs, /finance/invoices, /finance/student-summaries

Learning outcomes

You will be able to:

explain the boundary between a fee, billing run, invoice, credit note, payment, and student financial summary;
identify the dependencies that must pass before billing;
describe the verified billing-run and invoice states;
separate approval state from payment state;
identify the evidence required after each lifecycle stage;
choose a safe correction path without deleting financial history.

Exact definition and boundaries

A billing lifecycle is the controlled sequence that selects an approved fee, resolves eligible students, creates invoices, obtains required approval, communicates obligations, tracks balances, and applies authorised adjustments.

It is not:

payment collection;
receipt issuance;
bank settlement;
reconciliation;
General Ledger close;
a guarantee that every invoice posts automatically.

Those activities are controlled by P4–P6 and the selected school’s configuration.

Record	Meaning in the billing lifecycle	Not the same as
School fee	reusable price, audience, dates, currency, and policy	student debt
Billing run	asynchronous instruction and telemetry for bulk invoice generation	invoice
Invoice	student-specific obligation for a period	payment request evidence from a provider
Credit note	approved reduction of an invoice obligation	cash refund
Student financial summary	aggregate invoiced, paid, adjusted, refunded, outstanding, and ageing values	original transaction ledger
Payment	incoming funds recorded by Makronexus	invoice approval
Receipt	numbered proof issued for a payment	invoice or bank evidence

Prerequisites

Dependency	Verification
Selected school	school switcher displays the intended school
Academic year and term	active and consistent with the selected fee
Accounting period	open for the intended invoice date
Fee	active, approved, effective, positive amount, correct currency
Fee audience	grade/class/student type/eligibility is reviewable
Students	active and within the requested scope
Posting mappings	billing readiness does not report missing mappings
Roles	maker and reviewer are different people where policy requires
Communication	guardian contact and channel policy are available before send
Access	exact abilities below are present

Roles and exact permissions

Activity	Exact ability
View fee catalogue	`financial_fee:list`
Create fee	`financial_fee:create`
Update fee	`financial_fee:update`
View billing runs	`invoice_billing_run:list`, `invoice_billing_run:read`
Create dry/live run	`invoice_billing_run:create`
Inspect failures	`invoice_billing_run:failures`
Cancel pending/queued run	`invoice_billing_run:cancel`
Resolve supported run exception	`invoice_billing_run:resolve`
List/read invoices	`financial_invoice:list`, `financial_invoice:read`
Create/update invoices	`financial_invoice:create`, `financial_invoice:update`
Send invoices	`financial_invoice:send`
Approve/reject	`financial_invoice:approve`, `financial_invoice:reject`
Archive/cancel	`financial_invoice:delete`, `financial_invoice:update`
Create/read/apply credit	`financial_credit_note:create`, `financial_credit_note:read`, `financial_credit_note:apply`
Read summary/ageing	`student_financial_summary:list`, `student_financial_summary:read`
Recalculate summary	`student_financial_summary:recalculate`
Export summaries	`student_financial_summary:export`

The backend remains authoritative. A visible button or role label does not prove an action will be accepted.

End-to-end lifecycle

State model

Approval state and payment state are independent. An approved invoice can remain unpaid. A paid invoice should not be interpreted as approved unless approval evidence also says so.

Guided procedure

Open Finance → Fee Structures. Confirm the fee’s school, academic year, optional term, audience, amount, currency, effective window, approval status, and active flag.
Expected result: the fee is eligible for billing and no field conflicts with the intended period.
Open Finance → Billing Runs. Select the school, fee, population scope, period dates, invoice date, and due date. Prefer backend defaults only when the fee/calendar selection is correct.
Expected result: the form shows the exact scope that will be resolved.
Run a dry run. Do not use force regeneration during initial validation.
Expected result: the run completes without persisting invoices and exposes resolved-student and estimated-total evidence.
Review the dry-run evidence. Compare counts to the school register and inspect zero matches, duplicate candidates, exclusions, and fee-scope intersection.
Expected result: an independent reviewer can explain every included and excluded population.
Create the live run with an idempotency key.
Expected result: a new run enters pending, then progresses asynchronously.
Monitor to a terminal state. Inspect processed, successful, and failed counters.
Expected result: each failure has a code and student/context evidence.
Open generated invoices. Reconcile invoice count and totals to the completed run. Review line items, dates, currency, guardian contact, approval and payment states.
Expected result: generated obligations match the approved billing design.
Approve/reject and send under policy. Rejections require explanatory comments.
Expected result: approval history and communication fields are appended.
Review Student Summaries. Filter by school, academic year, currency and balance status.
Expected result: invoice totals and outstanding values are visible in the correct currency/year scope.
Correct safely. Use invoice cancellation, credit notes, or reruns only after inspecting the original evidence.
Expected result: original and corrective records remain traceable.

Accounting and balance effects

Event	Operational effect	Possible accounting effect
Create fee	no student balance changes	none
Dry billing run	no invoices persist	none
Live invoice creation	student obligation and outstanding balance increase	posting is configuration-dependent
Send invoice	communication timeline changes	none
Approve invoice	authorisation state changes	posting may be enabled by configuration
Apply credit note	invoice outstanding decreases	configured adjustment posting may occur
Cancel/archive	obligation becomes cancelled/archived	correction/posting behaviour is configuration-dependent
Recalculate summary	aggregate snapshot refreshes	no new economic event by itself

Controls and audit evidence

Retain:

fee ID and schedule version;
run ID, scope snapshot, dry-run flag, idempotency key, actor and timestamps;
resolved and failed student counts;
invoice IDs and totals;
approval history and comments;
communication channel, sent date and reminder count;
credit-note reason, approval and applied amount;
recalculated summary timestamp;
correlation/request IDs for support.

Worked scenario

Mupfure Learning Academy bills USD 500 Term 1 Tuition to active Form 3 day students. The fee is approved, school-scoped, effective for the term, and mapped for posting. The bursar selects grade-level scope and runs a dry run. The school register has 82 active students, but the dry run resolves 79 because two are boarders and one is inactive. The reviewer confirms the exclusions. A live run creates 79 invoices. One later transfer requires a credit note rather than deleting the completed run. The student summary is recalculated and shows the reduced outstanding balance while preserving the original invoice and approved adjustment.

Failure modes

Symptom	Likely cause	Evidence to inspect	Safe action	Escalate when
No students matched	scope and fee applicability do not intersect	fee audience, run scope, student status	correct fee/scope and repeat dry run	expected eligible students still excluded
Duplicate failures	invoice already covers student, fee and period	failure `existingInvoiceId`	inspect original; do not force regenerate blindly	original invoice is invalid but cannot be corrected
Run stuck processing	queue/worker issue	timestamps, processed count, request ID	avoid duplicate live request; monitor or support	no progress under operational SLA
Totals differ	fee amount/scope/discount application changed	run snapshot, invoice lines, concession ledger	stop approval and reconcile	persisted invoices conflict with run evidence
Invoice cannot approve	missing permission or invalid state	exact ability, approval history	route to eligible reviewer	backend rejects valid eligible state
Balance appears stale	summary not recalculated or wrong year/currency	recalculated timestamp and filters	recalculate with exact scope	source transactions and summary still disagree

Verification checklist

Practice and knowledge check

Guided practice

Use a non-production test school and the Mupfure Learning Academy scenario. Record the selected school, academic year, term, currency, fee, operator, reviewer, and timestamps. Capture the before-state, action evidence, after-state, and any exception IDs. Do not mark the exercise complete from a success toast alone.

Knowledge check

What record proves the student obligation?
Which status dimension answers whether the invoice is authorised?
Which status dimension answers how much remains unpaid?
What evidence proves the selected student population was correct?
Which action requires a separate reviewer in your school policy?
What should be inspected before retrying a failed or partial operation?
Which later phase owns payment collection and receipt procedures?

Answer rubric: a complete answer names the exact Makronexus record, status, permission or evidence source. Role names alone are insufficient.

Next lesson

Continue to Assign fee applicability.

Learning outcomes​

Exact definition and boundaries​

Prerequisites​

Roles and exact permissions​

End-to-end lifecycle​

State model​

Guided procedure​

Accounting and balance effects​

Controls and audit evidence​

Worked scenario​

Failure modes​

Verification checklist​

Practice and knowledge check​

Guided practice​

Knowledge check​

Next lesson​