igny8/master-docs/30-frontend/accounts/SUBSCRIPTION-PAGE.md

Subscription Page (Plans & Upgrades)

Purpose

Let tenants view current subscription, browse available plans, start or cancel subscriptions, and align payment method selection with plan changes. Uses the same billing data as the Billing dashboard but focuses on plan lifecycle.

Code Locations (exact paths)

• Page: frontend/src/pages/account/PlansAndBillingPage.tsx (tabs plan and upgrade)
• API: frontend/src/services/billing.api (getPlans, getSubscriptions, createSubscription, cancelSubscription)
• Payment selection (shared): same page via getAvailablePaymentMethods

High-Level Responsibilities

• Fetch active plans and the tenant’s current subscription.
• Enable plan change (create/update subscription) gated by payment method selection.
• Allow cancellation of the active subscription.

Detailed Behavior

• Initial load (loadData):
  • Fetches credit balance, packages, invoices, payments, payment methods, plans, subscriptions (with retry/backoff for 429).
  • Filters plans to active ones; excludes Enterprise for non aws-admin accounts but re-injects the account’s assigned plan so UI always reflects truth.
  • Ensures there is at least one subscription entry; if none returned, synthesizes one from user.account.plan.
• Plan selection:
  • Requires a chosen payment method if any exist.
  • handleSelectPlan(planId) → createSubscription({ plan_id, payment_method }) → reload data.
• Cancellation:
  • handleCancelSubscription calls cancelSubscription(currentSubscription.id) and refreshes state.
• Tabs:
  • plan shows current subscription summary.
  • upgrade lists available plans (filtered) with select buttons; highlights defaults via UI styling.

Data Structures / Models Involved (no code)

• Plan: name, slug, price, billing cycle, features, is_active.
• Subscription: id, plan, status.

Execution Flow

• useEffect → loadData (controlled sequence + throttling gaps) → set plans/subscriptions/paymentMethods.
• Select plan → API call → toast → reload.
• Cancel → API call → toast → reload.

Cross-Module Interactions

• Shares payment method selection with credit purchase; uses useAuthStore for account plan fallbacks.

State Transitions

• activeTab controls view; planLoadingId/purchaseLoadingId track in-flight plan or package actions.
• Subscription status rendered from backend; cancellation triggers status change server-side.

Error Handling

• Central handleBillingError surfaces message + toast.
• Throttle (429) handled with delayed retry for subscriptions; errors suppressed if retry fails to keep page usable.

Tenancy Rules

• All subscription APIs are account-scoped by the backend; client does not switch tenants.

Billing Rules (if applicable)

• Requires a payment method before subscription create/update.
• Enterprise plans hidden for non-admin tenants to prevent accidental selection.

Background Tasks / Schedulers (if applicable)

• None client-side; no polling beyond initial load.

Key Design Considerations

• Guardrails to avoid showing empty state when account already has a plan (synthesizes subscription from account plan).
• Prefers bank/manual methods when selecting plan for safer checkout in absence of Stripe/PayPal integrations.

How Developers Should Work With This Module

• To expose new plan attributes, extend plan cards in the upgrade tab and ensure Plan type carries those fields.
• Keep enterprise-plan visibility rules aligned with backend authorization; avoid client-side-only blocking for sensitive plans.