Momento/docs/story-3.7-billing-ux.md

Story 3.7: Billing & Subscription UX — Complete User Journey

Epic: 3 — The SaaS Commercial Engine Priority: High Status: ready-for-dev Depends on: 3.1 (quota tracking), 3.6 (Stripe tiers) Blocks: 4.3 (data portability export needs billing status)

---

Context

The backend billing infrastructure (Stripe checkout, webhook sync, quota tracking via Redis) is fully implemented. The base UI components exist:

• billing-plans.tsx — Plan selection cards + Stripe embedded checkout
• usage-meter.tsx — Sidebar quota bar with upgrade modal
• /settings/billing page — Current plan + upgrade CTA
• API routes — /billing/status, /billing/create-checkout, /billing/portal, /billing/webhook, /usage/current

However, the user experience has significant gaps that block a production launch:

1. No detailed usage breakdown — Users see a tiny progress bar in the sidebar but have no dedicated view showing per-feature consumption
2. No billing history — Users cannot view past invoices or download receipts
3. No inline paywall — When a quota-exceeded error occurs during an AI action, the user gets a generic error toast instead of being guided to upgrade
4. No billing cycle overview — Missing period start/end, next billing date, tokens used this cycle
5. Upgrade flow not triggered from error states — Quota exhaustion in AI features shows a toast but doesn't offer a path to resolution

---

User Stories

US-1: Detailed Usage Dashboard

As a user on any tier, I want to see a detailed breakdown of my AI feature usage for the current billing period, So that I understand exactly where my quota is being consumed.

Acceptance Criteria:

• Given I am on the Billing settings page
• When I scroll below the current plan card
• Then I see a "Usage this period" section with a per-feature breakdown:
  • Feature name (i18n key)
  • Progress bar: used / limit
  • Numeric count (e.g., "47 / 100")
  • Visual state: normal (violet), warning ≥75% (amber), exhausted 100% (rose)
• And for unlimited features (Enterprise), the bar is full and shows "Unlimited"
• And the data refreshes every 30s via the existing useQuery with refetchInterval
• And the section shows the period dates (e.g., "May 1 – May 31, 2026")

US-2: Billing History

As a paying user, I want to see my past invoices and download them, So that I have records for accounting.

Acceptance Criteria:

• Given I have an active or past paid subscription
• When I view the Billing settings page
• Then I see a "Billing History" section below usage
• And it lists invoices sorted by date (newest first) with:
  • Date
  • Amount (formatted in user currency)
  • Status (Paid, Pending, Failed) with color badge
  • Download PDF link (via Stripe hosted invoice URL)
• And for BASIC/free users, the section is hidden entirely
• And the "Open Billing Portal" button remains for payment method changes

US-3: Inline Paywall (Quota Exceeded → Upgrade)

As a free user who just exhausted my AI Discovery Pack, I want to see a clear upgrade prompt instead of a cryptic error, So that I can take action immediately.

Acceptance Criteria:

• Given I trigger an AI feature (e.g., auto-tag) and my quota is exhausted
• When the API returns a QuotaExceededError
• Then the UI shows an inline paywall panel (not just a toast) with:
  • Clear message: "You've used all your [feature] credits this month"
  • Two CTAs:
    1. "Upgrade to Pro" → links to /settings/billing
    2. "Use your own API key" → links to /settings/ai#byok
  • A "Maybe later" dismiss button
• And the paywall replaces the AI action result area (not a full-page overlay)
• And the paywall auto-dismisses if the user navigates away or after 10s

US-4: Billing Cycle Overview

As a paying user, I want to see my current billing period details, So that I know when I'll be charged next and how much I've used.

Acceptance Criteria:

• Given I have an active paid subscription
• When I view the Billing page
• Then the Current Plan card also shows:
  • Billing period: "May 1 – May 31, 2026"
  • Next billing date (or "Access until [date]" if canceled)
  • A small ring/donut chart showing total AI credits used vs total limit (aggregate across features)

US-5: Upgrade Success Confirmation

As a user who just completed checkout, I want to see a clear confirmation that my plan is now active, So that I have confidence the payment worked.

Acceptance Criteria:

• Given I return from Stripe checkout (via session_id URL param)
• When the page loads
• Then I see a success banner at the top: "Welcome to [Plan Name]! Your subscription is now active."
• And the banner auto-dismisses after 5s
• And the usage meter in the sidebar updates immediately
• And the plan cards section is hidden (replaced with current plan + manage)

---

Technical Design

Architecture

All changes are frontend-only — no new API routes needed. The existing APIs provide all necessary data:

Data Need	Existing API	Field
Per-feature quotas	GET /api/usage/current	quotas[feature].{used,limit,remaining}
Billing status	GET /api/billing/status	tier, status, currentPeriodEnd, cancelAtPeriodEnd
Invoices	Stripe Customer Portal	Via /api/billing/portal redirect
Checkout	POST /api/billing/create-checkout	{clientSecret, url}

