simple-module-billing 0.0.8__tar.gz

simple_module_billing-0.0.8/.gitignore

@@ -0,0 +1,53 @@
+.claude/settings.local.json
+
+# Python
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+
+# Node
+node_modules/
+dist/
+
+# Built module frontend bundles (force-included into wheels at build time)
+modules/*/*/static/dist/
+
+# Host build output and the module-pages manifest regenerated by `make gen-pages`
+host/static/dist/
+host/client_app/modules.manifest.json
+host/client_app/modules.generated.ts
+host/client_app/modules.generated.css
+host/client_app/modules.assets.json
+
+# Local databases. `make migrate` resolves alembic's script_location relative
+# to the repo root, so running it the documented way leaves ./app.db here —
+# not under host/ — and it must never be committed.
+host/*.db
+app.db*
+# SQLite runs in WAL mode since framework 0.0.35 (#339): its sidecar files.
+host/*.db-wal
+host/*.db-shm
+
+# Runtime upload storage (PagebuilderSettings.media_root)
+var/
+# file_storage's local backend (DEFAULT_FS_ROOT = ./uploads), which the dev
+# host creates in the repo root
+uploads/
+
+# Env
+.env
+
+# Playwright
+playwright-report/
+test-results/
+.playwright-mcp/
+
+# macOS
+.DS_Store
+
+# QA / verify pipeline artifacts (/qa, /vf)
+.qa/
+.verify/
+# Scratch database a /qa run boots against, so it never touches host/app.db.
+qa.db*

simple_module_billing-0.0.8/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.5
+Name: simple_module_billing
+Version: 0.0.8
+Summary: Plans, subscriptions and Stripe billing for multi-tenant SimpleModule apps
+Project-URL: Repository, https://github.com/antosubash/simple_module_python_modules
+Author-email: Anto Subash <antosubash@live.com>
+License-Expression: MIT
+Keywords: billing,saas,simple-module,stripe,subscriptions,tenants
+Requires-Python: >=3.12
+Requires-Dist: cryptography>=42
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: simple-module-core<0.1,>=0.0.35
+Requires-Dist: simple-module-db<0.1,>=0.0.35
+Requires-Dist: simple-module-hosting<0.1,>=0.0.35
+Requires-Dist: simple-module-inertia<0.1,>=0.0.35
+Requires-Dist: simple-module-settings<0.1,>=0.0.35
+Requires-Dist: simple-module-tenants<0.1,>=0.0.35
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: stripe<17,>=16
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: simple-module-test<0.1,>=0.0.35; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# simple_module_billing
+
+Plans, subscriptions and Stripe payments for multi-tenant SimpleModule apps.
+
+Billing is the commercial layer on top of the framework's `tenants` module.
+It changes none of the tenants code. Instead it plugs into the seams that
+module exposes:
+
+- **Entitlements.** Billing installs `PlanEntitlements` as
+  `app.state.tenants.entitlements`. A tenant's plan then answers
+  `limit(tenant_id, key)` and `has_feature(tenant_id, key)`. The seat limit
+  that `tenants` already enforces on members and invitations (HTTP 402) is
+  taken from the plan's `tenants.seats`.
+- **Lifecycle.** When a subscription becomes `unpaid`, billing suspends the
+  tenant through `TenantService.set_status`. When payment recovers, billing
+  reactivates it. A tenant that an admin suspended by hand is never
+  reactivated by billing.
+- **Events.** On `MembershipAdded` and `MembershipRemoved`, billing keeps the
+  Stripe quantity of a per-seat plan equal to the member count.
+
+**Full documentation** lives in [`docs/`](docs/index.md):
+[user guide](docs/user-guide.md) (admin screens and the owner's Billing page),
+[API reference](docs/api-reference.md) (endpoints, errors, gating a feature on
+a plan), [operations](docs/operations.md) (install, Stripe setup,
+reconcile, troubleshooting) and [architecture](docs/architecture.md).
+
+## Install
+
+```bash
+pip install simple_module_billing
+```
+
+The package depends on `simple_module_tenants>=0.0.35`. The host has to run
+with `SM_MULTI_TENANT=true`, because the tenant billing screen needs an active
+organisation. Billing ships SQLModel tables but no migrations. Autogenerate a
+revision in the host and give its first revision
+`branch_labels = ("billing",)`, so the module can be removed on its own with
+`alembic downgrade billing@base`.
+
+On first start, billing seeds a free default plan (`free`). It is idempotent,
+so a fresh install entitles every tenant before an admin has opened the plan
+editor.
+
+## Usage
+
+### Plans
+
+Edit plans on **Admin → Billing → Plans** (`/admin/billing/plans`). Each plan
+has the following:
+
+| Field | Meaning |
+|---|---|
+| `pricing_model` | `free`, `flat` (one price) or `per_seat` (the Stripe quantity tracks members) |
+| `stripe_price_month` / `stripe_price_year` | Stripe Price IDs. Under Stripe they are checked on save to exist, be active, and match the plan's currency and interval. |
+| `amount_month` / `amount_year` | Minor units, for display only. Stripe charges whatever the price says. |
+| `trial_days` | Trial length passed to Checkout. Free plans have no trial. |
+| `limits` | `{key: int}`. **A key that is not set means unlimited; `0` forbids.** `tenants.seats` caps members plus pending invitations. |
+| `features` | Keys that `has_feature` answers `true` for |
+
+A Stripe price that a live subscription is billed on cannot be swapped or
+removed (`409 price_in_use`): webhooks map a subscription to its plan through
+its price. Create a new plan for new pricing instead. For the same reason, do
+not let the Customer Portal switch customers to prices that belong to no plan.
+
+Exactly one plan is the default. It must be free, and it can be neither
+unset nor archived. To change the default, mark another free plan as default.
+Plans are archived, never deleted. Tenants already on an archived plan keep
+it, but it no longer appears in the plan picker.
+
+A tenant's plan is decided like this:
+
+- If the subscription status is `trialing`, `active` or `past_due`, the
+  tenant gets the subscribed plan.
+- In every other case (no subscription, `canceled`, `incomplete`, `unpaid`),
+  the tenant gets the default plan.
+
+Consumers ask the `tenants` protocol and never import billing:
+
+```python
+limit = await request.app.state.tenants.entitlements.limit(tenant_id, "storage.gb")
+```
+
+### Providers
+
+Billing settings are stored in the database. They are registered with
+`register_module_settings` and read no environment variables, so a
+`SM_BILLING_*` variable has no effect.
+
+| Setting | Notes |
+|---|---|
+| `provider` | `manual` (the default) or `stripe`. Read at startup, so changing it needs a restart. |
+| `stripe_secret_key` | `sk_…`. Stored as `enc:v1:<fernet>`, encrypted with the app's `secret_key`. |
+| `stripe_webhook_secret` | `whsec_…`, encrypted the same way. |
+| `return_base_url` | Origin that Stripe returns visitors to. If empty, the request's own origin is used. |
+
+- **manual.** There is no payment. Admins assign a plan and status on
+  **Admin → Billing → Subscriptions**. Setting `unpaid` suspends the tenant.
+- **stripe.** Payment uses Stripe Checkout (first paid plan), the Customer
+  Portal (cards, invoices, cancellation) and webhooks. If you choose `stripe`
+  without both secrets, the app still boots on `manual`, and the Connection
+  screen explains why.
+
+### Stripe setup
+
+1. Create a Product and recurring Prices in Stripe. Put their IDs on the
+   plans.
+2. Enter the secret key and webhook secret on **Admin → Billing → Stripe
+   connection** (`/admin/billing/connection`). This screen encrypts them.
+   Saving new secrets rebuilds the provider immediately.
+3. Add a webhook endpoint at `https://<host>/billing/webhooks/stripe` for
+   `checkout.session.completed` and `customer.subscription.created|updated|deleted`.
+4. Under **Settings → Billing → Subscriptions → Manage failed payments**,
+   choose **"mark the subscription as unpaid"**. This setting is what makes
+   billing allow a grace period and then suspend. If it is set to "cancel",
+   the tenant drops to the free plan instead of being suspended.
+5. Enable the Customer Portal (Settings → Billing → Customer portal).
+
+To try it locally:
+
+```bash
+stripe listen --forward-to localhost:8000/billing/webhooks/stripe
+```
+
+A tenant gets one trial: after any earlier Stripe subscription, Checkout runs
+without `trial_days`. Starting a new Checkout expires the tenant's previous
+open session, and Checkout is refused while Stripe still lists a live
+subscription for the customer, so two tabs cannot buy two subscriptions.
+
+The owner of an organisation that billing suspended can still open
+`/billing/` in a pay-only "restore" mode (status and Customer Portal, no plan
+changes); paying there reactivates it through the next webhook. An
+organisation an admin suspended stays closed.
+
+Webhooks are verified, deduplicated by event id, and never trusted for state:
+each one re-fetches the subscription from Stripe, so events that arrive out
+of order are harmless. A failed delivery records its error in
+`billing_webhook_event` and returns 500, so Stripe retries it. A subscription
+that maps to no tenant (another product on the same Stripe account, or a
+tenant since deleted) is recorded and acknowledged with 200 instead, so it
+cannot get the endpoint disabled. A cancellation or `unpaid` whose price no
+plan knows is still applied, on the plan the tenant had.
+
+### Reconcile
+
+```bash
+smpy billing reconcile [--tenant ID]
+```
+
+Re-fetches every Stripe subscription and pushes any drift in per-seat
+quantity. It is safe to run while the app is live and safe to run twice. Use
+it after missed webhooks or a Stripe outage.
+
+## Permissions
+
+| Permission | Granted to |
+|---|---|
+| `billing.view` | tenant `owner`, `admin` |
+| `billing.manage` | tenant `owner`. Checkout, plan changes and the portal also require the owner role in the active tenant. |
+| `billing.platform.view` / `billing.platform.manage` | platform admins (the `admin` role holds `*`) |
+
+## Routes
+
+| Route | What |
+|---|---|
+| `GET /billing/` | Tenant screen: current plan, seats, plan picker, portal |
+| `GET /api/billing/status` | Plan, subscription, seats, provider |
+| `POST /api/billing/checkout` `{plan_id, interval}` | Returns a Checkout `{url}` (first paid plan only) |
+| `POST /api/billing/portal` | Returns a Customer Portal `{url}` |
+| `POST /api/billing/change-plan` `{plan_id, interval}` | Paid → paid with proration; paid → free cancels at period end. Returns 409 `too_many_members` if the target's seats are fewer than those in use. |
+| `/admin/billing/plans`, `/subscriptions`, `/connection` | Admin screens |
+| `/api/billing/admin/plans` … `/subscriptions/{tenant_id}/assign` … `/connection` | Admin API |
+| `POST /billing/webhooks/stripe` | Public. The signature is the authentication. |
+
+Every API mutation needs the `X-CSRF-Token` header, which views expose as
+the `csrf_token` prop.
+
+## Known limits
+
+- **Deleting a tenant.** `tenants` publishes no `TenantDeleted` event, and
+  billing's `tenant_id` is a plain column (one module cannot hold a foreign
+  key into another module's tables). Deleting a tenant therefore neither
+  cancels its Stripe subscription nor removes its billing rows. Cancel the
+  subscription in Stripe first.
+- **Not in v1:** per-tenant limit overrides, coupons, usage metering, more
+  than one subscription per tenant, and translated UI text.

simple_module_billing-0.0.8/README.md

@@ -0,0 +1,185 @@
+# simple_module_billing
+
+Plans, subscriptions and Stripe payments for multi-tenant SimpleModule apps.
+
+Billing is the commercial layer on top of the framework's `tenants` module.
+It changes none of the tenants code. Instead it plugs into the seams that
+module exposes:
+
+- **Entitlements.** Billing installs `PlanEntitlements` as
+  `app.state.tenants.entitlements`. A tenant's plan then answers
+  `limit(tenant_id, key)` and `has_feature(tenant_id, key)`. The seat limit
+  that `tenants` already enforces on members and invitations (HTTP 402) is
+  taken from the plan's `tenants.seats`.
+- **Lifecycle.** When a subscription becomes `unpaid`, billing suspends the
+  tenant through `TenantService.set_status`. When payment recovers, billing
+  reactivates it. A tenant that an admin suspended by hand is never
+  reactivated by billing.
+- **Events.** On `MembershipAdded` and `MembershipRemoved`, billing keeps the
+  Stripe quantity of a per-seat plan equal to the member count.
+
+**Full documentation** lives in [`docs/`](docs/index.md):
+[user guide](docs/user-guide.md) (admin screens and the owner's Billing page),
+[API reference](docs/api-reference.md) (endpoints, errors, gating a feature on
+a plan), [operations](docs/operations.md) (install, Stripe setup,
+reconcile, troubleshooting) and [architecture](docs/architecture.md).
+
+## Install
+
+```bash
+pip install simple_module_billing
+```
+
+The package depends on `simple_module_tenants>=0.0.35`. The host has to run
+with `SM_MULTI_TENANT=true`, because the tenant billing screen needs an active
+organisation. Billing ships SQLModel tables but no migrations. Autogenerate a
+revision in the host and give its first revision
+`branch_labels = ("billing",)`, so the module can be removed on its own with
+`alembic downgrade billing@base`.
+
+On first start, billing seeds a free default plan (`free`). It is idempotent,
+so a fresh install entitles every tenant before an admin has opened the plan
+editor.
+
+## Usage
+
+### Plans
+
+Edit plans on **Admin → Billing → Plans** (`/admin/billing/plans`). Each plan
+has the following:
+
+| Field | Meaning |
+|---|---|
+| `pricing_model` | `free`, `flat` (one price) or `per_seat` (the Stripe quantity tracks members) |
+| `stripe_price_month` / `stripe_price_year` | Stripe Price IDs. Under Stripe they are checked on save to exist, be active, and match the plan's currency and interval. |
+| `amount_month` / `amount_year` | Minor units, for display only. Stripe charges whatever the price says. |
+| `trial_days` | Trial length passed to Checkout. Free plans have no trial. |
+| `limits` | `{key: int}`. **A key that is not set means unlimited; `0` forbids.** `tenants.seats` caps members plus pending invitations. |
+| `features` | Keys that `has_feature` answers `true` for |
+
+A Stripe price that a live subscription is billed on cannot be swapped or
+removed (`409 price_in_use`): webhooks map a subscription to its plan through
+its price. Create a new plan for new pricing instead. For the same reason, do
+not let the Customer Portal switch customers to prices that belong to no plan.
+
+Exactly one plan is the default. It must be free, and it can be neither
+unset nor archived. To change the default, mark another free plan as default.
+Plans are archived, never deleted. Tenants already on an archived plan keep
+it, but it no longer appears in the plan picker.
+
+A tenant's plan is decided like this:
+
+- If the subscription status is `trialing`, `active` or `past_due`, the
+  tenant gets the subscribed plan.
+- In every other case (no subscription, `canceled`, `incomplete`, `unpaid`),
+  the tenant gets the default plan.
+
+Consumers ask the `tenants` protocol and never import billing:
+
+```python
+limit = await request.app.state.tenants.entitlements.limit(tenant_id, "storage.gb")
+```
+
+### Providers
+
+Billing settings are stored in the database. They are registered with
+`register_module_settings` and read no environment variables, so a
+`SM_BILLING_*` variable has no effect.
+
+| Setting | Notes |
+|---|---|
+| `provider` | `manual` (the default) or `stripe`. Read at startup, so changing it needs a restart. |
+| `stripe_secret_key` | `sk_…`. Stored as `enc:v1:<fernet>`, encrypted with the app's `secret_key`. |
+| `stripe_webhook_secret` | `whsec_…`, encrypted the same way. |
+| `return_base_url` | Origin that Stripe returns visitors to. If empty, the request's own origin is used. |
+
+- **manual.** There is no payment. Admins assign a plan and status on
+  **Admin → Billing → Subscriptions**. Setting `unpaid` suspends the tenant.
+- **stripe.** Payment uses Stripe Checkout (first paid plan), the Customer
+  Portal (cards, invoices, cancellation) and webhooks. If you choose `stripe`
+  without both secrets, the app still boots on `manual`, and the Connection
+  screen explains why.
+
+### Stripe setup
+
+1. Create a Product and recurring Prices in Stripe. Put their IDs on the
+   plans.
+2. Enter the secret key and webhook secret on **Admin → Billing → Stripe
+   connection** (`/admin/billing/connection`). This screen encrypts them.
+   Saving new secrets rebuilds the provider immediately.
+3. Add a webhook endpoint at `https://<host>/billing/webhooks/stripe` for
+   `checkout.session.completed` and `customer.subscription.created|updated|deleted`.
+4. Under **Settings → Billing → Subscriptions → Manage failed payments**,
+   choose **"mark the subscription as unpaid"**. This setting is what makes
+   billing allow a grace period and then suspend. If it is set to "cancel",
+   the tenant drops to the free plan instead of being suspended.
+5. Enable the Customer Portal (Settings → Billing → Customer portal).
+
+To try it locally:
+
+```bash
+stripe listen --forward-to localhost:8000/billing/webhooks/stripe
+```
+
+A tenant gets one trial: after any earlier Stripe subscription, Checkout runs
+without `trial_days`. Starting a new Checkout expires the tenant's previous
+open session, and Checkout is refused while Stripe still lists a live
+subscription for the customer, so two tabs cannot buy two subscriptions.
+
+The owner of an organisation that billing suspended can still open
+`/billing/` in a pay-only "restore" mode (status and Customer Portal, no plan
+changes); paying there reactivates it through the next webhook. An
+organisation an admin suspended stays closed.
+
+Webhooks are verified, deduplicated by event id, and never trusted for state:
+each one re-fetches the subscription from Stripe, so events that arrive out
+of order are harmless. A failed delivery records its error in
+`billing_webhook_event` and returns 500, so Stripe retries it. A subscription
+that maps to no tenant (another product on the same Stripe account, or a
+tenant since deleted) is recorded and acknowledged with 200 instead, so it
+cannot get the endpoint disabled. A cancellation or `unpaid` whose price no
+plan knows is still applied, on the plan the tenant had.
+
+### Reconcile
+
+```bash
+smpy billing reconcile [--tenant ID]
+```
+
+Re-fetches every Stripe subscription and pushes any drift in per-seat
+quantity. It is safe to run while the app is live and safe to run twice. Use
+it after missed webhooks or a Stripe outage.
+
+## Permissions
+
+| Permission | Granted to |
+|---|---|
+| `billing.view` | tenant `owner`, `admin` |
+| `billing.manage` | tenant `owner`. Checkout, plan changes and the portal also require the owner role in the active tenant. |
+| `billing.platform.view` / `billing.platform.manage` | platform admins (the `admin` role holds `*`) |
+
+## Routes
+
+| Route | What |
+|---|---|
+| `GET /billing/` | Tenant screen: current plan, seats, plan picker, portal |
+| `GET /api/billing/status` | Plan, subscription, seats, provider |
+| `POST /api/billing/checkout` `{plan_id, interval}` | Returns a Checkout `{url}` (first paid plan only) |
+| `POST /api/billing/portal` | Returns a Customer Portal `{url}` |
+| `POST /api/billing/change-plan` `{plan_id, interval}` | Paid → paid with proration; paid → free cancels at period end. Returns 409 `too_many_members` if the target's seats are fewer than those in use. |
+| `/admin/billing/plans`, `/subscriptions`, `/connection` | Admin screens |
+| `/api/billing/admin/plans` … `/subscriptions/{tenant_id}/assign` … `/connection` | Admin API |
+| `POST /billing/webhooks/stripe` | Public. The signature is the authentication. |
+
+Every API mutation needs the `X-CSRF-Token` header, which views expose as
+the `csrf_token` prop.
+
+## Known limits
+
+- **Deleting a tenant.** `tenants` publishes no `TenantDeleted` event, and
+  billing's `tenant_id` is a plain column (one module cannot hold a foreign
+  key into another module's tables). Deleting a tenant therefore neither
+  cancels its Stripe subscription nor removes its billing rows. Cancel the
+  subscription in Stripe first.
+- **Not in v1:** per-tenant limit overrides, coupons, usage metering, more
+  than one subscription per tenant, and translated UI text.

simple_module_billing-0.0.8/docs/api-reference.md

@@ -0,0 +1,202 @@
+# Billing API reference
+
+All routes are JSON. Every `POST`/`PUT` needs the session's CSRF token in an
+`X-CSRF-Token` header; the billing pages expose it as the `csrf_token` Inertia
+prop (`simple_module_hosting.csrf.get_csrf_token`). The webhook is the only
+exception. Errors are `{"detail": "<code>", …}`; the full table is at the end.
+
+## Gating a feature on a plan (from another module)
+
+Never import billing. Ask the `tenants` entitlement seam, which billing fills
+in at startup (without billing it answers "unlimited, every feature"):
+
+```python
+from tenants.contracts.entitlements import ensure_within_limit
+
+entitlements = request.app.state.tenants.entitlements
+
+# A count-based limit: raises EntitlementExceededError → HTTP 402
+# {"detail": "plan_limit", "key": "storage.gb", "limit": 5}
+await ensure_within_limit(entitlements, tenant_id, "storage.gb", current=used, adding=1)
+
+# A yes/no feature
+if not await entitlements.has_feature(tenant_id, "sso"):
+    raise HTTPException(403, "Your plan does not include single sign-on.")
+
+# The raw number: None = unlimited, 0 = forbidden
+limit = await entitlements.limit(tenant_id, "exports.per_month")
+```
+
+Name keys `<module>.<thing>` (`storage.gb`, `exports.per_month`). An
+administrator then sets them per plan in the plan editor's Limits and Features.
+To have a key suggested in the editor, add it to `KNOWN_LIMIT_KEYS` in
+`sm_billing/constants.py`.
+
+## Tenant API — `/api/billing`
+
+The organisation is always the session's **active tenant**; no route takes a
+tenant id from the client.
+
+### `GET /api/billing/status`
+
+Permission: `billing.view` (tenant owner and admin). Also answers for the owner
+of an organisation billing suspended (restore mode).
+
+```json
+{
+  "plan": {"id": 2, "key": "team", "name": "Team", "pricing_model": "per_seat",
+           "currency": "eur", "amount_month": 900, "amount_year": null,
+           "stripe_price_month": "price_…", "stripe_price_year": null,
+           "trial_days": 14, "limits": {"tenants.seats": 10}, "features": ["sso"],
+           "description": "", "is_default": false, "is_public": true,
+           "sort_order": 1, "archived_at": null},
+  "subscription": {"status": "active", "interval": "month", "quantity": 4,
+                   "trial_end": null, "current_period_end": "2026-11-01T00:00:00Z",
+                   "cancel_at_period_end": false, "has_provider_subscription": true},
+  "seats": {"used": 4, "limit": 10},
+  "provider": "stripe",
+  "checkout_available": true,
+  "portal_available": true
+}
+```
+
+`plan` is the plan **in force** (the default plan when the subscription has
+lapsed). `subscription` is `null` for an organisation that never subscribed.
+`seats.used` counts members plus pending invitations — the number the seat
+limit is enforced against.
+
+### `POST /api/billing/checkout`
+
+Permission: `billing.manage` and tenant role `owner`. Body
+`{"plan_id": 2, "interval": "month" | "year"}` (interval defaults to `month`).
+Returns `{"url": "https://checkout.stripe.com/…"}`; redirect the browser there.
+Nothing is granted until Stripe's webhook arrives.
+
+Creates the Stripe customer on first use, expires the organisation's previous
+open Checkout session, applies the plan's trial only if the organisation never
+had a Stripe subscription, and sets the quantity to the member count for
+per-seat plans.
+
+Errors: `checkout_unavailable` 409 (manual provider), `plan_not_found` 404
+(unknown, archived or hidden plan), `plan_is_free` 400,
+`interval_unavailable` 400, `already_subscribed` 409 (a live subscription
+exists locally or at Stripe — use change-plan), `too_many_members` 409,
+`tenant_owner_required` 403, `provider_error` 502.
+
+### `POST /api/billing/portal`
+
+Permission: tenant role `owner` (with `billing.manage`, or restore mode for a
+billing-suspended organisation). No body. Returns `{"url": "https://billing.stripe.com/…"}`.
+
+Errors: `checkout_unavailable` 409, `no_customer` 409 (never checked out),
+`tenant_owner_required` 403.
+
+### `POST /api/billing/change-plan`
+
+Permission: `billing.manage` and tenant role `owner`. Body as checkout. Paid →
+paid moves the Stripe subscription with proration; → free sets it to cancel at
+period end. The local row is re-synced from Stripe's answer and the new status
+is returned (same shape as `GET /status`).
+
+Errors: `no_subscription` 409 (use checkout), `already_on_plan` 409,
+`too_many_members` 409 (`{"detail": "too_many_members", "used": 7, "limit": 5}`),
+plus the checkout errors.
+
+## Admin API — `/api/billing/admin`
+
+Read routes need `billing.platform.view`; writes need `billing.platform.manage`.
+Platform admins (role `admin`) hold both.
+
+| Method & path | Body | Returns |
+|---|---|---|
+| `GET /plans` | — | every plan, archived included |
+| `POST /plans` | plan (below) | the plan, 201 |
+| `PUT /plans/{id}` | plan (same `key`) | the plan |
+| `POST /plans/{id}/archive` | — | the plan |
+| `GET /subscriptions?status=&offset=` | — | one row per organisation (200 per page) |
+| `POST /subscriptions/{tenant_id}/assign` | `{"plan_id", "status", "interval"?}` | the row — manual provider only |
+| `POST /subscriptions/{tenant_id}/resync` | — | the row — Stripe only |
+| `GET /connection` | — | connection status (never the secrets) |
+| `PUT /connection` | see below | connection status |
+
+**Plan body**
+
+```json
+{"key": "team", "name": "Team", "description": "", "pricing_model": "flat",
+ "currency": "eur", "amount_month": 1900, "amount_year": 19000,
+ "stripe_price_month": "price_…", "stripe_price_year": "price_…",
+ "trial_days": 14, "limits": {"tenants.seats": 10}, "features": ["sso"],
+ "is_default": false, "is_public": true, "sort_order": 0}
+```
+
+Amounts are minor units (cents), 0–2,000,000,000; limit values the same range;
+`trial_days` 0–730; `sort_order` ±1,000,000. Plan keys match
+`^[a-z0-9][a-z0-9_-]{0,63}$`; limit keys and features match
+`^[a-z0-9][a-z0-9_.-]{0,99}$`. A blank price is stored as `null`. Out-of-range
+or malformed values are a 422. Reads never re-apply these bounds, so a row
+stored before a bound existed still lists.
+
+**Subscription row**
+
+```json
+{"tenant_id": "…", "tenant_name": "Acme", "tenant_slug": "acme",
+ "tenant_status": "active", "members": 4, "plan_id": 2, "plan_key": "team",
+ "plan_name": "Team", "status": "active", "interval": "month", "quantity": 4,
+ "current_period_end": "…", "cancel_at_period_end": false,
+ "suspended_by_billing": false, "provider_subscription_id": "sub_…",
+ "synced_at": "…"}
+```
+
+**Connection body** — `{"stripe_secret_key": "", "stripe_webhook_secret": "",
+"clear_secret_key": false, "clear_webhook_secret": false,
+"return_base_url": "https://app.example.com"}`. A blank secret keeps the stored
+one; `clear_*` removes it. Secrets are trimmed and stored encrypted. The
+response is `{"provider", "active_provider", "provider_error",
+"has_secret_key", "has_webhook_secret", "return_base_url", "webhook_path"}`.
+
+## Webhook — `POST /billing/webhooks/stripe`
+
+Public (exempt from login), no CSRF; authenticated by the `Stripe-Signature`
+header. Returns 404 unless the Stripe provider is running.
+
+| Response | Meaning | Stripe |
+|---|---|---|
+| 400 `invalid_signature` | bad or missing signature | gives up on this delivery |
+| 200 `processed` | subscription re-fetched and applied | done |
+| 200 `duplicate` | event id already processed | done |
+| 200 `ignored` | not an event billing handles | done |
+| 200 `ignored_unknown_tenant` | subscription belongs to no organisation here | done; reason kept on the event row |
+| 200 `ignored_nothing_to_apply` | unknown price on a lapsed subscription we never had | done; reason kept |
+| 500 `processing_failed` | anything else (Stripe unreachable, unknown price on a live subscription…) | retries with backoff |
+
+Handled events: `checkout.session.completed` and
+`customer.subscription.created|updated|deleted`.
+
+## Error codes
+
+| `detail` | Status | Where | Meaning |
+|---|---|---|---|
+| `tenant_required` | 403 | tenant API | no active organisation in the session |
+| `tenant_owner_required` | 403 | tenant API | only the owner may do this |
+| `forbidden` | 403 | status, portal | missing `billing.view` / `billing.manage` (other routes return the framework's own 403) |
+| `checkout_unavailable` | 409 | tenant API | manual provider: nothing to pay through |
+| `already_subscribed` | 409 | checkout | a live subscription exists |
+| `no_subscription` | 409 | change-plan | nothing to change yet |
+| `already_on_plan` | 409 | change-plan | target equals current |
+| `no_customer` | 409 | portal | never checked out |
+| `too_many_members` | 409 | checkout, change-plan | `used` exceeds the target's `limit` |
+| `plan_is_free` / `interval_unavailable` | 400 | checkout | wrong target |
+| `plan_not_found` | 404 | both | unknown, archived or hidden |
+| `plan_key_taken` / `price_taken` | 409 | admin plans | uniqueness (also under concurrent creates) |
+| `plan_key_immutable` | 400 | admin plans | key changed on update |
+| `price_in_use` | 409 | admin plans | a live subscription is billed on the price being changed |
+| `paid_plan_needs_price` / `free_plan_has_price` / `free_plan_has_trial` / `default_must_be_free` | 400 | admin plans | plan invariants |
+| `default_required` / `cannot_archive_default` | 409 | admin plans | there must always be one free default |
+| `price_not_found` / `price_mismatch` | 400 | admin plans (Stripe) | `{"price", "reason"}` |
+| `provider_managed` | 409 | assign | Stripe owns subscriptions; use resync |
+| `no_provider_subscription` | 409 | resync | nothing at Stripe to read |
+| `tenant_not_found` | 404 | assign, resync | |
+| `invalid_return_url` | 400 | connection | `{"message"}` says the rule |
+| `provider_unavailable` | 503 | any | no provider built (startup failed) |
+| `provider_error` | 502 | any | Stripe refused; `{"message"}` |
+| `plan_limit` | 402 | other modules | from `tenants`: `{"key", "limit"}` |