# Billing UI

## Overview

Stratofusion exposes Stripe billing management directly inside the authenticated user area at `/user/billing`.

## What Users Can Do

- Open **Billing & Subscription** from the header settings menu.
- See the current subscription tier and Stripe subscription status.
- Review the current billing period end date.
- See monthly plan usage, daily search usage, and connected-service limits in the billing dashboard.
- Compare quantitative tier limits such as searches/day, data transfer, and file size caps.
- See transfer messaging for copying and moving between services and accounts directly in the pricing cards and comparison table.
- Start Stripe Checkout for the first paid subscription purchase from the Free tier.
- Upgrade active paid subscriptions inside StratoFusion with immediate prorated billing.
- Schedule downgrades to a lower tier or Free for the next billing cycle inside StratoFusion.
- Open the Stripe Billing Portal to update the payment method or review Stripe-hosted billing details.
- See contextual upgrade prompts from Drive search when premium modes are selected without access.
- See a billing warning banner in Drive when a subscription is past due.

## Navigation

The authenticated user routes include:

- **Settings**: `/user/settings`.
- **Billing**: `/user/billing`.

## Search Feature Availability

| Feature          | Free         | Pro         | Unlimited   |
| ---------------- | ------------ | ----------- | ----------- |
| Basic Search     | Included     | Included    | Included    |
| Full-Text Search | Not included | Included    | Included    |
| AI Search        | Not included | Coming Soon | Coming Soon |

## Notes

- Free-tier users see upgrade prompts for full-text search.
- AI-powered semantic search is still in development and appears as `Coming Soon` for Pro and Unlimited plans.
- Pro and Unlimited plans can access full-text search today.
- Free-tier billing is conversion-first: available plans appear before plan-admin controls, and non-actionable payment-method management is hidden.
- Free-tier billing suppresses historical `canceled` Stripe status badges; after cancellation, Free is the active access state.
- The public `/welcome` campaign page is pricing-first and uses the shared billing-plan facade so Free, Pro, and Unlimited prices, highlights, and direct plan CTAs stay aligned with the app.
- Paid-tier billing remains management-first: current plan, usage, billing status, and payment details stay visible for subscription management.
- The usage card shows daily/monthly data transfer consumption, daily search usage, and live connected-service counts against the plan caps.
- Warning alerts appear once daily/monthly data transfer or daily search usage reaches `80%`.
- The header can surface a compact quota warning badge when a user is approaching daily/monthly data transfer or daily search limits.
- Subscription quota failures in transfer flows point users back to `/user/billing` with an upgrade call to action.
- Connected-service, transfer/download quota, and search tier-limit failures point users back to `/user/billing` with an upgrade call to action.
- Upload dialog batch-count and file-size tier caps surface as non-destructive plan warnings with a direct `Upgrade Plan` link instead of generic upload failure errors.
- Active paid subscribers can upgrade immediately from the billing page and schedule downgrades for the next renewal without leaving the app.
- Scheduled downgrades surface a billing alert that shows the target tier and effective date.
- A detailed comparison table shows Free, Pro, and Unlimited side by side with the current tier highlighted.
- Billing card copy surfaces `2 storage services (more coming)`, `5 storage services (more coming)`, and `All storage services (more coming)`.
- Billing copy warns that provider APIs may still restrict unlimited allowances, large files, and large batches.
- Past-due subscriptions surface a destructive banner in the Drive experience with a direct billing CTA.

## Quality Coverage

- Storybook scenarios live in `src/components/billing/BillingSettingsContent.stories.tsx`.
- Component coverage includes billing content, settings navigation, and gated search prompts.
- Playwright coverage lives in `e2e/billing-navigation.spec.ts` and expects a refreshed `.auth/local-session.json` for local runs.