PSA/ee/docs/plans/2026-01-09-billing-cycle-anchors/PRD.md

PRD — Billing Cycle Anchors (Day-of-Month) + Exclusive End Dates

• Slug: billing-cycle-anchors
• Date: 2026-01-09
• Status: Draft

Summary

Add per-client billing cycle anchors so MSPs can invoice clients on non-calendar boundaries (e.g., “bill on the 10th of each month”), while standardizing the billing domain on a single, consistent date-range convention: billing period end dates are exclusive.

Problem

Today Alga supports picking a billing cycle type per client (weekly/bi-weekly/monthly/quarterly/semi-annually/annually), but cycle generation is effectively aligned to calendar boundaries for monthly+ (and has inconsistent logic for weekly/bi-weekly), and the billing domain has mixed semantics for whether a period end date is inclusive or exclusive. This prevents common MSP workflows like:

• “Invoice this client monthly on the 10th.”
• “Invoice this client annually on their service anniversary.”
• “Invoice this client every 2 weeks starting next Friday.”

Goals

• Allow admins to configure a per-client billing cycle anchor appropriate to the client’s billing frequency.
• Ensure billing, proration, and overlap validation all treat billing periods as [start, end) (end is exclusive).
• Ensure the design works across cycle types: weekly, bi-weekly, monthly, quarterly, semi-annually, annually.
• Preserve existing behavior by default (clients without anchors keep the current “calendar-aligned” schedule for monthly+/annual and the current rolling schedule for weekly/bi-weekly).

Non-goals

• Replacing client_billing_cycles with a new “bill run” system; we continue to use client_billing_cycles as the source of truth for concrete billing periods.
• Retroactively rewriting already-invoiced billing periods.
• Supporting arbitrary time-of-day boundaries; billing periods remain UTC-midnight dates.
• V1: complex “29/30/31st of month” semantics unless explicitly requested (see Open Questions).

Users and Primary Flows

Personas

• Billing Admin (MSP): configures billing cycles and anchors per client; generates invoices.
• Ops/Admin: adjusts client billing settings during onboarding/renewal.

Primary flows

1. Billing admin selects a client from the Clients menu.
2. In the client detail view, navigates to the client’s Billing tab.
3. Chooses the billing cycle type and configures the anchor (cycle-type-aware).
4. System uses the configured schedule to generate upcoming billing cycles (automated nightly + manual “create next cycle”).
5. Billing admin generates invoices from billing cycles (existing).

Secondary flow:

• Billing admin opens Billing → Billing Cycles to review a cross-client summary and click through to a specific client’s Billing tab.

UX / UI Notes

UI placement

• Billing schedule configuration (cycle type + anchor + preview) lives on the Client → Billing tab.
• The Billing → Billing Cycles tab is summary-only (no schedule editing); it links to the client’s Billing tab for changes.

Anchor UX should be cycle-type aware:

• Weekly: choose “weekday” (Mon–Sun). Optionally show the computed “next start date” preview.
• Bi-weekly: choose a concrete “first cycle start date” (UTC date) so parity is stable.
• Monthly: choose “day of month” (default 1). V1 is limited to 1–28 for predictability.
• Quarterly: choose “start month” + day-of-month (1–28), with a preview of next cycle boundaries.
• Semi-annually: choose “start month” + day-of-month (1–28), with a preview of next cycle boundaries.
• Annually: choose “start month” + day-of-month (1–28), with a preview of next cycle boundaries.

UI should make the date semantics explicit in copy/tooltips: “Billing periods are [start, end); end date is the start of the next period.”

Requirements

Functional Requirements

Billing schedule configuration (cycle type + anchor)

• Store a per-client anchor configuration.
• Validate anchor values (ranges, required fields per cycle type).
• Use anchor configuration when generating new client_billing_cycles rows.
• Allow updating schedule configuration (cycle type and/or anchor), with guardrails to avoid breaking already-invoiced periods.

Cycle generation

