Reconciliation as a Product Feature
Modern billing systems are inherently distributed.
A customer completes checkout. Stripe creates a subscription. Webhooks are delivered asynchronously. Invoices are finalized later. Payments may succeed, fail, retry, or require customer action. Internal systems consume events, project state, update entitlements, and generate operational records.
Every step in this process happens independently.
As Stripe's subscription and webhook documentation makes clear, billing state is event-driven and asynchronous by design. Systems must be built to handle delayed events, retries, temporary failures, and eventual consistency.
Because of this, reconciliation should not be treated as a hidden maintenance task.
It should be a visible product capability.
Drift Is Not a Failure
One of the most common misconceptions in SaaS billing is that drift indicates a broken system.
In reality, drift is a normal consequence of distributed architectures.
Examples include:
- A webhook delivery is delayed.
- An internal projection job fails.
- A subscription update arrives out of order.
- An invoice is finalized before downstream processing completes.
- A payment retry succeeds after an initial failure.
- An entitlement projection does not update correctly.
In each case, Stripe remains correct, but internal systems may temporarily diverge from Stripe's state.
The goal is not to eliminate every possibility of drift.
The goal is to detect it, explain it, and recover safely.
Stripe as the Source of Truth
LedgerBill follows a simple principle:
Stripe owns billing truth.
Stripe determines:
- Customer state
- Subscription state
- Invoice state
- Payment state
- Renewal state
LedgerBill continuously compares its internal projections against Stripe's authoritative records.
When differences are detected, those differences become reconciliation findings.
This creates a deterministic process for identifying and repairing inconsistencies before they impact customers or revenue operations.
Reconciliation Should Be Visible
Many systems hide reconciliation behind background jobs and internal dashboards.
The result is that billing inconsistencies become operational mysteries.
Instead, reconciliation findings should be surfaced directly within the product.
Operators should immediately understand:
- What is wrong
- Which organization is affected
- Which Stripe object is involved
- Which internal projection differs
- How severe the issue is
- What actions are available
A reconciliation system should transform billing inconsistencies into manageable workflows.
What a Good Reconciliation Finding Contains
Every finding should provide enough information for an operator to understand and resolve the issue without additional investigation.
This includes:
Stripe State
The current authoritative state retrieved from Stripe.
Internal State
The state currently projected within LedgerBill.
Severity
An indication of operational impact.
For example:
- Informational
- Warning
- High
- Critical
Repair Metadata
Context about how the finding can be resolved.
Resolution Actions
Operators should be able to:
- Replay events
- Requeue processing
- Recompute projections
- Ignore expected differences
- Mark findings as resolved
The objective is not simply to identify drift.
The objective is to provide a safe path to recovery.
Why Lineage Matters
Detecting drift answers one question:
What is wrong?
Lineage answers a different question:
How did we get here?
These are not the same problem.
A reconciliation finding may indicate that an invoice projection differs from Stripe.
That explains the current inconsistency.
It does not explain why the inconsistency occurred.
Understanding causality requires lineage.
Building an Audit Trail of Decisions
A production billing platform should preserve the sequence of events that created the current state.
This includes:
- Stripe webhook events
- Canonical billing events
- Projection updates
- Replay operations
- Entitlement changes
- Invoice lifecycle events
- Administrative actions
- Repair operations
Together, these records create a complete operational history.
When a discrepancy occurs, teams can follow the chain of events that produced it.
Reconciliation and Lineage Work Together
Reconciliation and lineage solve different but complementary problems.
Reconciliation
Identifies differences between Stripe and internal projections.
It answers:
What does not match?
Lineage
Explains how the current state was produced.
It answers:
Why does this state exist?
A mature billing platform requires both.
Without reconciliation, inconsistencies remain hidden.
Without lineage, inconsistencies remain unexplained.
Operational Confidence at Scale
As organizations grow, billing systems become increasingly complex.
Subscriptions change.
Invoices are generated.
Usage is reported.
Entitlements evolve.
Webhooks are retried.
Background jobs fail and recover.
The question is no longer whether inconsistencies will occur.
The question is whether teams have the tools to understand and manage them.
That is why reconciliation should be treated as a core product feature rather than a background process.
Stripe provides the billing truth.
Reconciliation identifies where projections diverge from that truth.
Lineage explains how those divergences occurred.
Together, they create a billing platform that is observable, auditable, and operationally trustworthy.