Assign fee applicability

In the current verified product contract, fee “assignment” is the controlled combination of fee applicability and billing-run population scope. The evidence reviewed for P3 does not establish a separate permanent student-fee assignment object as the universal billing mechanism. Student debt begins when an invoice is created.

Audience: bursars, administrators, implementers, billing reviewers, and support analysts
Learning time: 30–40 minutes
Primary routes: /finance/fees, /finance/billing-runs

Learning outcomes

You will be able to:

• distinguish fee applicability from invoice creation;
• configure and review grade, class, student-type and conditional targeting;
• choose the correct billing-run scope;
• explain the mandatory/optional fee safety rule;
• verify the population with a dry run;
• diagnose missing and unexpected students.

Exact definition and boundaries

Fee applicability describes who may be billed by a fee. Run scope describes which student population the operator asks Makronexus to evaluate. The live target is their intersection.

A broad school run does not override a Form 3-only fee. A selected student does not become billable when the fee is inactive, outside its effective window, or incompatible with that student’s properties.

Prerequisites

Requirement	Evidence
Correct school	fee and students belong to the selected school
Correct calendar	fee academic year and optional term match billing intent
Approved active fee	approval status and is_active permit use
Effective dates	billing period overlaps effective_from/effective_until
Positive amount and currency	fee amount and ISO currency are valid
Student attributes	active status, grade, class and boarding status are current
Eligibility design	optional/conditional rules are machine-readable where broad billing is intended
Access	exact abilities are present

Roles and exact permissions

Action	Exact ability
List/read fees	financial_fee:list, financial_fee:read
Create fee	financial_fee:create
Update applicability	financial_fee:update
Archive fee	financial_fee:delete
List/read billing runs	invoice_billing_run:list, invoice_billing_run:read
Create dry run	invoice_billing_run:create
Read failure population	invoice_billing_run:failures
View students/rosters	school IAM abilities for student and class records
View invoices after run	financial_invoice:list, financial_invoice:read

Applicability field reference

Field	Meaning	Billing consequence
applies_to	audience mode	selects all, grades, classes, boarding/day or other configured group
grade_level_ids	allowed grades	excludes students outside listed grades
class_ids	allowed class divisions	excludes students outside listed classes
student_type	day/boarding/half-boarding filter	adds boarding-status filter
fee_category	core/optional/conditional classification	may require explicit list or eligibility rules
is_mandatory	compulsory flag	non-mandatory without rules is protected from broad runs
eligibility_rules	machine-readable conditions	final student list must pass conditions
academic_year_id	billing year	run and student scope must use compatible year
term_id	optional term scope	annual fees remain null; term fees must match
effective_from, effective_until	use window	billing period must overlap
amount, currency	price basis	copied into invoice calculations/snapshots

Scope choices

Scope type	Required input	Typical use
school	selected school	mandatory all-school fee after dry-run proof
grade_level	gradeLevelId	grade-specific tuition/levy
class_division	classDivisionId	class-specific charge
subject_class	subjectClassId	subject/course charge
student_list	1–500 studentIds	optional fee, exceptions, hand-picked group

Guided procedure

1. Open the selected fee. Record its ID, school, year, term, approval, active state, amount, currency, frequency, effective dates and scope fields.
   Expected result: the fee is valid for the intended billing period.

2. Review student source data. Confirm active status, school, grade/class and boarding status.
   Expected result: the register is current enough to drive automated targeting.

3. Classify the fee. Decide whether it is mandatory, optional, or conditional.
   Expected result: broad scope is used only where the rules safely support it.

4. Choose run scope. Select the narrowest scope that still represents the business decision. Use student_list for elective or exceptional charges without machine-readable eligibility.
   Expected result: requested scope can be explained without relying on operator memory.

5. Run dry. Keep forceRegenerate false.
   Expected result: no invoice persists; population and estimated totals are available.

6. Reconcile population. Compare dry-run students/count to a roster extract. Explain exclusions and unexpected inclusions.
   Expected result: reviewer signs the population evidence.

7. Only then authorise live billing.
   Expected result: live run repeats an approved scope rather than creating a new population decision.

Worked scenario

Mupfure Learning Academy has a USD 120 Science Laboratory Fee for Form 4 students enrolled in a subject class. The fee’s grade scope includes Form 4 and its eligibility rule requires the subject-class relationship. A school-wide run would still be filtered, but it would hide the operator’s intent. The implementer selects subject_class, previews 34 students, and compares the list to enrolment. One withdrawn student remains in the subject-class table, so the source roster is corrected before the live run.

Controls and audit evidence

Store the fee version, scope type and IDs, student source date, dry-run ID, result count, excluded count, reviewer, approval timestamp and live-run ID. Avoid screenshots as the only evidence; retain identifiers and exports where available.

Balance and accounting effect

Applicability review and dry runs do not alter balances. Live invoice creation increases student obligations. Posting into the General Ledger remains configuration-dependent and must be verified from posting evidence rather than inferred from invoice presence.

Failure modes

Symptom	Likely cause	Evidence to inspect	Safe action	Escalate when
Expected student missing	inactive/wrong grade/class/type	student profile and fee scope	correct source data or scope	source appears correct but service excludes
Unexpected student included	fee too broad or stale student attributes	fee and roster snapshot	stop before live run and correct	live invoices already created
Broad optional fee rejected	no eligibility rules	fee category and rules	use explicit student_list	product requires another supported rule
Scope mismatch 422	selected grade/class conflicts with fee	request and fee IDs	choose compatible scope	valid intersection is rejected
Zero matches	no active intersection	dry-run metadata	repair fee or student data	data appears valid but result remains zero
More than 500 explicit students	API limit	selected list size	split controlled batches with unique keys	requirement needs larger atomic list

Verification checklist

• Fee applicability is explicit and approved.
• Student source data is current.
• Optional fees use explicit lists unless rules exist.
• Requested scope is the narrowest defensible scope.
• Dry-run population reconciles to an independent roster.
• No unexpected student is accepted as “close enough.”
• Live run references the reviewed population decision.
• Evidence includes IDs, counts, actor and reviewer.

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 Run billing safely.