All templates
State template
Subscription downgrade lifecycle
State transitions when a user downgrades from paid to free plan.
A user on a paid plan says "I want to downgrade." Simple action, complex business logic. Do they lose access to premium features immediately or at the end of the billing cycle? Can they change their mind? What happens to data they created with a premium feature? This state machine maps the journey: from "Pro" through a grace period where they can back out, to either "Free" (feature-limited) or "Immediately_Free" (if they force it), with the option to upgrade again anytime.
Unlike the subscription lifecycle (which shows free → pro → churn), this diagram focuses on what happens when someone intentionally downgrades — the most customer-impacting flow because you're about to remove features they may rely on.
When to use this template
- Building the downgrade flow — before coding, clarify: grace period or immediate? Refund prorated overages? Lock data read-only or delete? Align product, support, and billing.
- Customer support training — explain to support what states users pass through and what actions trigger each transition. Helps them advise customers accurately.
- Compliance documentation — financial auditors often ask "what happens to a user's data when they leave?" This diagram is the answer.
How to adapt it
Common variations to model your own downgrade policy:
- Different grace periods by plan — if yearly subscribers get a 30-day cancellation window but monthly subscribers get none, add branching: "Downgrade_Requested → [Monthly: Immediately_Free, Yearly: Grace_Period_30_Days]".
- Tiered downgrades — if you have Free/Pro/Enterprise, add intermediate states for "Pro_to_Mid" and "Mid_to_Free" so you can upsell instead of downgrading all the way.
- Dunning (payment failure) — add a state "Payment_Failed" that downgrades automatically if payment isn't retried successfully. Link back to "Pro" on successful retry.
- Suspension before deletion — add "Suspended" state between downgrade and deletion, where read-only access persists for 90 days before purge. Recoverable if they re-upgrade.
Mermaid code
Copy it anywhere Mermaid is supported — GitHub, Notion, or your docs.
stateDiagram-v2
[*] --> Pro
Pro --> Downgrade_Requested: User selects downgrade
Downgrade_Requested --> Grace_Period: Downgrade scheduled for period end
Grace_Period --> Pro: User cancels downgrade
Grace_Period --> Free_Pending: Period end reached
Free_Pending --> Free: Premium features disabled
Pro --> Immediately_Free: User force-downgrades now
Free --> Pro: User upgrades again
Free --> [*]: Account deleted
Immediately_Free --> Pro: User upgrades again
Immediately_Free --> [*]: Account deleted
Grace_Period --> [*]: Account deleted
Frequently asked questions
- Why do we need a grace period between downgrade request and downgrade execution?
- A grace period (usually until the end of the current billing cycle) gives users time to reconsider and prevents accidental downgrades due to misclicks. It also lets your product ask 'why are you leaving?' and offer discounts or feature customization. Without a grace period, users downgrade, realize they need pro features, and upgrade again — noisy churn. A grace period smooths the experience.
- What happens to a user's premium data when they downgrade (e.g., private diagrams, team workspaces)?
- This diagram doesn't show data handling; add your own rules. Common patterns: (1) Convert to read-only for 30 days — user can export but not edit. (2) Immediately delete (harsh). (3) Downgrade access (private diagrams → read-only, team workspaces → personal only). Decide this before building downgrade logic, because angry users who lose work will churn forever.
- Can a user downgrade to free if they have a yearly subscription?
- Usually not immediately — yearly subscriptions are committed. Show an 'upgrade/cancel' path instead: cancel the yearly subscription (losing prorated credit or paying a cancellation fee per your terms), then downgrade. Or let them downgrade at the next renewal. The state machine shows 'immediately free' but link it to your refund/credit policy.
- How do I know if a downgrade attempt is a pricing issue or a product issue?
- Send a survey in the 'Downgrade_Requested' state: 'Why are you downgrading?' with options like 'Too expensive', 'Don't need pro features', 'Switching products', 'Disappointed with X'. Answers tell you whether to improve product fit, adjust pricing, or create a mid-tier plan. Track conversion rates from survey → cancel-downgrade, and invest in the highest leverage fix.