[P1] Ship pricing, checkout, usage, and billing account UX

[postigodev]

Context

A subscription backend is not sufficient for a trustworthy paid beta. Users need clear pricing, accurate limits, accessible checkout entry points, billing status, remaining usage, cancellation behavior, and recoverable failed-payment states.

The UI must not advertise unlimited AI or voice when the entitlement system enforces bounded usage.

Initial product direction

• Founding plan target: $6.99/month.
• No annual plan at initial launch.
• Guided cooking, recipe steps, navigation, and local timers should not be presented as paid remote-voice usage.
• Remote voice allowance should be explained in minutes or another measurable unit, not vague session counts.

Scope

Pricing and upgrade surfaces

• Create one canonical plan presentation shared by landing, onboarding/account upgrade surfaces, and checkout initiation.
• Clearly distinguish free/local features from metered provider-backed features.
• Show monthly price, trial terms if any, renewal behavior, taxes where applicable, included usage, and material limitations before checkout.
• Do not show annual pricing until enabled by configuration and approved by the pricing/source review.
• Support a time-bounded founding offer without scattering special-case copy.

Checkout lifecycle UX

• Start checkout from a server-created Stripe Checkout Session.
• Handle success, cancel, pending webhook, duplicate return, expired session, already-subscribed user, and provider outage states.
• Never show paid access as active merely because the browser reached a success URL.
• Provide a recoverable state while verified billing status is pending.

Account and usage

• Show current plan, subscription status, renewal/cancel date, trial/grace state, and billing-management entry point.
• Show current period usage and remaining allowance for materially limited categories, especially remote voice.
• Warn before expensive allowance exhaustion and provide a safe fallback when exhausted.
• Provide clear upgrade, cancel, resume/reactivate, and payment-failure recovery actions.
• Avoid dark patterns around cancellation, trials, and automatic renewal.

Paywalls and degraded behavior

• Add reusable feature-gate components that consume server-provided entitlements rather than hard-coded plan names.
• Preserve user work when a metered action is denied.
• Offer local/text alternatives where possible instead of blocking the whole cooking flow.
• Make quota, payment, and provider errors accessible with focus management and live-region feedback.

Analytics

• Track pricing-view, checkout-start, checkout-complete, checkout-abandon, upgrade, cancellation, payment-recovery, quota-warning, and quota-exhausted events.
• Do not include card data, prompts, transcripts, recipe content, or sensitive billing identifiers in analytics.

Acceptance criteria

• Pricing shown in every product surface is sourced from one configuration/contract.
• Users see material plan limits and renewal terms before checkout.
• Checkout success waits for verified subscription state.
• Current plan, billing status, period dates, and usage are visible in account settings.
• Cancellation and failed-payment recovery are clear and accessible.
• Exhausting remote voice does not destroy the local guided-cooking experience.
• Feature gates use resolved entitlements, not frontend-only isPremium logic.
• Annual pricing is hidden until explicitly enabled.
• E2E tests cover checkout, webhook delay, cancel, payment failure, grace period, quota exhaustion, and reactivation.

Dependencies

• Stripe lifecycle: [P0] Build Stripe subscription billing and customer lifecycle #118.
• Entitlements and usage: [P0] Define plan entitlements and durable usage accounting #119.
• Enforcement: [P1] Enforce subscription-aware quotas and provider rate limits #120.
• Accessible frontend foundation: [P1] Create an accessible dialog, navigation, and form foundation #115.
• App-wide error states: [P1] Establish app-wide loading, error, offline, and stale-data states #113.
• Privacy/terms disclosures: [P0] Publish privacy, terms, AI, and voice disclosures before public beta #99.

Out of scope

• App Store or Play Store purchase UX.
• Personalized pricing or regional experimentation during the first beta.

[arjunkshah12345-hash]

For this scope I would make the paid-flow contract explicit before UI work: (1) catalog/config exposes plan id, display price, currency, included remote-voice units, trial, renewal and founding-offer expiry; (2) the server creates the Checkout Session and records an intent id; (3) success returns to a pending-verification state until the webhook establishes the entitlement; (4) retries are idempotent and late/duplicate webhooks cannot downgrade access; (5) quota denial preserves the cooking step and offers the local/text fallback. The highest-value E2E matrix is: cancel, expired session, duplicate return, delayed webhook, wrong-plan webhook, failed payment/grace, quota exhaustion, reactivation, and config-disabled annual pricing. Analytics should carry only plan/flow/result and a correlation id, never card, prompt, transcript, or billing identifiers.