Fees troubleshooting

Common fee setup, collection, online pay, receipts, defaulters, and bulk generate issues with fixes.

This getting started guide covers school software onboarding for K-12 day schools. Whether you are evaluating cloud school management software or configuring Schoolyi after go-live, you will find practical steps for school ERP go live checklist, migrate from Excel to school ERP - written for administrators and staff, not developers.

Last updated August 27, 2026

Setup and configuration

Symptom	Check	Fix
Bulk generate shows zero students	Fee structures and class mapping	Confirm fee structures at /fees/fee-structures apply to student classes; active academic year set at /academic-year.
Fee amounts wrong after structure change	Existing instances vs new structure	Regenerate only affects future instances; adjust or waive old lines at /fees/waivers before re-generating.
GST not applied on receipts	GST settings	Enable and configure rates at /fees/settings/gst; regenerate or edit instances if rate changed mid-year.
Late fee not calculating	Calendar and dunning	Sync working days at /academic-calendar; configure late rules at /fees/settings/late-fees and dunning at /fees/settings/dunning.
Transport fee missing on student	Transport assignment	Assign stop at /transport/students with monthlyFee > 0; TRN instances sync on assign.

Collection and parent pay

Symptom	Check	Fix
Parent pay button missing on /fees/me	Online pay mode and link	Enable online pay in Fees → Settings → Payment gateway; parent must be linked at /parents; use /fees/me?childId=.
Online payment stuck on processing	Gateway mode and cron	Check FEES_ONLINE_PAYMENT_MODE; simulated completes instantly; live Razorpay needs keys. Run fees cron with FEES_CRON_SECRET.
Receipt email failed	SMTP and payment row	Test SMTP at Settings → Email; retry from /fees/payment-history where row shows [RECEIPT_EMAIL:FAILED].
Student still on defaulters after payment	Instance status	Refresh /fees/defaulters; confirm payment applied to correct fee instance at /fees/payment-history.
Cannot record counter payment	Permissions and pending instances	Finance role needs /fees/collections access; student must have pending instances from bulk generate.
Waiver or refund not reflecting	Approval workflow	Complete approval at /fees/waivers or /fees/refunds; check audit status before expecting balance change.
Autopay did not run today	Cron and mandates	Schedule scripts/run-school-cron.sh with FEES_CRON_SECRET; autopay calls POST /api/fees/autopay/run-due for mandates whose dayOfMonth matches today.
Dunning step did not advance	Cron and preview	Run GET /api/fees/dunning/preview first; then POST /api/fees/dunning/run via cron or Dunning ladder UI. Dunning sends reminders — it does not auto-apply late fee amounts.
Simulated online pay not completing	Payment mode env	Set FEES_ONLINE_PAYMENT_MODE=simulated; parent uses /fees/pay-online Pay (simulated) tab or POST /api/fees/payments/online/simulate with parent session.

Fees setup workflow (quick reference)

Create fee types at /fees/fee-types.
Build structures at /fees/fee-structures.
Set installment schedule at /fees/fee-schedule.
Configure late fees, GST, and dunning under /fees/settings.
Run bulk generate at /fees/bulk-generate.
Open collection at /fees/collections or enable parent pay at /fees/me.

Common questions

Quick answers in plain language.

How do I bulk generate student fee instances?+

Open /fees/bulk-generate, select the active academic year and fee structures, preview counts, then run generate. Students must be enrolled in classes with matching fee structures. Review /fees/class-summary before opening collection.

How do I generate fee invoices for all students?+

Fee instances are generated in bulk at /fees/bulk-generate (not per-student invoices). After generate, parents pay at /fees/me and finance collects at /fees/collections. Receipt PDFs are created on payment.