Feature: Settings → Billing & Plan page (FEAT-104)

Metadata

• Issue ID: FEAT-104
• Status: Done (PR open against dev)
• Owner: beansint
• Related issues: #104
• Builds on: FEAT-31 (cookie auth), FEAT-39 (Stripe + webhooks — the foundation this issue extends), FEAT-40, FEAT-103 Phase 1 (settings shell + useSubscription() provider).

---

Overview

Replaces the <ComingSoon /> placeholder at /settings/billing with the full read + lifecycle surface every modern subscription product ships:

• R1 Current plan card — plan name + price, status pill (active | past_due | canceled | paused | ending), renewal copy, "Manage subscription" via Stripe portal, inline past-due and paused sub-banners.
• R2 Plan comparison — 3-card grid (Free / Pro / Plus) with "Current" badge, mobile-friendly horizontal scroll, in-app upgrade/downgrade CTAs that route through proration preview + confirmation dialogs.
• R3 Payment method — <brand> •••• <last4> · exp mm/yy with "Update" → Stripe portal. Empty state for Free / never-charged users.
• R4 Invoices — last 12 invoices; each row links to Stripe's hosted_invoice_url (built-in email + PDF download).
• R5 Cancel plan link — subtle text link routing to the Stripe portal for the destructive cancel flow.
• W1 Auto-renew toggle — <Switch> on the Current plan card. Flips cancel_at_period_end in Stripe; UI updates to "Plan ends on …" copy.
• W2 In-app plan switching with proration — <Dialog> with live previewProration number from Stripe; on confirm calls changePlan.
• W4 Pause subscription — 1-cycle fixed pause via pause_collection.resumes_at. Resume button on the inline paused banner.
• W5 Global past-due dunning banner — sticky red banner across every features page when status === 'past_due'. Dismissable per-session. Message and CTA are conditional: if requiresPaymentAction=true (3DS pending), shows "Your payment requires additional verification (3D Secure) — please complete the authentication to keep access." with a "Complete verification" CTA; otherwise shows "We couldn't charge your card — update your payment method to keep access." with an "Update card" CTA. Both CTAs open the Stripe Billing Portal.
• W6 Receipt access — invoice rows open Stripe's hosted_invoice_url (email + download natively). No per-row "Email me" button — Stripe has no clean API to resend a paid invoice receipt, and the hosted page already covers it.
• W7 Post-upgrade confirmation banner — 5-second auto-dismissing banner when URL has ?upgraded=<plan_slug> (set by createCheckoutSessionForUser's success_url).

Out of scope (deferred to a later issue):

• W3 Trial conversion — per product review, the free trial is descoped from FEAT-104 and will ship as its own change. No has_used_trial column, no start-trial endpoint, no trial_will_end webhook handler.
• W6 per-row email button — Stripe does not expose a clean API to re-send a paid invoice receipt; the hosted invoice page already covers it.

The entire feature layers on top of the existing BillingService pipeline at backend/src/billing/billing.service.ts — no new Stripe client, no parallel cache, no duplicate webhook dispatcher. Every mutation resyncs via the existing syncSubscriptionFromStripe so the local DB row matches Stripe before the controller returns; webhooks remain authoritative.

---

Frontend Behavior

Routes

Components

Subscription provider additions

frontend/components/providers/subscription-provider.tsx gains:

• New state field: pauseCollectionResumesAt: string | null
• New context methods: toggleAutoRenew, previewProration, changePlan, pauseSubscription, resumeSubscription, fetchPaymentMethod, fetchInvoices
• All mutations return the refreshed getMySubscriptionView shape and call setState(parseStateFromPayload(data)) so a single PATCH/POST response replaces local state — no double round-trip.

Strict edge policy (D6)

Disabled CTAs render with aria-disabled + a title tooltip explaining why ("Resolve payment first").

Loading / empty / error states

Mobile layout (375px viewport)

• All sections stack vertically.
• The plan-comparison grid becomes a horizontal scroll strip (flex overflow-x-auto snap-x), each card minimum 16rem wide.
• Dunning banner and UpgradeBanner sit above the FeatureHeader and don't push content into a broken state (per QA-25).

---

Backend Behavior

New endpoints

All on SubscriptionsController under @UseGuards(CookieAuthGuard). All mutations return the refreshed getMySubscriptionView shape.

Webhook dispatcher additions

In processStripeEvent the existing switch picks up two new cases:

customer.subscription.updated, invoice.payment_succeeded, invoice.payment_failed, and invoice.payment_action_required were already handled by FEAT-39 — no changes there.

Pre-condition guards (D6)

setAutoRenew, changePlan, pauseSubscription throw BadRequestException when the local row's status !== 'active'. The only allowed flow on a non-active sub is setAutoRenew(true) to revert an end-of-period cancel.

getMySubscriptionView extension

The shape now includes pauseCollectionResumesAt: string | null so the provider can render the inline paused banner without an extra round-trip.

Checkout success URL — W7 wiring

createCheckoutSessionForUser now appends &upgraded=<plan_slug> to whatever STRIPE_CHECKOUT_SUCCESS_URL is configured to. Recommended success URL: ${FRONTEND_URL}/settings/billing so the new UpgradeBanner mounts on the features layout right next to the new R1 card.

Data model

ALTER TABLE user_subscriptions
  ADD COLUMN IF NOT EXISTS pause_collection_resumes_at TIMESTAMP NULL;

Migration: backend/prisma/migrations/202605190001_add_subscription_pause_field/migration.sql. Nullable, no FK — safe to drop on revert.

Catalog seeding (one-time ops)

Stripe test mode and the v2 Neon branch ship with the Free plan only. FEAT-104 seeds Pro + Plus during the PR:

See Notes → How to add or re-price a plan below for the live-mode runbook.

Failure modes

---

QA Test Scenarios

---

Edge Cases

• No Stripe customer record (Free tier, never checked out) — both payment-method and invoices endpoints return null / [] without calling Stripe. UI shows empty states.
• Stripe outage on read endpoints — graceful "Couldn't load …" copy with Retry; page still renders.
• Invoice with null hosted_invoice_url` — row is non-clickable (no broken anchor).
• Different currency — invoice rows format via Intl.NumberFormat(currency); no hardcoded $.
• Localised renewal date — uses the browser's toLocaleDateString(), not en-US.
• Concurrent change-plan + webhook — webhook is authoritative; stripe_updated_at ensures the latest Stripe state wins.
• customer.subscription.updated after invoice.payment_action_required — Stripe often fires both events for the same payment attempt. syncSubscriptionFromStripe preserves the existing status_reason when the incoming value is null and the new local status is not active, so payment_action_required is not silently overwritten. The dunning banner continues to show the 3DS message rather than reverting to the generic payment-failure copy.
• Pause + auto-renew off attempted together — the W1 toggle is hidden during pause and the pause link is hidden when cancel_at_period_end=true, preventing the dual state by construction.
• Server-side retry of change-plan — idempotent in Stripe via the 1-minute idempotency-key window.
• User signs in mid-billing-cycle on a past_due sub — DunningBanner appears on first navigation to any features page even if /settings/billing hasn't been opened yet.
• Plan price changes upstream — admin updates subscription_plan_prices.stripe_price_id per the runbook below; new subscriptions land on the new price, existing subs keep theirs until they switch.

---

Notes

How to add or re-price a plan (admin runbook)

Stripe Price objects are immutable — you don't edit them, you create a new one and archive the old one. The DB row in subscription_plan_prices is the link.

1. Create a new Stripe price for an existing product:

   stripe prices create --product=prod_XXX --unit-amount=1500 --currency=usd --recurring="interval=month"
   # → price_NEW_ID
   

2. Update the DB:

   UPDATE subscription_plan_prices
     SET stripe_price_id = 'price_NEW_ID', price = 15.00
     WHERE plan_slug = 'pro' AND billing_interval = 'month';
   

3. Archive the old Stripe price (Dashboard → Products → Pro → Prices → ⋯ → Archive).
4. Existing customers stay on their old price until they switch plans (via in-app upgrade/downgrade) — this is intentional and matches Notion/Vercel-style price grandfathering.

To change Pro/Plus credit caps, see credits-subscription-plan.md.

Stripe Dashboard receipt setting (one-time ops)

The "Email me this receipt" expectation is satisfied by Stripe Dashboard's Settings → Customer emails → Successful payments / Refunds. Enable once per account so every successful charge auto-emails a receipt. The invoice row in R4 also opens Stripe's hosted invoice page where users can self-serve another copy.

Webhook events needing forwarding for local dev

stripe listen --forward-to localhost:3001/billing/stripe/webhook \
  --events customer.subscription.updated,customer.subscription.paused,customer.subscription.resumed,invoice.payment_succeeded,invoice.payment_failed,invoice.payment_action_required,checkout.session.completed,customer.subscription.deleted

Feature flags

None — FEAT-104 ships behind no flag. The strict-guard policy is the gating mechanism (operations on non-active subs throw BadRequestException).

Known limitations

• Annual billing intervals are not exposed in the UI; the schema column exists for future use.
• Free trials are descoped from this issue and will ship as a separate change.
• The proration preview calls POST /v1/invoices/create_preview (form-encoded). The deprecated GET /v1/invoices/upcoming was replaced in #137 because the old endpoint was removed from the Stripe API after 2024-09-30.