PSA/ee/docs/plans/2026-03-16-service-period-first-billing-and-cadence-ownership/REPORTING_DATE_BASIS.md

Reporting And Analytics Date-Basis Policy

Recurring service-period-first billing makes date basis an explicit product rule instead of an accidental side effect of whichever table a reader touched first.

Policy Matrix

Reporting family	Primary surfaces	Authoritative date basis	Historical / fallback rule	Notes
Billing overview and invoice summary surfaces	client portal overview cards, recent invoice activity, invoice list summaries, payment-success summaries	invoice-window and invoice-header dates for operational state; canonical recurring service-period summaries only as explanatory recurring coverage metadata	if canonical recurring detail rows are absent, keep invoice-header / financial-document semantics and label the artifact accordingly	Do not silently reinterpret pending, overdue, or unpaid states as service-period metrics.
Contract revenue reporting	contract revenue report, contract summary YTD cards, revenue report definitions	invoice_charge_details.service_period_end when canonical recurring detail rows exist	fall back to invoices.invoice_date for historical flat invoices or manual rows without canonical detail periods	Revenue is the main reporting family that pivots to billed service-period semantics.
Contract expiration and renewal-decision reporting	contract expiration report, renewal decision summary cards	client_contracts.end_date and renewal decision_due_date	no service-period fallback because this family is assignment-timeline based, not invoice-timing based	Expiration remains assignment / renewal workflow reporting even after recurring invoice timing changes.
Credit reconciliation and discrepancy reporting	reconciliation report lists and summary counts	credit_reconciliation_reports.detection_date, discrepancy status, and transaction / expiration financial dates	canonical recurring service-period lineage may appear additively for explanation, but it does not drive report totals or aging buckets	Reconciliation stays financial-control reporting, not service-period reporting.
Financial analytics and collections-style aggregates	financial analytics API, invoice-count and net-revenue trends, credit issuance/application analytics	invoices.created_at, invoices.due_date, invoices.finalized_at, and transactions.created_at depending on the metric	no recurring service-period fallback unless a later analytics plan explicitly redefines that metric	These surfaces answer financial-operational questions, not coverage-window questions.
Service metrics and recurring coverage summaries	recurring invoice detail summaries, billed-service-period cards, recurring allowance summaries	canonical recurring service periods and explicit allowance periods	if canonical detail rows are absent, show financial-only fallback copy rather than synthesizing service periods from headers	These surfaces are allowed to diverge from invoice-date views because they are intentionally coverage-based.

Mixed-Cadence Rule

When invoice dates and recurring service periods diverge because client-cadence and contract-cadence work coexist:

• financial-operational surfaces keep their invoice-header or transaction-date basis
• recurring coverage surfaces keep canonical service-period basis
• readers must label which basis they are showing instead of flattening one into the other silently

Recent invoice activity is one of the portal surfaces that may display canonical recurring coverage summaries, while pending-invoice counts remain invoice-state metrics.

Implementation Notes

• Prefer canonical recurring service periods only for readers whose product question is "what coverage was billed?"
• Prefer invoice-header, due-date, finalized-date, or transaction-date semantics for readers whose product question is "what financial document was issued, due, paid, expired, or reconciled?"
• Historical flat invoices remain valid inputs; do not synthesize canonical service periods for them just to satisfy a reporting shape.