PSA/ee/docs/plans/2026-04-06-invoice-service-period-layout-fields-design.md

Invoice Service Period Layout Fields Design

Date: 2026-04-06 Status: Approved

Summary

Add first-class invoice layout fields for canonical recurring invoice service periods and improve line-item table discoverability for existing per-row service period data.

Chosen scope:

• Header-level bindings for recurring invoice service period start, end, and formatted label
• Table suggestion support for row-level service period fields
• No canonical detail-period list rendering in V1

Problem

Invoice layouts currently do not expose a first-class header binding for service periods, even though recurring invoices already carry canonical recurring service period summary data upstream.

At the same time, line items already contain service period summary fields in the renderer view model, but the invoice designer does not make those row fields discoverable in the table editor.

This makes it difficult for template authors to show service periods consistently on invoices.

Goals

1. Expose canonical recurring invoice service periods as header-level invoice layout fields.
2. Provide a formatted service period label suitable for printed invoices.
3. Make row-level service period fields easy to discover in dynamic table authoring.
4. Keep the implementation canonical and avoid inventing service periods for invoices that do not have them.

Non-Goals

1. Rendering nested canonical recurringDetailPeriods lists in templates.
2. Deriving header-level service periods from line items.
3. Automatically changing shipped standard invoice templates.
4. Adding row-level formatted service period labels in V1.

Approved Product Decisions

Scope

Approved option: B

• Header + line items
• No nested canonical detail-period rendering

Missing Header Period Behavior

Approved option: A

• If the invoice does not have canonical recurring invoice service period summary data, the header fields resolve to blank/null.
• No fallback to line-item aggregation.

Formatted Label

Approved format: A

• Jan 1, 2025 - Feb 1, 2025

Design

1. Data Contract and Binding Model

Add three invoice-level renderer fields:

• recurringServicePeriodStart?: string | null
• recurringServicePeriodEnd?: string | null
• recurringServicePeriodLabel?: string | null

These fields are populated only from canonical recurring invoice summary fields already produced upstream:

• recurring_service_period_start
• recurring_service_period_end

For line-item tables, keep the existing row model unchanged and make these paths discoverable:

• item.servicePeriodStart
• item.servicePeriodEnd
• item.billingTiming

2. UX / Designer Behavior

Header fields

Expose these in the invoice designer field picker under the Invoice category:

• Recurring Service Period Start
• Recurring Service Period End
• Recurring Service Period

The formatted label field should render like:

• Jan 1, 2025 - Feb 1, 2025

Behavior:

• Populated only when canonical recurring header period data exists
• Blank/null otherwise
• Derived from canonical invoice header dates, not from line items

Table discoverability

In the table editor, add row binding suggestions for:

• item.servicePeriodStart
• item.servicePeriodEnd
• item.billingTiming

This is a discoverability enhancement only. The row data already exists in the renderer model.

3. Implementation Details

Renderer view model

Update:

• packages/types/src/lib/invoice-renderer/types.ts

Add optional top-level fields for recurring service period start, end, and label.

Adapter mapping

Update:

• packages/billing/src/lib/adapters/invoiceAdapters.ts

Map canonical invoice summary fields from source invoice data into the renderer model. Build the formatted label in the adapter layer so preview and PDF rendering share one source of truth.

Binding catalog

Update:

• packages/billing/src/lib/invoice-template-ast/standardTemplates.ts

Add value bindings for:

• recurringServicePeriodStart
• recurringServicePeriodEnd
• recurringServicePeriodLabel

Designer field catalog

Update:

• packages/billing/src/components/invoice-designer/fields/fieldCatalog.ts

Add first-class field definitions for the new invoice-level fields.

Preview support

Update:

• packages/billing/src/components/invoice-designer/preview/previewBindings.ts

Resolve the three new invoice bindings so designer preview matches runtime rendering.

Table suggestions

Update:

• packages/billing/src/components/invoice-designer/inspector/widgets/TableEditorWidget.tsx

Include service period-related item.* suggestions in row binding suggestions.

4. Error Handling and Behavior Rules

Canonical-only header behavior

Rules:

• If both canonical header dates are absent, all three header bindings resolve to null
• Do not derive from line items
• Do not inject placeholders in the renderer model

Label formatting behavior

Rules:

• Start + end present -> produce formatted label
• One side missing -> label is null
• Invalid date strings -> fail safely to null or equivalent non-throwing behavior in the adapter helper

Table row behavior

Rules:

• Missing row service period values render like any other missing row value
• item.billingTiming remains a raw text value in V1

Files Expected to Change

• packages/types/src/lib/invoice-renderer/types.ts
• packages/billing/src/lib/adapters/invoiceAdapters.ts
• packages/billing/src/lib/adapters/invoiceAdapters.test.ts
• packages/billing/src/lib/invoice-template-ast/standardTemplates.ts
• packages/billing/src/components/invoice-designer/fields/fieldCatalog.ts
• packages/billing/src/components/invoice-designer/preview/previewBindings.ts
• packages/billing/src/components/invoice-designer/preview/previewBindings.test.ts
• packages/billing/src/components/invoice-designer/inspector/widgets/TableEditorWidget.tsx

Testing Plan

1. Adapter tests

   • Maps canonical recurring header service period start/end into renderer view model
   • Produces formatted label when both dates are present
   • Leaves fields null when canonical header period is absent

2. Preview binding tests

   • Resolves new header bindings correctly
   • Formats label correctly
   • Returns null when canonical header fields are missing

3. Table editor tests

   • Suggested row bindings include item.servicePeriodStart, item.servicePeriodEnd, and item.billingTiming

4. Regression checks

   • Existing templates continue to load and render unchanged
   • Standard templates remain structurally unchanged unless explicitly edited later

Risks

1. Date formatting inconsistencies

   • Mitigation: centralize label construction in one adapter helper

2. Ambiguity between header and row service periods

   • Mitigation: use explicit naming and field descriptions in the field catalog

3. Historical invoices without canonical recurring metadata

   • Mitigation: resolve header bindings to null and avoid fallback derivation

Recommendation

Implement the approved V1 scope exactly as designed:

• canonical header bindings for recurring invoice service periods
• formatted header label
• row-level table field discoverability
• no fallback derivation and no nested canonical detail-period rendering