# billing-overview.screen

Billing + payments overview for Quinn's CocotteAI subscription + usage costs. Implements [brief Z](./Z-billing-payments.brief.md). 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](./Z-billing-payments.brief.md) — parent.
- [Brief W](./W-org-overlay.brief.md) — org plan billing.
- [Brief M](./M-error-degraded-modes.brief.md) — payment-failure degradation.
- [Brief I](./I-audit-trust-replay.brief.md) — every billing change audited.
- [Brief V](./V-data-portability-erasure.brief.md) — 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).