Run billing safely

A billing run is an asynchronous, school-scoped instruction that resolves students and creates invoices from one approved fee. It stores status, counts, scope snapshots, telemetry and individual failures. The run itself is not the student obligation; generated invoices are.

Audience: bursars, implementers, billing operators, reviewers, and support analysts
Learning time: 40–50 minutes
Primary route: /finance/billing-runs

Learning outcomes

You will be able to:

• choose dry-run and live-run modes correctly;
• explain run states and cancellation limits;
• use idempotency and duplicate protection;
• monitor progress and reconcile counters;
• classify run failures before retrying;
• prove that generated invoices match the run.

Prerequisites

Requirement	Why
P2 billing readiness passes	prevents missing calendar, period or mapping dependencies
Approved effective fee	source pricing must be valid
Verified student scope	population must be reviewed
Open accounting period	invoice date must be operable
Correct dates	period start/end and invoice/due order must be valid
Exact access	create/list/read/failures/cancel abilities
Reviewer	live run must be reviewed independently
Duplicate policy	forceRegenerate decision documented

Roles and exact permissions

• invoice_billing_run:create
• invoice_billing_run:list
• invoice_billing_run:read
• invoice_billing_run:failures
• invoice_billing_run:cancel
• invoice_billing_run:resolve
• financial_fee:list
• financial_invoice:list
• financial_invoice:read

Request and control fields

Field	Meaning	Safe rule
schoolFeeId	fee used for invoice generation	never null
scopeType	population resolver	match reviewed applicability
scope ID/list	grade/class/subject/students	required by selected scope
period start/end	invoice coverage	start ≤ end and inside calendar
invoiceDate	obligation date	≤ due date and in open period
dueDate	payment deadline	use fee/term defaults only when verified
dryRun	preview without invoices	always use for new/changed design
forceRegenerate	bypass duplicate skipping	exceptional, reviewed correction only
idempotencyKey	dedupe repeated request	use deterministic unique business key

Status model

Only pending and queued runs can be cancelled. Once processing starts, cancellation is blocked to avoid an ambiguous partial state.

Operating sequence

Guided procedure

1. Select school and open Billing runs workspace.
2. Select the exact approved fee. Review its audience and calendar.
3. Choose scope and dates. When sending null dates, document which fee/calendar defaults the backend will resolve.
4. Set dryRun: true, forceRegenerate: false, and a preview idempotency key.
5. Create and monitor the run until terminal.
6. Inspect total_students, processed_students, successful_invoices, failed_students, failure_summary, timestamps and preview metadata.
7. Review individual failures using the failure list permission.
8. Obtain reviewer approval of population and estimated totals.
9. Create a live run with a separate idempotency key.
10. Monitor pending → queued → processing → terminal. Do not submit another run because a page refresh or timeout hides progress; retrieve the run first.
11. Filter Invoices by billingRunId and reconcile IDs, counts and amounts.
12. Record accepted failures and remediation owners.

Failure taxonomy

Code	Meaning	Default response
duplicate_invoice	existing invoice covers student, fee and period	inspect original; keep regeneration off
invoice_creation_failed	invoice service rejected or database failed	inspect error context and fix source
validation_failed	scope/date/ownership validation failed	correct request before retry
no_student_matches	eligibility intersection is empty	correct applicability or population

Duplicate prevention

forceRegenerate is not a retry switch. It can create duplicate obligations if used without inspecting the existing invoice.

Worked scenario

A Form 2 tuition preview resolves 105 students and estimates USD 52,500. The live run processes 105, creates 103 invoices and records two duplicates. The operator does not rerun with force regeneration. The reviewer opens the two existing invoice IDs, confirms they were manually created for the same fee/period, and records those as accepted duplicate outcomes. The run and invoice totals reconcile across all 105 students.

Controls and audit evidence

• request ID and actor;
• school, fee and scope IDs;
• calendar defaults/resolved dates;
• dry/live flag;
• idempotency keys;
• all counters and terminal status;
• failure codes and contexts;
• linked generated invoice IDs;
• reviewer decision;
• cancellation timestamp when applicable.

Failure modes

Symptom	Likely cause	Evidence	Safe action	Escalate when
Pending too long	queue delay	created/queued timestamps	retrieve same run; do not duplicate	exceeds queue SLA
Processing no progress	worker failure	processed count and events	support with request/run ID	no terminal transition
Completed with failures	student-level exceptions	failure list	resolve each category	systemic creation errors
Failed with zero matches	scope intersection empty	preview metadata	repair targeting	source data is valid
Cancel returns 409	run already processing/completed	status timestamps	inspect outcome; do not assume cancelled	partial inconsistent data suspected
Run count ≠ invoice count	failures, duplicate skips or query filter	counters and billingRunId	reconcile each difference	unexplained invoice exists/missing

Verification checklist

• Preview and live run are distinct and traceable.
• Idempotency keys are recorded.
• Force regeneration remained false unless formally approved.
• Terminal counters reconcile.
• Every failure has an owner/outcome.
• Billing-run invoices reconcile by run ID.
• No second live run was created merely because of timeout/refresh.
• Reviewer evidence is retained.

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

1. What record proves the student obligation?
2. Which status dimension answers whether the invoice is authorised?
3. Which status dimension answers how much remains unpaid?
4. What evidence proves the selected student population was correct?
5. Which action requires a separate reviewer in your school policy?
6. What should be inspected before retrying a failed or partial operation?
7. 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 Invoices.