14.11. Inspect, Repair, and Troubleshoot Recurring Service Periods on MSP Contracts

Navigate to Billing > Invoicing > Service Periods. The page heading reads Recurring Service Periods and gives MSP billing admins an operational view of the recurring billing windows the system has materialized for each contract line. Use it to confirm that scheduled charges are queued correctly, diagnose missing recurring invoices, and repair schedules that have drifted out of alignment.

What a Service Period Represents

Each service period is a single, materialized billing window tied to one contract line. Every row on the table tracks five things that together drive whether and when the line will appear on an invoice:

Service Period (Start / End): The half-open interval [start, end) during which the service is delivered. The start date is included, the end date is not — so the next period picks up exactly where the last one left off, with no overlap and no gap.
Cadence Source: Whether the period follows the Client schedule (the client's billing cycle anchor) or the Contract anniversary (the contract's own start date and frequency).
Billing Timing: Whether the line bills in advance (charged at the start of the period it covers) or in arrears (charged after the period closes).
Invoice Window: The window during which this period is available for invoicing. For advance billing, the invoice window matches the service period. For arrears billing, the invoice window shifts to the following period — the charge becomes invoiceable only after the period it covers has ended.
Lifecycle State: Where the period currently sits in the billing process (see below).

The Seven Lifecycle States

Every recurring service period is in exactly one of these states. Understanding them is the foundation of troubleshooting recurring billing.

State	Meaning
generated	The system created the period on its normal cadence; it is available for invoicing when its window opens.
edited	The period was manually adjusted by an operator (dates, scope, or both).
skipped	The period was deliberately excluded from due selection and will not be invoiced unless re-edited.
locked	The period is locked pending invoice generation — protected from further edits while billing runs.
billed	The period has been linked to a finalized invoice charge and represents booked revenue.
superseded	The period was replaced by a newer revision — typically after a cadence edit, repair, or regeneration.
archived	The period is no longer active and is retained for history only.

Once a period reaches billed or superseded, it cannot be re-edited or re-billed; the only forward transition is to archived. Archived periods are terminal — they cannot transition further. This is what protects historical revenue from being silently rewritten when schedules change.

How Service Periods Are Generated

Service periods are produced automatically from three contract-line settings:

The billing frequency (monthly, quarterly, semi-annually, annually).
The cadence source — clientSchedule (anchored to the client's billing cycle) or contractAnniversary (anchored to the contract start date).
The billing timing — advance or arrears.

The system materializes periods on a rolling horizon, so the table normally shows a mix of past periods (with billed history) and a few future periods queued for upcoming invoicing.

Using the Recurring Service Periods Page

The page does not show all schedules at once. You must select one specific schedule to load its periods.

Choosing a Schedule

Schedule dropdown: Pick from a list of recent active schedules. Each option is labeled with the client, contract line, cadence source, and billing timing so you can identify the right one quickly.
Schedule Key (paste): If you already have a schedule key from another tool, log entry, or support ticket, paste it directly into the Schedule Key field and click Open Schedule.

Once a schedule loads, the page shows the Recurring Obligation context block (client name, cadence source, billing timing, charge family, and the full schedule key) followed by summary tiles (Generated / Edited / Billed / Exceptions) and the table of service-period rows.

Available Operations

Open Schedule — Loads the selected or pasted schedule and renders its periods.
Repair Missing Service Periods — Materializes any service-period rows that the live schedule expects but that have not been persisted. Visible only when a repair is required.
Preview Regeneration — Shows what the schedule would look like if regenerated against a candidate set of records, including any conflicts with edited or billed rows. Preview only — applies no changes.

The "Repair Required" Banner

If you open a schedule that exists in live billing metadata but has no persisted service-period rows, the page displays a repair required state in place of the normal table. A warning panel explains that future rows will be materialized, billed history boundaries will be preserved, and the new records will be stamped with backfill provenance. Click Repair Missing Service Periods to run the repair.

Invoice Window Matching: The Combine Rule

Two contract lines can only land on the same invoice if their invoice windows match exactly. This is one of the most common reasons "I expected one invoice but got two."

Windows match — lines combine onto one invoice:

Line A: Client schedule, advance, March 1 to April 1
Line B: Contract anniversary, advance, March 1 to April 1

Even though their cadence sources differ, the resulting invoice windows are identical, so they combine.

Windows do not match — lines invoice separately:

Line A: March 1 to April 1
Line B: March 15 to April 15

Different windows produce different invoices, regardless of client, contract, or anything else.

If you are seeing more invoices than expected, check the invoice windows of each line on the Service Periods page first.

Troubleshooting Checklist

When a recurring charge is missing from Automatic Invoicing, walk this list in order:

Is the contract line active and saved?
Does the line have a billing frequency set?
Does the line have a cadence setting (client schedule or contract anniversary)?
Does the line have a billing timing (advance or arrears)?
Is the current date past the invoice window start for the period in question? (Remember: arrears windows open after the service period ends.)
Does a service period exist in generated state for that window? Skipped, superseded, and archived rows will not invoice.
Is there a repair required banner on the schedule? If so, run Repair Missing Service Periods before re-checking invoicing.
Has the period already been billed? A billed row is locked to a finalized invoice and will not produce another charge.

The fastest diagnostic path is almost always: confirm the contract line settings, then open Service Periods for that schedule, then check Automatic Invoicing.

Navigation