Samir Boulahtit
f141cc4e6a
Move 39 documentation files from top-level docs/ into each module's docs/ folder, accessible via symlinks from docs/modules/. Create data-model.md files for 10 modules with full schema documentation. Replace originals with redirect stubs. Remove empty guide stubs. Modules migrated: tenancy, billing, loyalty, marketplace, orders, messaging, cms, catalog, inventory, hosting, prospecting. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
75 lines
3.0 KiB
Markdown
75 lines
3.0 KiB
Markdown
# 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
|