How Recurring Invoice Scheduling Actually Works

When you turn on recurring billing for an invoice, the system does not simply "remember" to resend it. It creates a separate schedule record, calculates a next-run date, and hands that record to a background worker that checks for due schedules on a fixed interval. This article explains exactly how that works — the frequency options, how the next date is calculated when a month is shorter than expected, what happens to the due date, and what you should check if a recurring invoice didn't go out when you expected it to.

What Happens the Moment You Turn On Recurring Billing

Every invoice belongs to an invoice group. When you mark that group as recurring and choose a frequency, the platform writes one row to a dedicated schedule table: your workspace ID, the invoice group ID, the frequency, and a calculated next_run_at date. This row is completely separate from the invoice itself — the invoice is your template, and the schedule is the instruction for when to clone it next.

If you later edit the invoice — change the amount, switch the frequency, or turn recurring off — the schedule updates to match. Turning recurring off doesn't delete the schedule; it flips a flag that marks it inactive, so re-enabling recurring later picks up cleanly rather than creating a duplicate schedule.

The Four Frequency Options and How the Next Date Is Calculated

Four frequencies are supported: weekly, monthly, quarterly, and yearly. Weekly is the simplest — it just adds seven days to the anchor date. Monthly, quarterly, and yearly all work by adding calendar months (one, three, or twelve) to the date.

The part worth understanding is what happens when the target month is shorter than the one you started in. If your invoice date is January 31st and the frequency is monthly, February doesn't have a 31st day. Naively adding a month in JavaScript would silently roll the date over into March 3rd — a bug that would drift your billing date forward every single month until it eventually stopped making sense. Instead, the system detects when the month rollover happened and clamps the date back to the last valid day of the intended month. So January 31st recurring monthly becomes February 28th (or 29th in a leap year), then March 31st, then April 30th — each occurrence lands on the last day of its month rather than sliding forward.

How the Due Date Is Carried Forward

When a new occurrence is generated, the system doesn't just copy the due date from the template invoice — it recalculates it. It measures the gap in days between the original invoice date and its due date (say, a Net 14 term is a 14-day gap), and applies that same gap to the new invoice date. This means if you originally set Net 14 terms, every future occurrence automatically gets a due date 14 days out, even though the calendar dates are different each time.

What Gets Cloned, and What Doesn't

Each new occurrence is a genuinely new invoice group with its own ID, not an edit to the previous one. The line items, client, currency, and template settings all carry forward unchanged. What resets: the invoice date becomes today, the due date is recalculated from the offset described above, the paid amount resets to zero, and the payment date and method are cleared. If you set a base invoice number, each occurrence gets a suffix like -R2, -R3, and so on, so your numbering sequence stays traceable back to the recurring series without colliding with your regular invoice numbers.

If the original template invoice has since been deleted, the schedule has nothing left to clone from. Rather than failing silently or throwing an error on every future check, the system deactivates that schedule the first time it discovers the source is gone.

Draft vs. Sent: What Decides Whether the New Invoice Auto-Emails

Whether the newly generated invoice is created as a draft or immediately sent depends on one thing: whether the invoice has a client email on file. If it does, the new occurrence is marked "sent" and an email goes out automatically to that address. If there's no client email attached, the occurrence is saved as a draft instead, and nothing is emailed — you'd need to open it and send it manually. This is a deliberate safeguard: the system won't silently email a document to nobody, but it also won't block automation just because you haven't filled in every field.

How Often the System Actually Checks for Due Invoices

A background worker checks for due schedules once every hour by default (configurable via an environment variable, though most accounts never touch this). Because billing dates are day-granularity — nothing about recurring billing needs minute-level precision — checking once an hour is more than sufficient; there's no benefit to polling more frequently, and it would just waste server cycles. When the worker runs, it looks for any schedule where next_run_at is today or earlier, generates the next invoice for each one, and advances that schedule's next-run date forward by one more interval. It processes up to 50 due schedules per pass, which comfortably covers even a large backlog if the worker was paused for a while.

If a Recurring Invoice Didn't Go Out

The most common causes, in order of likelihood: the schedule was deactivated because recurring billing was turned off (check the invoice's recurring toggle), the source template invoice was deleted (the schedule silently deactivates itself), or there's no client email on the invoice so it generated correctly but sat as a draft instead of sending. None of these are failures in the underlying mechanism — the schedule and the worker are doing exactly what they're told; the usual fix is checking which of the three conditions above applies to your specific invoice.

Frequently Asked Questions

Does editing a past occurrence change future ones? No. Each generated invoice is independent once created. Editing occurrence #3 has no effect on occurrence #4 — only editing the recurring settings on the active schedule changes what happens going forward.

Can I have more than one recurring schedule per client? Yes. Recurring status is tracked per invoice group, so a client can have several independent recurring invoices — for example, a monthly retainer and a separate quarterly maintenance fee — running on completely different schedules.

What happens if I change the frequency partway through? The next-run date is recalculated from today using the new frequency, so the change takes effect on the very next occurrence rather than retroactively.