• Initial cycle creation uses anchor logic to pick the correct current cycle start.
• Subsequent cycle creation advances deterministically by cycle type from the last cycle’s boundary.
• Manual “Create Next Cycle” uses the same logic as the scheduled job and respects anchor configuration.
• Schedule updates (cycle type and/or anchor) take effect after the last invoiced cycle:
  • Compute cutoverStart = lastInvoiced.period_end_date (exclusive end = next start).
  • Create a transition period [cutoverStart, nextAnchorBoundary) (if cutoverStart is not already aligned).
  • Create subsequent full periods aligned to the configured anchor.
• Transition periods require deterministic proration of fixed recurring charges based on actual period length vs canonical cycle length.

Exclusive end date consistency

• All billing periods are treated as [period_start_date, period_end_date).
• Proration factors and “days in period” calculations must be consistent with exclusive end semantics.
• Overlap detection and “cannot span cycle change” validation must use exclusive end semantics.

Non-functional Requirements

• Deterministic and timezone-safe: all persisted billing boundary dates are UTC-midnight ISO8601 strings.
• Backward compatible: existing clients with no anchor configured continue behaving as today.

Data / API / Integrations

Data model

Add anchor fields to client_billing_settings (preferred, since it already stores billing knobs) rather than adding new columns to clients or client_billing_cycles.

Proposed shape (final schema is a design decision in implementation):

• client_billing_settings.billing_cycle_anchor_day_of_month (int, nullable)
• client_billing_settings.billing_cycle_anchor_month_of_year (int, nullable; for annual/semi/quarterly where applicable)
• client_billing_settings.billing_cycle_anchor_day_of_week (int, nullable; ISO 1=Mon..7=Sun)
• client_billing_settings.billing_cycle_anchor_reference_date (date/timestamp UTC-midnight, nullable; for bi-weekly parity / “first cycle start”)

API / server actions

• Add server actions for reading/updating the anchor configuration.
• Add a server action for updating a client’s billing schedule (cycle type + anchor) that applies the same cutover behavior as anchor updates.
• Ensure invoice generation continues to rely on client_billing_cycles.period_start_date/period_end_date (no anchor logic in invoice generation).

Security / Permissions

• Same permissions as existing billing configuration: only tenant users with billing/admin privileges can update anchors and create cycles.

Observability

• Not in scope for V1 (no new dashboards/metrics); rely on existing logs and error surfaces.

Rollout / Migration

1. Ship schema changes for anchor fields on client_billing_settings.
2. Backfill default anchor values for existing clients:
   • monthly/quarterly/semi/annually: default day-of-month = 1, default start-month = current calendar convention (Jan/Apr/Jul/Oct; Jan/Jul; Jan).
   • weekly/bi-weekly: preserve current rolling behavior unless the admin sets an anchor.
3. Update cycle generation to use anchor settings for newly created cycles.
4. Update date-range semantics and fix inconsistent end-date usage.
5. Document the semantics and migration notes in billing docs.

Open Questions

1. For weekly: do we also want a “first cycle start date” option (like bi-weekly) to make weekday-only anchors less ambiguous for initial creation?
2. When changing schedule (cycle type and/or anchor), should the UI show an explicit warning that future non-invoiced billing cycles will be regenerated under the new schedule?

Acceptance Criteria (Definition of Done)

• A billing admin can set a monthly anchor day (e.g., 10) for a client and the system generates monthly billing cycles starting/ending on the 10th.
• Weekly, bi-weekly, quarterly, semi-annual, and annual cycle generation continues to work and respects anchors when configured.
• Billing, proration, and overlap validation treat billing periods as [start, end) with end exclusive.
• Manual “Create Next Cycle” respects anchor configuration and no longer ignores provided anchor/effective date inputs.
• Billing cycle type changes follow the same cutover behavior as anchor changes (no retroactive modification of invoiced cycles; future non-invoiced cycles are regenerated under the new schedule).
• Existing clients without anchors are not behaviorally broken; already-invoiced cycles are not modified.