Component Structure

settings/billing/page.tsx
├── BillingPlans (existing — current plan card + plan selection)
│   ├── CurrentPlanCard (enhanced with billing cycle dates + mini usage ring)
│   ├── PlanCard[] (existing — unchanged for BASIC)
│   └── ManageBilling (existing — portal button for paid users)
├── UsageBreakdown (NEW — per-feature usage dashboard)
│   ├── PeriodHeader ("Usage for May 1–31, 2026")
│   └── FeatureRow[] (one per feature: label + progress bar + count)
└── BillingHistory (NEW — for paid users, via Stripe portal link)

components/quota-paywall.tsx (NEW — inline paywall)
├── Message ("You've used all X credits")
├── CTAs (Upgrade link + BYOK link)
└── Dismiss button

Files to Create

File	Description
components/settings/usage-breakdown.tsx	Detailed per-feature usage table with progress bars
components/settings/billing-history.tsx	Invoice list with download links (via Stripe)
components/quota-paywall.tsx	Inline paywall component for quota-exceeded errors

Files to Modify

File	Change
app/(main)/settings/billing/page.tsx	Add UsageBreakdown + BillingHistory sections
components/settings/billing-plans.tsx	Enhance CurrentPlanCard with billing period dates + mini usage ring
components/usage-meter.tsx	Add click handler to navigate to /settings/billing (not just on exhausted)
Various AI feature components	Catch QuotaExceededError and show QuotaPaywall instead of toast

Design Tokens (Existing — No New Colors)

Element	Token/Class
Section header	text-[11px] font-bold uppercase tracking-[0.15em] text-muted-foreground
Card container	rounded-xl border border-border/40 bg-paper p-6 space-y-4
Progress bar track	h-1.5 rounded-full bg-secondary/40
Progress bar fill (normal)	bg-gradient-to-r from-violet-400 to-purple-400
Progress bar fill (warning ≥75%)	bg-amber-400
Progress bar fill (exhausted)	bg-rose-400
Feature count text	text-[11px] text-muted-ink tabular-nums
Badge (active)	bg-emerald-100 text-emerald-700
Badge (past due)	bg-amber-100 text-amber-700
CTA primary	bg-[#D4A373] text-white hover:bg-[#C49363] (highlighted)
CTA secondary	border border-border hover:bg-foreground/5
Paywall panel	rounded-xl border border-rose-200 bg-rose-50/50 dark:border-rose-800/40 dark:bg-rose-900/10 p-4

i18n Keys to Add (15 locales)

{
  "billing": {
    "usageThisPeriod": "Usage this period",
    "periodRange": "{start} – {end}",
    "featureUsedLimit": "{used} / {limit}",
    "unlimited": "Unlimited",
    "noUsage": "No AI usage yet this period.",
    "billingHistory": "Billing History",
    "noInvoices": "No invoices yet.",
    "viewInvoices": "View all invoices in Stripe portal",
    "nextBillingDate": "Next billing date",
    "billingPeriod": "Billing period",
    "planSince": "Subscribed since {date}"
  },
  "quotaPaywall": {
    "title": "Monthly limit reached",
    "description": "You've used all your {feature} credits for this month.",
    "upgrade": "Upgrade plan",
    "useOwnKey": "Use your own API key",
    "later": "Maybe later"
  }
}

---

Out of Scope

• Stripe Customer Portal customization — uses the default hosted portal (already configured)
• Downgrade flow — handled via Stripe portal (out of scope for this story)
• Enterprise self-serve — "Contact Sales" mailto link is sufficient
• Real-time WebSocket quota updates — polling every 30s is sufficient
• Admin billing dashboard — deferred to a later epic
• Currency switching — EUR default, handled by Stripe locale

---

Testing Notes

• Unit: billing-sync.test.ts, billing-price-map.test.ts already exist and pass
• Integration: Test checkout flow with Stripe test mode (sk_test_ keys)
• Visual: Verify in both light and dark mode
• i18n: All 15 locale files must have the new keys
• Responsive: Plan cards grid must collapse to single column on mobile (<768px)
• Edge cases:
  • User with no subscription (BASIC) should see only usage + upgrade cards
  • User with canceled subscription should see "Access until [date]" + no upgrade cards
  • User with past_due subscription should see warning banner
  • Redis down → usage section shows "Unable to load usage" (fail-open on API, graceful on UI)

---

Estimated Effort

Task	Hours
usage-breakdown.tsx component	2h
billing-history.tsx component	1.5h
quota-paywall.tsx component	1.5h
Enhance billing-plans.tsx with cycle info	1h
Wire paywall into AI feature error handlers	2h
i18n keys (15 locales)	1h
Visual testing + dark mode	1h
Total	~10h