The Stripe subscription lifecycle

Why the estimate is always wrong

Checkout is a day. Cancel is an afternoon. Both are well documented and both work first time.

Then somebody upgrades mid-cycle, and you discover that proration is a set of decisions rather than a feature, that the invoice generated is not the one your finance person expected, and that your own database now has a plan on it that doesn't match what Stripe thinks.

Here is the full list, so it can go in the estimate rather than into month two.

The state changes

Mid-cycle upgrade. Stripe will prorate by default, generating a credit for the unused portion of the old plan and a charge for the remainder of the new one. Decide deliberately whether you want that, whether the difference is charged immediately or added to the next invoice, and what the customer sees. All three are configurable and all three surprise somebody.

Downgrade. Almost always should take effect at period end, not immediately, because immediate downgrades generate credits and awkward conversations. That means holding a pending plan change in your own system and applying it when the period rolls, which is state you have to store and reconcile.

Cancellation. At period end or immediately, and they behave differently. Also: what happens to their data, whether they can reactivate, and whether reactivating restores the old price or the current one. That last question is usually answered by accident.

Pause. Supported, rarely scoped, and worth deciding about before a customer asks.

Quantity changes on seat-based plans. Same proration questions as an upgrade, arriving more often, usually from an API call rather than a checkout page.

The money that doesn't arrive

Failed charges. Cards expire, get replaced, and get declined for reasons the customer doesn't know about. Stripe retries on a schedule you configure. Your system needs to know what state the subscription is in during those retries, and what the customer can still do.

Dunning. The sequence of emails, the grace period, and the point at which access is withdrawn. This is a commercial decision that arrives as an engineering ticket, and the default is rarely what the business wants.

Involuntary churn. A meaningful share of cancellations are cards failing rather than customers deciding. Whether you handle that well is a revenue question, and it's entirely in this part of the integration.

The webhook problems

Out of order delivery. Webhooks are not guaranteed to arrive in the order the events happened. You can receive customer.subscription.updated before the invoice.paid that caused it. Any logic that assumes sequence will be wrong intermittently, which is the worst way to be wrong.

The fix is to treat webhooks as notifications rather than as data, and to fetch current state from the API when handling one. Slower, and correct.

Duplicate delivery. The same event will sometimes arrive twice. Every handler needs to be idempotent, keyed on the event ID, with a record of what's been processed. Without this you will eventually double-apply a credit or send a receipt twice.

Retries after your endpoint fails. If your handler throws, Stripe retries with backoff for up to three days. That's helpful, and it means a bug deployed on Friday produces a burst of retried events on Monday.

The reconciliation problem

At some point your database and Stripe will disagree. A webhook was missed, a deploy dropped requests, or somebody changed something in the dashboard by hand.

The systems that survive this have a scheduled reconciliation: fetch subscriptions from Stripe, compare against local state, log the differences, and either correct them automatically or raise them. Without it, the disagreement is silent and grows.

Treat Stripe as the source of truth for billing state and your database as a cache of it. That one decision, made early, resolves most of the ambiguity in the rest of the integration.

What to actually scope

Checkout and cancel are a week. The list above is four to six, depending on whether you're seat-based and how much dunning the business wants.

That's not a padded estimate. It's the difference between a subscription that works and one that works until somebody upgrades.