Billing & Subscriptions

Stripe integration, subscription plans, checkout flow, and webhook processing

Billing & Subscriptions

HostMetrics uses Stripe for subscription billing. The billing system manages plan tiers, payment methods, checkout, and subscription lifecycle.

Plan Tiers

Plans are stored in the plans table. Each tier defines:

• Monthly and annual pricing
• Feature limits (number of vehicles, investors, imports)
• Access to premium features (reports, fleet pages, toll sync)

The BillingCycleToggle component lets users switch between monthly and annual pricing views. PlanComparisonModal shows a side-by-side feature comparison.

Checkout Flow

User selects plan → Stripe Checkout session created
→ User completes payment on Stripe → Webhook fires
→ Subscription record created → User gains access

1. User clicks upgrade on CurrentPlanCard
2. API creates a Stripe Checkout session
3. User is redirected to Stripe’s hosted checkout page
4. On success, Stripe sends a webhook to the app
5. The webhook handler creates/updates the subscriptions record

Subscription Lifecycle

Status	Meaning
active	Subscription is current and paid
past_due	Payment failed, grace period active
cancelled	User cancelled, access until period end
expired	Subscription period ended

The CancelSubscriptionDialog handles cancellation with confirmation and reason collection.

Payment Methods

Users manage saved cards via PaymentMethodsCard and AddPaymentMethodDialog. Payment methods are stored in Stripe and referenced in the payment_methods table.

Customer Portal

The StripeConnectButton redirects users to Stripe’s Customer Portal where they can:

• Update payment methods
• View invoice history
• Download receipts
• Manage subscription

Webhook Processing

The Stripe webhook route processes these events:

Event	Action
checkout.session.completed	Create subscription record
invoice.paid	Update subscription status, create invoice record
invoice.payment_failed	Mark subscription as past_due
customer.subscription.updated	Sync plan changes
customer.subscription.deleted	Mark subscription as cancelled

The webhook endpoint must verify Stripe’s signature to prevent spoofing. The signing secret is configured via environment variable.

Key Components

Component	Purpose
BillingSection	Main billing page layout
CurrentPlanCard	Shows active plan with upgrade option
PlanComparisonModal	Side-by-side plan features
BillingCycleToggle	Monthly/annual toggle
PaymentMethodsCard	Saved payment methods
OrderHistoryTable	Past invoices and receipts
UsageLimitsCard	Current usage vs plan limits
PromoCodeCard	Apply promotional codes

Key Files

File	Purpose
src/lib/db/billing.ts	Subscription and plan database operations
src/hooks/useBilling.ts	Billing state and actions hook
src/app/api/stripe/webhook/route.ts	Stripe webhook handler