PSA/ee/docs/plans/2026-04-12-unapproved-time-blocks-recurring-invoices-design.md

Unapproved Time Blocks Recurring Invoices Design

Date: 2026-04-12 Slug: unapproved-time-blocks-recurring-invoices

Summary

Recurring invoice windows that contain billable time entries which are not yet approved should be treated as not invoice-ready. Instead of silently billing partial work or burying the problem in preview flows, Automatic Invoices should split those windows into a dedicated Needs Approval section and prevent generation until the underlying time is approved.

Current-State Findings

Code review in this worktree showed:

• Contract hourly billing already filters time_entries.approval_status = 'APPROVED' in packages/billing/src/lib/billing/billingEngine.ts.
• Unresolved/non-contract time billing also filters time_entries.approval_status = 'APPROVED' in the same billing engine.
• rolloverUnapprovedTime(...) explicitly targets DRAFT, SUBMITTED, and CHANGES_REQUESTED entries after recurring invoice generation.

So the primary issue is less “the core billing query intentionally bills unapproved time” and more:

1. recurring bulk invoicing does not clearly surface windows that are blocked by unapproved billable time,
2. operators lack a dedicated queue for approval-dependent windows, and
3. generation should still re-check the approval rule server-side in case the UI is stale.

Product Rule

A recurring invoice window is blocked when it contains at least one uninvoiced time entry that would otherwise be billable for that window but whose approval_status !== 'APPROVED'.

This blocks the entire invoice window, even if the same window also contains fixed, license, usage, or other non-time charges.

UX

Automatic Invoices layout

Split the recurring invoice experience into two sections:

1. Needs Approval

   • Shown above Ready to Invoice.
   • Contains grouped invoice windows that are otherwise billable but blocked by unapproved time.
   • Shows client, service period, invoice window, and X unapproved entries.
   • Includes a Review Approvals action.
   • Rows are informational/actionable only: no generation, no selection.

2. Ready to Invoice

   • Contains only windows that are fully invoiceable now.
   • Existing preview/generate behaviors remain available.

Operator messaging

• Section helper text should explain that these windows are blocked because billable time is not yet approved.
• Needs Approval rows should show blocked counts, not blocked hours, because entry count is more actionable for approvers.
• After bulk generation, the screen may still summarize how many windows remain in Needs Approval, but blocked windows should not be mixed into Ready to Invoice selection.

Detection Rules

Approval blockers must be computed with the same effective billing semantics as invoice selection:

• Contract hourly time: use the same service-period timing, client/work-item scope, service matching, and assignment logic used for approved-billing selection, but search for non-approved entries.
• Unresolved/non-contract time: only treat unresolved time as a blocker when unresolved/non-contract time is actually part of the recurring selection scope.
• Ignore already invoiced entries.
• Treat any non-approved status as blocking, not only today’s named workflow states.

A client having unrelated unapproved time elsewhere must not block unrelated invoice windows.

Enforcement

Read path

The recurring due-work read path should classify windows with approval blockers and include blocker metadata in the row/candidate models.

Generate path

Invoice generation must re-run the blocker check immediately before invoice creation and reject blocked windows with a descriptive error such as:

This invoice window is blocked because it contains 7 unapproved time entries.

That protects against stale tabs, direct API calls, and approval-state races.

Implementation Shape

Likely touchpoints:

• packages/billing/src/actions/billingAndTax.ts
• packages/billing/src/components/billing-dashboard/AutomaticInvoices.tsx
• packages/billing/src/actions/invoiceGeneration.ts
• packages/billing/src/actions/recurringBillingRunActions.ts
• packages/types/src/interfaces/recurringTiming.interfaces.ts
• Possibly shared recurring due-work helpers / billing-engine helpers for reusable blocker detection

Edge Cases

• Mixed fixed + hourly window with one matching unapproved time entry: block the whole window.
• Window becomes approved after manager action: it moves from Needs Approval to Ready to Invoice on refresh.
• UI showed ready earlier but approval status changed before generate: server rejects generation.

Testing Focus

• Due-work classification between Needs Approval and Ready to Invoice
• Window-specific blocker semantics vs unrelated client time
• Server-side rejection of blocked generation attempts
• Automatic Invoices rendering and non-selectability of blocked rows
• Transition from blocked to ready after approval