Billing Page (Plans & Billing Dashboard)

Purpose

Present a consolidated billing dashboard with tabs for credit balance, plans, invoices, payments, and available payment methods. Acts as the UI client for billing endpoints (balance, invoices, payments, credit packages, payment methods, plans, subscriptions).

Code Locations (exact paths)

Page: frontend/src/pages/account/AccountBillingPage.tsx
Billing API client: frontend/src/services/billing.api (getInvoices, getPayments, getCreditBalance, getCreditPackages, getAvailablePaymentMethods, downloadInvoicePDF, getPlans, getSubscriptions)
UI: frontend/src/components/ui/card, frontend/src/components/billing/BillingRecentTransactions, frontend/src/components/ui/pricing-table/PricingTable

High-Level Responsibilities

Fetch and render account-scoped billing data (credits, invoices, payments, packages, payment methods, plans, subscriptions).
Provide tabbed navigation across overview, plans, invoices, payments, methods.
Allow invoice PDF download.

Detailed Behavior

On mount: loadData() runs seven parallel calls for balance, invoices, payments, packages, payment methods, plans, subscriptions. Results populate local state; errors render a banner.
Overview tab: shows four metric cards (balance, monthly allocation, used this month, plan status) from creditBalance.
Plans tab: displays PricingTable with static plan catalog (Starter/Growth/Scale) plus dynamic plans from API; shows current subscription chips if present.
Invoices tab: lists invoices with amount/currency/status/date; supports PDF download via downloadInvoicePDF(invoiceId) using blob download flow.
Payments tab: lists payments with status badges derived from status-to-style map (paid/succeeded/completed/pending/pending_approval/processing/failed/refunded/cancelled/void/uncollectible).
Methods tab: lists available payment methods from getAvailablePaymentMethods.
“Purchase Credits” button links to /account/purchase-credits.
Loading: full-page spinner until loadData completes.

Data Structures / Models Involved (no code)

Invoice, Payment, CreditBalance, CreditPackage, PaymentMethod, Plan, Subscription DTOs from billing.api.

Execution Flow

useEffect → loadData (Promise.all) → set state.
Tab click sets activeTab; conditional renders per tab.
Invoice download: fetch blob → create object URL → anchor click → revoke URL.

Cross-Module Interactions

Reads auth user from useAuthStore for contextual display; all billing data is backend-scoped to account.
Plans tab uses static catalog for marketing copy but still shows live plan/subscription data from API.

State Transitions

activeTab switches UI sections; loading gates initial fetch; error banner shows on fetch failure.
Status badges reflect backend payment/invoice statuses only; no client mutation flows here.

Error Handling

Catches fetch errors → sets error message → red banner.
Invoice download failure shows alert.

Tenancy Rules

Relies on backend scoping through authenticated requests; no client-side account selection.

Billing Rules (if applicable)

Read-only view of credits, invoices, payments, and plans; purchases/plan changes are triggered elsewhere (Purchase Credits page or separate plan change flows).

Background Tasks / Schedulers (if applicable)

None client-side; periodic refresh is not scheduled (one-time load per mount).

Key Design Considerations

Minimizes throttling risk by batching fetches but does not paginate invoices/payments on the client; relies on API pagination responses.
Uses static plan catalog for UX but shows actual subscriptions from API to avoid mismatch with assigned plan.

How Developers Should Work With This Module

Add or reorder tabs by extending the TabType union and tab config array.
When adding new billing surfaces (e.g., disputes/refunds), mirror the pattern: fetch via billing.api, guard with loading/error, render tab content.
Keep invoice download flow consistent (blob + object URL) for cross-browser support.

4.1 KiB Raw Blame History