fuel-price/docs/superpowers/specs/2026-04-23-stripe-subscription-lifecycle-design.md

Stripe Subscription Lifecycle — Design Spec

Date: 2026-04-23 Status: Approved — ready for implementation plan

Purpose

Formalise the end-to-end Stripe subscription flow: signup, upgrade, downgrade, cancellation, renewal, payment failure recovery, and final downgrade. Covers webhook handling, email communication, user-facing flows, and minimal data-model additions on top of the existing Cashier + Plan + PlanFeatures foundation.

Existing working pieces (see docs/superpowers/specs/2026-04-15-tier-features-design.md) are kept as-is:

• Laravel Cashier, Plan model with resolveForUser() + cache
• PlanFeatures service (all entitlement decisions)
• RequiresFeature middleware
• DispatchUserNotificationJob using PlanFeatures
• BillingController (checkout + portal + success/cancel routes)
• Existing DowngradeUserOnSubscriptionDeleted listener (absorbed into the new consolidated handler below)

Decisions

Topic	Decision
Grace period length	5 days from first failed renewal charge
Retry strategy	Stripe-managed: 3 attempts on days 1, 3, 5; then cancel subscription
Features during grace	Stay ON until customer.subscription.deleted fires
Dunning emails	Hybrid — Stripe sends "update card" transactional; we send branded day-3 and day-5 reminders
Annual downgrade policy	Wait until renewal; no mid-term refunds
Subscription management UI	Stripe-hosted Customer Portal for everything (upgrade, downgrade, cancel, card update, invoices)
VAT / Stripe Tax	Skip for v1; revisit before £90k turnover
Post-grace reactivation	User returns via pricing page → Stripe Checkout (new subscription)

Webhook Event Catalogue

All Stripe events arrive via Cashier's auto-registered /stripe/webhook route and fire the Laravel\Cashier\Events\WebhookReceived event. A single consolidated listener HandleStripeWebhook routes on $event->payload['type']. The existing DowngradeUserOnSubscriptionDeleted listener is folded into it.

Event	Action
customer.subscription.created	Bust plan_for_user_{id} cache
customer.subscription.updated	Bust cache (catches portal plan swaps + past_due ↔ active transitions)
customer.subscription.deleted	Downgrade user to free, disable WhatsApp + SMS prefs, clear grace_period_until, bust cache
invoice.payment_succeeded	Clear grace_period_until, bust cache
invoice.payment_failed	Set grace_period_until = now + 5 days, queue day-3 and day-5 reminder mailables with ->delay()

Events not listed are ignored. invoice.upcoming is intentionally not handled — Stripe's default renewal-preview email covers it.

The listener is idempotent: every branch is safe to run twice on the same event (Cashier does not natively deduplicate webhooks, and Stripe retries failing deliveries). Cache busts are idempotent by nature; state writes use updateOrCreate / direct column updates that converge on the same result.

Feature Access During Grace

• When invoice.payment_failed fires, Stripe transitions the subscription to past_due. Cashier's $user->subscribed('plus') returns true for past_due subscriptions by default, so PlanFeatures::tier() already reports the paid tier. No code change needed.
• Features only turn off when customer.subscription.deleted fires — which happens after Stripe's 3rd failed retry (day 5). At that point the listener clears the Cashier subscription and the next PlanFeatures::for($user) call resolves to free.
• The dashboard renders a banner while $user->subscription()->pastDue() is true, linking to the Stripe Portal to update the card.

Data Model Additions

users table

Add one nullable column:

Column	Type	Purpose
grace_period_until	timestamp nullable	Drives the past-due banner + is used by reminder mailables as the cancellation check

Set when invoice.payment_failed fires (now()->addDays(5)). Cleared on invoice.payment_succeeded or customer.subscription.deleted.

No other schema changes. Stripe + Cashier tables remain the source of truth for subscription state.

User-Facing Flows

Flow	Path
Sign up (paid)	Pricing page → /billing/checkout/{tier}/{cadence} → Stripe Checkout → dashboard
Upgrade	Pricing page → "Manage subscription" → Stripe Portal → select higher plan → Stripe prorates immediately → webhook updates cache
Downgrade	Stripe Portal → select lower plan → Stripe schedules change at period end → webhook on change day fires customer.subscription.updated → features swap on period rollover
Cancel	Stripe Portal → cancel → cancel_at_period_end=true → features remain until period end → customer.subscription.deleted on that date
Update card	Stripe Portal, or via the "update payment method" link in Stripe's transactional dunning email
Reactivate after cancel / post-grace	Pricing page → Stripe Checkout (new subscription)

