Subscription Lifecycle¶

Models the lifecycle of a customer Subscription from creation and activation through recurring renewal cycles, optional pause, and eventual cancellation or expiry. Covers trial periods, payment failures, and win-back flows.

Object: subscription · States: 6 · Transitions: 11

State Diagram¶

flowchart LR

    %% ── classDef palette ─────────────────────────────────────
    classDef stInit  fill:#0d9488,stroke:#0f766e,color:#fff,font-weight:bold
    classDef stNorm  fill:#3b82f6,stroke:#2563eb,color:#fff
    classDef stOk    fill:#16a34a,stroke:#15803d,color:#fff,font-weight:bold
    classDef stFail  fill:#dc2626,stroke:#b91c1c,color:#fff,font-weight:bold
    classDef stHold  fill:#d97706,stroke:#b45309,color:#fff

    %% ── nodes ───────────────────────────────────────────────
    trialing(["Trialing"])
    active["Active"]
    past_due["Past Due"]
    paused>"Paused"]
    cancelled[["Cancelled"]]
    expired[["Expired"]]

    %% ── transitions ─────────────────────────────────
    trialing -->|"subscription-activated"| active
    trialing -->|"subscription-cancelled"| cancelled
    active -->|"subscription-renewed"| active
    active -->|"subscription-renewed"| past_due
    past_due -->|"subscription-activated"| active
    past_due -->|"subscription-expired"| expired
    active -->|"subscription-paused"| paused
    paused -->|"subscription-activated"| active
    active -->|"subscription-cancelled"| cancelled
    paused -->|"subscription-cancelled"| cancelled
    active -->|"subscription-expired"| expired

    %% ── class assignments ───────────────────────────
    class trialing stInit
    class active,past_due stNorm
    class paused stHold
    class cancelled,expired stFail

States¶

State	Label	Description	Initial	Terminal
`trialing`	Trialing	Free trial period. Access granted. No payment yet charged.	✓
`active`	Active	Subscription live and paid. Customer has full access. Auto-renewal scheduled.
`past-due`	Past Due	Renewal payment failed. Grace period active. Customer retains access temporarily.
`paused`	Paused	Subscription intentionally suspended by customer. Access restricted. Billing halted.
`cancelled`	Cancelled	Subscription terminated. Access ends at period end or immediately per policy.		✓
`expired`	Expired	Subscription reached its end date without renewal. Access revoked.		✓

Transitions¶

From	To	Trigger	Guards
`trialing`	`active`	`subscription-activated`	Trial period elapsed; Payment method charged successfully
`trialing`	`cancelled`	`subscription-cancelled`	Customer cancels before trial ends OR trial payment fails with no retry
`active`	`active`	`subscription-renewed`	Renewal payment successful; Subscription not cancelled
`active`	`past-due`	`subscription-renewed`	Renewal payment declined
`past-due`	`active`	`subscription-activated`	Retry payment successful OR customer updates payment method
`past-due`	`expired`	`subscription-expired`	Grace period elapsed with no successful payment
`active`	`paused`	`subscription-paused`	Customer requests pause; Pause permitted by plan terms
`paused`	`active`	`subscription-activated`	Customer resumes OR pause period ends automatically
`active`	`cancelled`	`subscription-cancelled`	Customer or admin cancels
`paused`	`cancelled`	`subscription-cancelled`	Customer cancels while paused
`active`	`expired`	`subscription-expired`	Fixed-term subscription reaches end date without renewal option