Statement Generation
Billing
Subscription ManagementStatement Generation
StewardStatement Generation handles the creation of giving statements (tax receipts) for donors. It operates through two mechanisms: an on-demand queue for user-initiated statement runs, and a monthly scheduler that auto-generates statements on the first of each month.
Schedule
| Field | Type | Description |
|---|---|---|
| Monthly Auto-Generation | 1st of month, 6am | Automatically creates a statement run for the previous month if auto-monthly statements are enabled in tenant configuration. |
| On-Demand Generation | User-triggered | Processes statement runs queued by finance staff via the Steward module. Uses BullMQ for reliable processing. |
| ZIP Packaging | On demand | Packages generated statement PDFs into downloadable ZIP archives. Runs with concurrency of 3 for parallel processing. |
| ZIP Cleanup | Every 30 minutes | Removes expired ZIP files from storage to free disk space. |
Monthly Auto-Generation
On the 1st of each month at 6am (tenant local time), the Tenant Scheduler checks whether the tenant has autoMonthlyStatements enabled in their configuration. If so, it:
- Calculates the previous month's date boundaries (e.g., March 1–31)
- Creates a statement run named “Monthly — [Month] [Year]” with type INTERIM
- Queues the run for processing via the existing statement generation infrastructure
- If
autoMonthlyStatementsAutoEmailis also enabled, monitors the run for completion and automatically emails statements to donors once generation finishes
Configuration
| Field | Type | Description |
|---|---|---|
| Auto Monthly Statements | Boolean | Enable or disable automatic monthly statement generation. Found in Tenant Configuration (autoMonthlyStatements). |
| Auto Email | Boolean | When enabled, automatically emails generated statements to donors after the monthly run completes (autoMonthlyStatementsAutoEmail). |
On-Demand Processing
When a finance user creates a statement run from the Steward module, the request is added to the statements BullMQ queue. The Statement Generation Processor picks up the job and calls processRun, which generates individual statement records and PDFs for each eligible donor.
ZIP Generation
After statements are generated, users can request a bulk download as a ZIP file. This is handled by a separate zip-generation BullMQ queue with a concurrency of 3, allowing multiple ZIP jobs to process in parallel.
If a ZIP job fails, the job status is updated to FAILED with the error message recorded for troubleshooting.
Auto-Email Monitoring
When auto-email is enabled for monthly runs, the system polls the run status every 30 seconds for up to 10 minutes. Once the run reaches GENERATED status, emails are dispatched to all donors in the run. If the run fails or does not complete within the timeout, auto-email is skipped and a warning is logged.