> ## Documentation Index
> Fetch the complete documentation index at: https://dhanurgo.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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                    |

<Warning>
  The webhook endpoint must verify Stripe's signature to prevent spoofing. The signing secret is configured via environment variable.
</Warning>

## 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                    |