Billing Screen Restructure Plan (Sales + Marketing Focus)

Goal

Make billing understandable in 30 seconds for a store admin:

• What plan am I on?
• What did I spend?
• What action should I take now?

1) Information Architecture (Top to Bottom)

A. Billing Health Hero (single card)

• Show only:
  • Current plan (Free / Paid)
  • Current month spend
  • Credit balance (paid) or replies left (free)
  • One primary CTA: Upgrade plan (free) or Buy credits (paid)
• Why:
  • This is the decision panel for admins, not a raw data dump.

B. Usage Snapshot (compact KPI row)

• Show 3 KPIs:
  • AI Chats this month
  • Estimated cost this month
  • Avg cost per chat
• Optional:
  • Small trend sparkline only if it adds clarity.
• Why:
  • Store owners care about trend and efficiency, not token internals.

C. Plan and Payment Actions

• Paid plan:
  • Subscription status, next billing date, cancel action.
• Free plan:
  • Short upgrade message plus one clear CTA.
• Keep add-on credit options as quick buttons/chips.
• Why:
  • Separates analytics from actions and reduces cognitive load.

D. Billing History (progressive disclosure)

• Default: latest 10 rows.
• Add Show more to reveal additional rows.
• Add simple filters: All | Recurring | One-time.
• Why:
  • History is reference data, not the main decision layer.

2) Content Simplification Rules

• De-emphasize or hide technical terms by default:
  • OpenRouter cost internals
  • Token count
  • Low-level platform wording
• Use merchant-first language:
  • “AI usage cost”
  • “Customer chat volume”
  • “Credits remaining”
• If needed, place technical data in an Advanced details collapsible block.

3) Copy Direction

• Rename sections:
  • “Current usage this month” -> “This month at a glance”
  • “Usage stats (last 30 days)” -> “Performance summary”
• Replace long paragraphs with short guidance:
  • “Your balance is low. Add credits to keep AI replies running.”
• Add contextual nudges:
  • “Chats are up 24% this week. Consider adding credits.”

4) Visual Hierarchy

• Larger typography for primary KPI values.
• One primary button per section.
• More whitespace and tighter grouping to avoid text walls.
• Show banners only when actionable:
  • Low balance
  • Payment failed
  • Cancel success

5) Behavior and Data Rules

• Show low-balance warning only when threshold is crossed.
• Free plan focus:
  • Replies left this month.
• Paid plan focus:
  • Credit balance and optional projected days left.
• Preserve all existing billing logic and backend behavior.
• Scope is presentation and organization, not core billing logic changes.

6) Implementation Plan (Code)

1. Refactor billing layout and copy in:
   • app/routes/app.billing.jsx
2. Add small style primitives in:
   • app/theme-overrides.css
3. Add optional derived metrics (non-breaking):
   • monthly spend
   • average cost per chat
   • optional projected days left
4. Validate free/paid rendering and all payment flows:
   • upgrade
   • cancel
   • buy credits
   • billing history filters and show-more

7) Rollout Strategy

• Phase A (quick win):
  • UI reorder + copy cleanup + history filters.
• Phase B:
  • Derived business metrics and low-friction nudges.
• Phase C (optional):
  • Lightweight trend visualization for forecasting.