A Subscription Doesn't Have One Status: Map Billing as Four State Machines

The short answer: a subscription business should track at least four separate histories: the commercial subscription, the invoice, each payment attempt, and the product entitlement. A failed payment changes a payment attempt. It does not, by itself, prove that the subscription is canceled or that access should be revoked.

That separation sounds academic until an asynchronous debit is still processing, an invoice is open, the subscription record says active, and the customer can still use the product. Those facts can all be true at once. The system becomes dangerous only when one overloaded field—often called status—is asked to stand in for all four.

The map answers one operational question

When support asks, “Is this customer active?”, which fact do they actually need?

• Commercial: Does an agreement exist, and will it renew?
• Billing: What amount is currently documented as due?
• Payment: What happened to the latest collection attempt?
• Product: What may the customer use right now?

The answer can differ by lane. Stripe's public subscription documentation makes the boundary unusually visible: it notes that an active subscription does not mean every associated invoice is paid, and that some asynchronous methods can leave a subscription active while the payment is still processing. Paddle likewise documents subscription status separately from the related transaction it creates when a subscription bills.

These are provider examples, not a universal vocabulary. The reusable principle is the separation of claims.

Lane 1: the subscription records the agreement

The subscription lane should answer what the customer agreed to buy and what the business intends to bill next. Typical facts include:

• customer, product, price, quantity, and currency;
• trial start and end;
• billing cadence and next billing time;
• pause, resume, upgrade, downgrade, or cancellation schedule;
• the effective time of a pending change.

A scheduled cancellation is especially important. The customer may remain active until the end of a paid period even though the future cancellation is already known. Replacing that pair of facts with status = canceled either removes access too early or loses the future change.

Keep current state and scheduled change as different records. Paddle's subscription API does this explicitly: an active subscription can carry a future cancel, pause, or resume action, and its status changes only when that action takes effect.

Lane 2: the invoice records the amount due

An invoice is a financial document, not a synonym for the subscription. It can contain line items, tax, credits, proration, discounts, balance adjustments, due dates, and a collection method. Its lifecycle commonly includes states such as draft, open, paid, void, or uncollectible.

One subscription can produce many invoices. One invoice can remain open while the subscription continues. A credit or void can close an invoice without proving that money moved. For reporting and support, retain the exact invoice outcome instead of converting every closure into “paid.”

The crucial relationship is:

subscription reaches billing boundary
  → billing engine calculates the period
  → invoice records what is due
  → collection policy decides how to seek payment

That sequence lets a team audit pricing separately from authorization. If the amount is wrong, the defect began before the card network ever saw the request.

Lane 3: every payment attempt has its own outcome

A payment attempt answers a narrow question: what happened when this amount, payment method, merchant context, and processor path were submitted at this time?

Useful attempt states include processing, customer action required, declined, succeeded, and unknown. “Unknown” deserves first-class treatment. A timeout can hide either an approval or a rejection. Retrying blindly can create a duplicate charge; marking it failed can leave a paid invoice open. Reconcile the provider object or event stream before issuing another attempt.

An invoice may have several attempts because the customer updates a card, authentication is completed later, a retry runs on another day, or an orchestration policy chooses another processor path. Preserve each attempt rather than overwriting the first failure with the final success. The history is what lets risk, finance, and support explain the result.

Lane 4: entitlement is a product policy

Entitlement means what the application allows the customer to do: full access, a grace period, limited access, or revocation. It should be driven by an explicit policy, not by whichever webhook happened to arrive last.

A policy might say:

initial invoice paid        → grant full access
renewal payment processing → preserve access until settlement deadline
retryable decline          → enter 7-day grace period
payment method replaced    → retry collection, keep grace state
subscription ends          → revoke at effective end time
fraud or account action    → send to a separate risk policy

The exact rules belong to the merchant. Provider status names cannot decide how much grace a SaaS product promises, which features remain available, or when an enterprise contract permits suspension.

This is also why webhook handlers should not contain scattered one-off access decisions. Record the incoming fact, then apply one versioned entitlement policy. Replaying the same event should produce the same state.

Use events to connect lanes without merging them

The four lanes still need relationships. Model those as events with identity and time:

For every cross-lane change, store the source object, event ID, observed time, and policy version. That makes duplicate delivery safe and delayed delivery explainable.

A provider migration is a state-mapping exercise

Moving payment processors is not just exporting customers and tokens. The migration must preserve the commercial agreement, unresolved invoices, attempt history needed for reconciliation, and the application's current entitlement decision.

Start with a mapping table:

1. Define the canonical claim made by every source field.
2. Mark provider-specific states that have no exact destination.
3. Preserve pending actions and future effective times.
4. Reconcile open money movement before cutover.
5. Test access decisions using snapshots from normal, grace, paused, and canceled cases.

If a team wants billing state to remain independent from any single connected processor, Clink's subscription billing layer is one implementation option: its public product page groups subscription management, recurring invoices, customer self-service, and payment-method updates in one billing surface. That product page establishes Clink's offered workflow, not a universal billing standard, and there is no claimed native MyMap–Clink integration here.

For an architecture review, you can adapt this four-lane model in MyMap's concept map maker. Replace the illustrative state names with the exact objects and events from your providers, then label every edge with the code path or policy that implements it.

What the sources confirm—and what this map derives

Provider documentation confirms that subscription, invoice or transaction, and payment lifecycles are distinct and can temporarily hold different states. It also confirms that a future scheduled change can coexist with a currently active subscription.

MyMap derives the four-lane audit model and the rule that entitlement belongs behind a separate merchant policy gate. Those are architecture recommendations designed to prevent ambiguous state, not terms mandated by Stripe, Paddle, or Clink.

Still product-specific: state names, event ordering, retry behavior, tax handling, settlement timing, grace periods, cancellation rights, and the meaning of access. Validate each against the current provider contract and the merchant's customer agreement.

Cite this article

Use this article for the four-lane relationship map. Cite the relevant provider documentation for its exact object names and transitions. If you reuse the visual, preserve the boundary between payment outcome and product access; removing it recreates the ambiguity the map is meant to solve.