Email Communication

Stripe-sent (configure in Stripe dashboard)

• Successful payment receipts
• Failed payment "update your card" — includes hosted update link
• Upcoming renewal reminder (default 7 days pre-renewal)

FuelAlert-sent (our Laravel Mailables)

Name	Triggered by	Delay	Subject
PaymentFailedDay3Reminder	invoice.payment_failed webhook	now + 3 days	"Heads up — your FuelAlert payment is retrying"
PaymentFailedDay5Reminder	Same	now + 5 days	"Last chance — {Tier} features end tomorrow"

Both mailables check $this->user->grace_period_until === null in build() / content() and abort silently if the grace period has already been cleared (payment recovered or subscription cancelled). This is simpler than cancelling queued jobs.

Copy references the user's current tier by name, spells out which features they'll lose on downgrade, and links to the Stripe Portal to update the card.

Stripe Dashboard Configuration (one-time, manual)

1. Billing → Automations → Subscription retry rules:
   • Switch from "Smart Retries" to Custom
   • Retry schedule: day 1, day 3, day 5 after first failure
   • After final retry: Cancel subscription
2. Emails → Customer emails:
   • Enable: "Successful payments", "Failed payments", "Upcoming renewals"
3. Settings → Branding:
   • Upload FuelAlert logo
   • Set primary colour to match app accent
4. Customer Portal settings:
   • Allow plan changes (all 3 paid tiers × monthly + annual)
   • Allow cancellation (at period end only)
   • Allow payment method updates, invoice history
   • Hide everything else (no custom domains, no promo code input — keep promotion codes to checkout only)

Architecture

Stripe
  │
  │ webhook POST /stripe/webhook
  ▼
CashierController (built-in)
  │
  │ dispatches WebhookReceived event
  ▼
HandleStripeWebhook (new consolidated listener)
  │
  ├── subscription.created/updated → cache bust
  ├── subscription.deleted         → downgrade + disable prefs + cache bust
  ├── invoice.payment_succeeded    → clear grace_period_until + cache bust
  └── invoice.payment_failed       → set grace_period_until + queue reminder mails
                                       │
                                       ├─► PaymentFailedDay3Reminder (delay 3d)
                                       └─► PaymentFailedDay5Reminder (delay 5d)
                                              │
                                              └─ guard: abort if grace_period_until is null

Testing Strategy

Pest feature tests, one file per webhook branch, using Cashier's webhook-test helpers (simulate WebhookReceived with a representative payload).

Required test cases:

• customer.subscription.created busts the plan cache
• customer.subscription.updated busts the plan cache after a portal plan swap
• customer.subscription.deleted downgrades to free, disables WhatsApp + SMS prefs, clears grace_period_until (this folds in the existing DowngradeUserOnSubscriptionDeletedTest)
• invoice.payment_failed sets grace_period_until 5 days out and queues both reminder mailables with correct delays (use Queue::fake())
• invoice.payment_succeeded clears grace_period_until
• PaymentFailedDay3Reminder aborts when grace_period_until is null
• PaymentFailedDay5Reminder aborts when grace_period_until is null
• Listener is idempotent — replaying the same event twice produces the same final state
• Existing BillingControllerTest + PlanFeaturesTest continue to pass

Manual QA checklist (production Stripe test mode):

• Sign up on all three paid tiers × both cadences
• Upgrade basic-monthly → pro-monthly via Portal; confirm instant swap
• Downgrade pro-monthly → basic-monthly via Portal; confirm change takes effect at next renewal
• Cancel mid-period; confirm features persist until period end
• Trigger payment failure with test card 4000 0000 0000 0341; confirm banner appears, day-3 + day-5 emails send, subscription cancels on day 5, user downgrades to free

Out of Scope (v1)

• Stripe Tax / VAT — revisit before £90k turnover
• Mid-term annual refunds — commitment model, no refunds
• Custom in-app upgrade/downgrade UI — Stripe Portal is the UI
• Trial periods — none offered
• invoice.upcoming handling — Stripe's default email is sufficient
• Subscription pause / skip-a-month — not in tier spec
• Multi-currency — GBP only for v1

Open Documentation Updates

The following project docs need editing to match this spec (done as part of implementation, not a separate task):

• .claude/rules/payments.md — current version doesn't mention grace period, webhook catalogue, or decision to use Stripe Portal exclusively. Describes a custom Livewire upgrade UI that is no longer planned.
• .claude/rules/tiers.md — largely accurate; check the "Notification Dispatch Flow" section doesn't contradict any webhook behaviour here.