cocottetech/@platform/codebase/@features/ai-copilot/docs/billing-overview.screen.md

billing-overview.screen

Billing + payments overview for Quinn's CocotteAI subscription + usage costs. Implements brief Z. P5+ — speculative. Reached from settings-root.screen.md S1 Account category. Voice: plain.

Layout (full-screen sheet)

┌─────────────────────────────────────────────────┐
│ ◄ Account                               Done    │ 56pt
├─────────────────────────────────────────────────┤
│                                                 │
│  Plan: Provider · $49 / month                   │   current plan
│  Renews: Jun 17 · 30 days                       │
│  [ Change plan ▼ ]                              │
│                                                 │
│  ─── This month's usage ───                     │
│  AI calls          1,847 / unlimited            │
│  Auto-actions      4,210                        │
│  GPU minutes       62 / 200                     │
│  Storage           1.4 GB / 50 GB               │
│  Coop reports      14 published                 │
│                                                 │
│  ─── Cost so far ───                            │
│  Base               $49.00                       │
│  Overage (GPU)        $0.00                      │
│  ────────                                       │
│  Total              $49.00                       │
│  [ See itemized → ]                              │
│                                                 │
│  ─── Payment ───                                │
│  Card: •••• 4218 · expires 03/29                │
│  [ Update card ]  [ Add backup card ]            │
│                                                 │
│  ─── History ───                                │
│  • May 17  Provider plan · $49.00 · paid        │
│  • Apr 17  Provider plan · $49.00 · paid        │
│  [ See all → ]                                  │
│                                                 │
│  [ Cancel plan ▼ ]                              │   destructive at bottom
│                                                 │
└─────────────────────────────────────────────────┘

Components

Component	Notes
Plan card	Current plan name + price + renewal date + change-plan CTA.
Usage panel	5 dimensions metered (AI calls, auto-actions, GPU, storage, coop reports). Each shows current / cap (or "unlimited").
Cost panel	Base + overages itemized. Tap → itemized billing sheet.
Payment card	Active card (last 4 + expiry) + add-backup affordance.
History	Last 3 paid invoices + see-all.
Cancel	Destructive at bottom — deliberate friction, multi-step confirmation.

States

1. Default (on-plan, paid) — green dot on plan card.
2. Approaching cap (GPU 80%+) — usage row pulses amber + plain copy: "Approaching GPU cap. Overage rate is $0.12/min above 200."
3. Over cap — red row + immediate overage calculation in cost panel.
4. Payment failed — red banner: "Last payment failed on {date}. Update card to avoid service interruption." Routes to card-update.
5. Card expiring soon — amber chip: "Card expires this month."
6. Cancel-in-progress (during grace period) — banner: "Plan will end on {date}. [Reactivate]"
7. Free trial active — top chip: "Trial · 7 days left."
8. Org plan vs personal plan (W) — additional row "Org: Demimonde · contributes $X/month" if applicable.
9. VoiceOver — usage rows announced with units; cost rows announced as line items.

Interactions

• Tap "Change plan" → plan picker (Provider / Provider+ / Agency tiers).
• Tap "See itemized" → itemized billing sheet (per-day per-line-item).
• Tap "Update card" → Stripe-hosted card-update sheet.
• Tap "Cancel plan" → 3-step confirmation flow with retention prompts; final commit records audit row.

Edge cases

• No payment method on file (trial only) — top banner: "Add a card to keep CocotteAI running after your trial."
• Refund pending — chip on a history row.
• Tax jurisdiction change (Quinn moved) — banner: "We've updated your tax based on a new address."
• Provider on Org plan billed through Org (per W) — usage panel reads org's allocation; personal billing card hidden; routes to org-overlay-settings.

Related

• Brief Z — parent.
• Brief W — org plan billing.
• Brief M — payment-failure degradation.
• Brief I — every billing change audited.
• Brief V — cancel-plan flows into account-close.

Out of scope

• Tier plan comparison details (separate marketing-side page).
• Tax invoice export (defer to S §S8 + V).
• Multi-payment-method primary/backup hierarchy (defer).