Invoices & monthly billing
What an invoice represents
An invoice is a saved bill for one parent and one billing month. Its items include regular subject fees for active students and applicable registration-fee items.
The billingMonth is stored as a date representing the month, normally its first day. The issueDate is separate. Payment dates belong to payment records, not to these invoice dates.
Single-parent flow
Use Invois & Resit to work with a parent's saved invoice. Spring builds and saves business data; the print service renders the supplied invoice payload into a PDF.
Downloading or sending that PDF does not create a payment. Use the payment ledger when money is received.
Monthly batch
The backend exposes a request-driven batch operation:
POST /invoice/batch/generate-current-month?billingMonth=2026-11
If no month is provided, the operation selects the current month in Asia/Kuala_Lumpur. An explicit month uses yyyy-MM.
This is an operational action, not a read-only preview. Use the correct environment and billing month. A render-only PDF test is a different endpoint.
The batch uses a fresh, checkpointed parent reader. Each chunk saves invoice data and a durable delivery handoff together. The configured chunk size is 10.
Duplicate prevention
Spring locks the parent during invoice creation and enforces the unique parent/month key. An existing invoice is not replaced simply because a batch is run again.
Do not remove existing invoice rows to make a migration or batch pass. If older duplicate data exists, investigate and reconcile it before creating the unique index.
Generation and delivery are different states
A successful invoice job means generation completed. A submitted delivery handoff means Laravel accepted the batch. Neither proves that every parent has received an email or Telegram message.
Use the outbox and Laravel batch status to inspect delivery progress. See Batch delivery for retries and uncertain send outcomes.