Reports
All tools on this page are read-only. The overdue and teacher reports mirror the staff UI. The contract and recurring revenue tools expose student plan assignments for agents.
report_overdue_payments
Section titled “report_overdue_payments”Invoices with status='overdue', joined to the student and plan they
belong to, oldest due_date first.
Returns a list of { invoice_id, amount, due_date, student_name, plan_name }.
report_students_per_teacher
Section titled “report_students_per_teacher”Count of actively-enrolled students per teacher (via classes →
class_enrollments where status='active'), highest first. This is the
basis for teacher pay.
Returns a list of { teacher_id, teacher_name, student_count }.
Student plan assignments
Section titled “Student plan assignments”list_student_contracts
Section titled “list_student_contracts”Returns students with every linked contract and plan, including students without a contract.
Use student_id to inspect one student. Use limit (default 50, maximum 200) and offset to paginate.
Continue until has_more is false. total is the exact student count.
Each contract includes its ID, plan ID and name, status, start and end dates, due day, and billing switch.
agreed_amount_cents comes from the stored contract snapshot added in migration 0003_billing.sql.
catalogue_price_cents is the current plan price. Unknown values are null, never zero.
catalogue_minus_agreed_cents is a comparison with the present catalogue. It is not a stored discount.
There is no stored discount field; discount remains null.
{ "eligibility_date": "2026-09-30", "limit": 200, "offset": 0 }eligibility_date defaults to today in UTC. It checks dates against current stored statuses and values.
It cannot reconstruct historical statuses, plan prices, agreed amounts, or deleted rows.
Students created after that date are explicitly excluded from projection. All returned assignments remain visible.
Contract end dates are inclusive. Contracts created after that date are ineligible.
report_recurring_revenue
Section titled “report_recurring_revenue”Reads every student page and groups the eligible students by plan. It never guesses a student’s plan.
{ "eligibility_date": "2026-09-30" }known_agreed_monthly_cents: subtotal of stored agreed amounts for unambiguous eligible students.unknown_agreed_students: students whose agreed amount is unknown. They do not enter that subtotal.catalogue_estimate_monthly_cents: separate simulation using current catalogue prices for those students.by_plan: student counts, known and unknown amount counts, and both monthly subtotals per plan.classificationsandexcluded: inactive students, no contract, no eligible contract, unavailable plan, students created after the date, and multiple eligible contracts.
An active student with exactly one active contract in its date window is eligible. The billing switch does not change this assignment test. A disabled billing switch does not mean free training. Several eligible contracts, even on the same plan, exclude the student from both totals pending review. The report counts each included student once. It does not silently choose the newest contract.
Projected recurring revenue is not received income. received_income_cents is null.
The report does not calculate invoices, payments, prorated amounts, charges, or finance journal entries.
Its monthly values are current-record projections, not promises of collection or historical accounts.
A known agreed subtotal can be partial. Always report the unknown and excluded counts with the amount.
All reads use the caller’s JWT and organization. Failed joins, unknown row counts, or detected page changes return an error. Pagination is not an atomic database snapshot; retry if records change during the read.