Operating subscription billing
Recurring billing is a state machine connected to money, access, tax, support, and accounting. The recurring charge is only one transition.
The short version.
- Subscription state, invoice state, payment state, and product entitlement should be related but not treated as one field.
- Upgrades, downgrades, pauses, trials, credits, and cancellations require explicit timing and proration rules.
- A billing provider can automate workflows, but the business still needs a product-access and customer-communication policy.
Separate the four state machines
A subscription describes the commercial schedule. An invoice describes an amount due. A payment describes collection. An entitlement describes product access. One can change without all the others changing at the same instant.
Store provider IDs, internal customer and account IDs, plan and price version, billing period, collection method, cancellation intent, and entitlement decision. Avoid driving the entire product from one provider status string.
Version prices instead of overwriting history
Existing customers may remain on legacy prices while new customers receive a new offer. Preserve the original price, currency, interval, tax behavior, quantity logic, discounts, and promised terms.
A migration or catalog cleanup should not silently reprice active customers. Map legacy plans explicitly and decide whether each cohort is grandfathered, migrated with consent, or renewed on new terms.
Define change timing
An upgrade can apply immediately, on the next invoice, or at renewal. A downgrade can remove access immediately or at period end. Proration can create a charge, credit, or no adjustment. Annual-to-monthly changes can affect revenue recognition and refund expectations.
Preview changes before applying them and show the customer the date, amount, credit, tax, and access effect. Pending changes can protect against granting an upgrade when its invoice fails.
Design failed-payment recovery
A failed renewal can trigger retries, payment-method updates, emails, grace access, restricted access, cancellation, or collections. The right sequence depends on product value, fraud risk, support load, and local requirements.
Track recovery by reason and cohort. Too many retries can add cost and customer frustration; too few can create involuntary churn.
Make cancellation and reactivation coherent
Support immediate cancellation, end-of-period cancellation, refunds, pauses, and reactivation as explicit policies. Preserve the audit trail even when the subscription becomes inactive.
The customer portal, support tooling, provider API, webhook handlers, and product UI must agree. Test each path with tax, discounts, seats, usage, and pending invoices rather than only a simple monthly plan.
Decision checklist.
- Document subscription, invoice, payment, and entitlement states separately.
- Preserve legacy prices and customer promises.
- Define proration and timing for every plan change.
- Write the retry, grace, suspension, and cancellation sequence.
- Test changes through the customer portal, support tools, API, and webhooks.
How this shows up in real businesses.
These are anecdotes and first-party accounts, not policy evidence. Use them to discover questions worth verifying.
Operators compare no-refund policies, proportional refunds, goodwill exceptions, annual-plan timing, support cost, reputational risk, and the possibility that rejected requests become chargebacks.
Community policy examples may be legally unsuitable for another product, country, customer type, or contract.engineering blog · provider authoredPaddle describes migrating more than a million subscriptionsPaddle's engineering team explains how an initially manual migration process evolved into self-service workflows across incompatible billing architectures and a large subscription population.
This is provider-authored engineering material about Paddle's own migration and highlights its chosen framing and success metrics.engineering blog · provider authoredPaddle explains rebuilding its billing platform around new primitivesThe engineering narrative shows how platform object models, APIs, subscriptions, developer experience, and legacy compatibility can become long-term architectural constraints for both provider and customer.
This is Paddle's account of its own product evolution and should be read alongside current documentation and customer experience.Review the evidence.
- Stripe subscription changes and prorationsReviewed 2026-07-27
- Stripe subscription migration stagesReviewed 2026-07-27