Recurring Invoices

Recurring invoices automate the generation of invoices on a defined schedule. NexusRMS creates invoice copies from a template at your chosen frequency, optionally sending them to clients and charging payment methods automatically. This feature is ideal for retainers, subscriptions, ongoing equipment hire, and any arrangement requiring regular billing.

Creating a recurring invoice

Navigate to Financial > Recurring Invoices and click Create Recurring Invoice. The form fields are:

• Name (required) — A descriptive label for the recurring schedule (e.g., "Monthly PA System Hire", "Quarterly Retainer")
• Client (required) — The client who will receive the generated invoices
• Project — Optional linked project for context and reporting
• Template Invoice — An existing invoice to use as the template. Line items, amounts, and notes are copied from this invoice.
• Frequency (required) — How often invoices are generated: daily, weekly, fortnightly, monthly, quarterly, semi_annually, annually, or custom
• Interval — Number of frequency units between invoices (e.g., interval of 2 with monthly frequency generates an invoice every two months). Defaults to 1.
• Day of Month — For monthly, quarterly, semi-annual, and annual frequencies, the day of the month on which invoices are generated (1 to 28 to avoid month-length issues)
• Day of Week — For weekly and fortnightly frequencies, the day of the week (0 for Sunday through 6 for Saturday)
• Start Date (required) — When the recurring schedule begins. The first invoice is generated on this date.
• End Date — Optional date on which the schedule stops. Leave blank for indefinite recurrence.
• Max Occurrences — Optional limit on the total number of invoices generated. The schedule completes automatically when this limit is reached.

The reference is auto-generated in the format REC-INV-YYYY-#### (e.g., REC-INV-2026-0001).

Line items

Recurring invoice line items are stored as a JSON array in the line_items field. Each entry defines the name, quantity, unit_price, and other details that are copied to each generated invoice. The financial summary fields are calculated from the line items:

• subtotal — Pre-tax total of all line items
• tax_rate — Tax percentage applied
• tax_amount — Calculated tax amount
• total — Final total including tax
• currency — ISO 4217 currency code (e.g., GBP, USD, EUR)

Automatic generation

NexusRMS checks recurring invoices daily using the isDueForGeneration() method, which returns true when the current date matches next_invoice_date and the schedule has not reached its maximum occurrences. The generateInvoice() method then:

1. Creates a new Invoice record with all fields copied from the recurring invoice template, including client, project, amounts, currency, and notes
2. Sets the invoice issue_date to today and the due_date to today plus payment_terms_days
3. Creates InvoiceItem records from the line_items array
4. Increments the occurrences_count field
5. Records last_invoice_date as today
6. Calculates the next_invoice_date using calculateNextInvoiceDate() based on the frequency and interval settings
7. Checks hasReachedMaxOccurrences() and hasReachedEndDate(), automatically marking the schedule as completed if either condition is met

Auto-send and auto-charge

Two automation toggles control what happens after an invoice is generated:

• auto_send — When enabled, the generated invoice is immediately marked as sent and emailed to the client. The email uses the recurring invoice's email_subject, email_body, and email_recipients fields for customisation.
• auto_charge — When enabled and Stripe Connect is configured for the client, the system automatically attempts to charge the client's stored payment method for the invoice total.

Email template

Each recurring invoice has its own email template fields for customising the notification sent with each generated invoice:

• email_subject — Custom subject line for the invoice email
• email_body — Custom HTML body content
• email_recipients — JSON array of additional recipients beyond the primary client contact

If these fields are left blank, the system uses your tenant's default invoice email template.

Recurring invoice statuses

1. active — The schedule is running and invoices will be generated on the next_invoice_date. This is the initial status on creation.
2. paused — The schedule has been temporarily suspended via pause(pausedBy). The paused_at timestamp and paused_by user are recorded. No invoices are generated while paused. Use resume() to clear the paused state and set the status back to active.
3. completed — The schedule has finished naturally because max_occurrences was reached or end_date has passed. Set automatically by markAsCompleted().
4. cancelled — The schedule has been permanently stopped via cancel(cancelledBy). The cancelled_at timestamp and cancelled_by user are recorded. Cancelled schedules cannot be reactivated.

Generated invoices

All invoices generated by a recurring invoice schedule are linked via the recurring_invoice_id field on the Invoice model. The invoices() relationship on the RecurringInvoice model returns all generated invoices, allowing you to review the complete billing history for a recurring schedule from a single page.

Notes

Recurring invoices support two notes fields:

• notes — Client-visible notes that are copied to each generated invoice
• internal_notes — Staff-only notes that are copied to each generated invoice's internal notes field

Invoice prefix

The invoice_prefix field allows you to set a custom prefix for invoices generated by this schedule (e.g., "RET" for retainer invoices). If left blank, the system uses your tenant's default invoice prefix. Generated invoices are numbered sequentially within the prefix and year.

Tips

• Use day_of_month values between 1 and 28 — Avoid 29, 30, and 31 to prevent issues with shorter months like February.
• Set an end date or max occurrences for fixed-term arrangements — This prevents invoices from being generated indefinitely. For a 12-month contract, set max_occurrences to 12.
• Enable auto_send for hands-free billing — Combined with auto_charge, you can create a fully automated billing cycle that requires no manual intervention.
• Pause rather than cancel for temporary stops — If a client needs to skip a billing period, use pause() to preserve the schedule and resume() when billing should restart.
• Review generated invoices periodically — Even with full automation, check the invoices() list regularly to ensure amounts, line items, and delivery status are correct.
• Link to a project for reporting — Setting the project_id field connects all generated invoices to a project, making financial reporting and profitability analysis more accurate.