# Billing & Subscriptions

Core subscription management, tier limits, store billing, and invoice history. Provides tier-based feature gating used throughout the platform. Uses the payments module for actual payment processing.

## Overview

| Aspect | Detail |
|--------|--------|
| Code | `billing` |
| Classification | Core |
| Dependencies | `payments` |
| Status | Active |

## Features

- `subscription_management` — Subscription lifecycle management
- `billing_history` — Billing and payment history
- `invoice_generation` — Automatic invoice generation
- `subscription_analytics` — Subscription metrics and analytics
- `trial_management` — Free trial period management
- `limit_overrides` — Per-store tier limit overrides

## Permissions

| Permission | Description |
|------------|-------------|
| `billing.view_tiers` | View subscription tiers |
| `billing.manage_tiers` | Manage subscription tiers |
| `billing.view_subscriptions` | View subscriptions |
| `billing.manage_subscriptions` | Manage subscriptions |
| `billing.view_invoices` | View invoices |

## Data Model

See [Data Model](data-model.md) for full entity relationships.

- **SubscriptionTier** — Tier definitions with Stripe price IDs
- **TierFeatureLimit** — Per-tier feature limits (feature_code + limit_value)
- **MerchantSubscription** — Per-merchant+platform subscription state
- **MerchantFeatureOverride** — Per-merchant feature limit overrides
- **AddOnProduct / StoreAddOn** — Purchasable add-ons
- **BillingHistory** — Invoice and payment records
- **StripeWebhookEvent** — Webhook idempotency tracking

## API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `*` | `/api/v1/admin/billing/*` | Admin billing management |
| `*` | `/api/v1/admin/features/*` | Feature/tier management |
| `*` | `/api/v1/merchant/billing/*` | Merchant billing endpoints |
| `*` | `/api/v1/platform/billing/*` | Platform-wide billing stats |

## Scheduled Tasks

| Task | Schedule | Description |
|------|----------|-------------|
| `billing.reset_period_counters` | Daily 00:05 | Reset period-based usage counters |
| `billing.check_trial_expirations` | Daily 01:00 | Check and handle expired trials |
| `billing.sync_stripe_status` | Hourly :30 | Sync subscription status with Stripe |
| `billing.cleanup_stale_subscriptions` | Weekly Sunday 03:00 | Clean up stale subscription records |

## Configuration

Configured via Stripe environment variables and tier definitions in the admin panel.

## Additional Documentation

- [Data Model](data-model.md) — Entity relationships and database schema
- [Subscription System](subscription-system.md) — Architecture, feature providers, API reference
- [Feature Gating](feature-gating.md) — Tier-based feature access control and UI integration
- [Tier Management](tier-management.md) — Admin guide for managing subscription tiers
- [Subscription Workflow](subscription-workflow.md) — Subscription lifecycle and implementation phases
- [Stripe Integration](stripe-integration.md) — Stripe Connect setup, webhooks, payment flow