simple-module-billing 0.0.8__py3-none-any.whl

simple_module_billing-0.0.8.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,64 @@
+sm_billing/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sm_billing/admin.py,sha256=VWDAfDY-TvaitMv908s-rkulXYA9VfPMNRPqxWtlpPE,9342
+sm_billing/checkout.py,sha256=GbwpBSEiK9KP_72ZPAQT2BZZpeXZs8o_Nhbx72aliPw,9046
+sm_billing/cli.py,sha256=s5gSrJwBDimM1JnfV_8JT0Niz0PDKnEu9yFEqbT_ucE,1452
+sm_billing/constants.py,sha256=HsSnisAdCqrr0wgstlyYRyeg9_zAsfM5uyYpi0LCsOg,4013
+sm_billing/context.py,sha256=s2kLlbTpslhxLr8RfFObC8MDTJG9UG3r1dvnJw_5Q6M,2676
+sm_billing/crypto.py,sha256=DpDqr9Cp26CKG3VOEvVh7HiBjGCemb4_kDI8UoxcUQg,3076
+sm_billing/deps.py,sha256=tvycEr5ap8FdQyZ1juCrIbFHzpS0u3Z5fkfWJUprOP0,2211
+sm_billing/entitlements.py,sha256=NAmO9hdF9ZZJSUQZdMsH9osdNa2K02lmFTJJvct53YI,1249
+sm_billing/errors.py,sha256=gH5OXOgO2aOgIM5YS3z7TiclvyA00orzmNVNPxcJSxU,1398
+sm_billing/lifecycle.py,sha256=IqpRk_BBTtbHz9tmtC9YSRk0h8eT2aPkHKdzgWrdNlo,2712
+sm_billing/models.py,sha256=c7xqwB9oC2jPP8Swu3dDWkwnTeL3Wn7MDzchX7rBisM,4966
+sm_billing/module.py,sha256=71dQ3SasQtOQxjLh9iQDZlXaAL69nrqgq3tXEBhPVaE,4871
+sm_billing/plans.py,sha256=VmSvf6m-BA9hwD8mrpXKMgxYHXd0z3IRuzuBCSVnixI,9219
+sm_billing/reconcile.py,sha256=9eYf-yIqXqkOqo4UjOgI9khIPr7FdtcWLyXULjjeawQ,2646
+sm_billing/resolve.py,sha256=r1V5efjMnupgzdmLmCpWvHC1RTkMukPsxOywlMIePNg,1154
+sm_billing/schemas.py,sha256=jkVudM9Jof4CXPbLxUUGJrJgjfMXZArHz56wj4QnoNA,6892
+sm_billing/seats.py,sha256=vJNtRXujBK5fn2qWUNv5UHZrMhmEq7--ok-2glhaVPo,2256
+sm_billing/services.py,sha256=Q2IPNjGeaQYngkSFjFcVqipfjlSXrFdDFGsNvgGAFDQ,1139
+sm_billing/settings.py,sha256=o9IPA--HTE0WJDwsRlHcEomOUsVI22ICXmn9w9vHkOQ,1673
+sm_billing/startup.py,sha256=xoZ-ORfib2HdmkN11mDc1gqeYBsm9VHT_72mxXRkyBQ,876
+sm_billing/sync.py,sha256=rEGORsGfOvL3Dz2oj5MjKHTepG9UmPKoDgEfq_AILLs,4840
+sm_billing/webhooks.py,sha256=7FoTIPYSpomBeVDla5s13FvAPhzMTuHl2bgm8CHstb4,5279
+sm_billing/components/AdminNav.tsx,sha256=s-50gmSZ6EHZD4uLaoEh78ecZYUDSnb3TI1e5Sn7Uug,1657
+sm_billing/components/AssignDialog.tsx,sha256=LRz7QDLloJKobZqbqG0dU8r8C8lKMeVUg33WZeI-Urc,3086
+sm_billing/components/CurrentPlanCard.tsx,sha256=H4kbPB9HYwMoUwfBjDnWYswGQxP4jEqr1Em3g6GjQQc,2993
+sm_billing/components/LimitRows.tsx,sha256=WJZOU1uv3eoKu88febak0FlieQW78oLK6zJ5OQ7viLM,2506
+sm_billing/components/PlanCard.tsx,sha256=A-NMLg-Kqfek4oHKHNoE9DDF37KpoJXLdkfhhfZTSdg,2723
+sm_billing/components/PlanEditor.tsx,sha256=ewXBBwoI8YsIyFlUY4Ng1bIUF6T96IXhfuxcckzSi3Y,7620
+sm_billing/components/PlansTable.tsx,sha256=KqE7lDZSiAtN8J6ctFQWzgXGIDpN8Kl5DJ0Hkp3t0Jk,2668
+sm_billing/components/StatusBadge.tsx,sha256=-Vtuk9GCgmwCvkcTRwb8OMxEE15D9YJi9cK-8EUHg34,343
+sm_billing/components/SubscriptionsTable.tsx,sha256=XwT-SPIOwWhT-VfjL8YGFd-MtGSWlD1HKivnYvcGS-8,3162
+sm_billing/contracts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sm_billing/contracts/provider.py,sha256=vxP3gbW9Y1G30_6HRrUlDf63g61Uy4SMlAT6JpxOwks,3078
+sm_billing/endpoints/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sm_billing/endpoints/admin_api.py,sha256=zfNa0bmI3T8yuRBC1abuxx1NHXUTmYmO8TjX-_NwUSg,3340
+sm_billing/endpoints/admin_views.py,sha256=1wHsq9mIwF_gd2Jl4HUw9HzlgFYIgwHlBkHz7_bH5Zo,2690
+sm_billing/endpoints/api.py,sha256=-Pq0BUhhnUZH7KHvStIRfPvWjOHaiHoR5k9yFllzXhc,2183
+sm_billing/endpoints/routers.py,sha256=zgLomdwxqztZWJOxGbTAlRH_ZJJWI_Pt8OYJswoCgQs,1009
+sm_billing/endpoints/views.py,sha256=Ic4tKYScEjw3qcJu-tKxMmgxAqXzbMMaHbwYYbdhRZg,2221
+sm_billing/endpoints/webhooks.py,sha256=lW-xFHYdqF13Bdtu2Td4btmGDLE1dDeInwMaBxU4Ar4,1009
+sm_billing/hooks/useCheckoutPolling.ts,sha256=fTD0hMxRnyIlEeLZh2ormtA3pn8Z55Mm1ukVDTI-h9I,1466
+sm_billing/pages/Billing.tsx,sha256=Ic-jvLCzDf1hwdPAJfhiaU3SWTtzW2p_Z6nq6IqbVrs,7334
+sm_billing/pages/Connection.tsx,sha256=mPW4R9Xsvwcbd-cm8L7-f_5Iny7kIuRRRIo_izAU_aY,7981
+sm_billing/pages/Plans.tsx,sha256=gEV-TXXuzLdmKw1qcvOWT-loycw08yu3nbPfS-22ZsI,4101
+sm_billing/pages/Subscriptions.tsx,sha256=VB8evz3SB4pmDVR4ykSq8KsNOqIbp8oc3SSBqCkkgnw,4269
+sm_billing/providers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sm_billing/providers/factory.py,sha256=tFPR9UFXBnZpnQrtfQRojpA1tciQYzlHCBL1CtmL0Pc,1857
+sm_billing/providers/manual.py,sha256=rpu0HRGLYnWDzG8IFQwEUX-6tripRcldZjzTcCfzQPE,1952
+sm_billing/providers/stripe.py,sha256=7T6PqQOi0AcQPEmL76O4FzXc9opLA4bx9e7jNtMl3t4,8808
+sm_billing/utils/api.test.ts,sha256=Nyx4rS2FRFYyMeJIfWKw3BNmMroYnxefNFNZ6NE9vHE,2151
+sm_billing/utils/api.ts,sha256=HSdB4qrNBDFZ8H8kygk0HioY1wBjRQMTeftB_BOZxvA,4300
+sm_billing/utils/format.test.ts,sha256=DE8J7oepBitm19BlTFcmJFhLJl0LS-Rqo1vdnaLevzg,4031
+sm_billing/utils/format.ts,sha256=DuUd03jUFN1L32Kn9MIHpb4aMPdcJ8fixk8PDcJbkg0,3408
+sm_billing/utils/plan-form.test.ts,sha256=8VT1OkaNDRlO7ohU24o2euVBIb57SUAwxc15CYnTN1E,7181
+sm_billing/utils/plan-form.ts,sha256=fuEMy1606uDrTU-ZRGziqglIXOlfaXqdJHEWoAvgT_4,6799
+sm_billing/utils/seats.test.ts,sha256=fDM2p9QkbTQrgwY6-d1W390mOfTYjTGaUOHK5EJxuKg,718
+sm_billing/utils/seats.ts,sha256=PmA3j2zOyJEb7S63YaXEGst5Gp_NfhXlbQulV_tbTcg,308
+sm_billing/utils/types.ts,sha256=_7t0DaUsNbCJcJ6JJ_k89-Un83MJsJKbGn2Mo5-RPgw,2083
+sm_billing/package.json,sha256=It2bnXELrNfl_idc41Gka7AF4jZ-YiVL3Az_baK6KB0,401
+simple_module_billing-0.0.8.dist-info/METADATA,sha256=y3ZDi4DV00q8C3IQWUtS1A2nqF98VNlGCiwyWWUtJQI,9906
+simple_module_billing-0.0.8.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+simple_module_billing-0.0.8.dist-info/entry_points.txt,sha256=0Fb1diONuHnclT1ty50Mupm4pQheofTwKvc-mzO6DOU,120
+simple_module_billing-0.0.8.dist-info/RECORD,,

simple_module_billing-0.0.8.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

simple_module_billing-0.0.8.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[simple_module]
+billing = sm_billing.module:BillingModule
+
+[simple_module_cli.cli_plugins]
+billing = sm_billing.cli:app

sm_billing/admin.py

@@ -0,0 +1,236 @@
+"""Platform-admin operations: plan writes with price checks, the tenant list,
+manual assignment, resync, and the Stripe connection settings."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from sqlalchemy import select
+from tenants.models import Tenant
+
+from sm_billing import constants as c
+from sm_billing import crypto
+from sm_billing.contracts.provider import ProviderError
+from sm_billing.errors import BillingError
+from sm_billing.lifecycle import apply_lifecycle, tenant_service
+from sm_billing.models import Plan, Subscription
+from sm_billing.plans import PlanService
+from sm_billing.providers.factory import install_provider
+from sm_billing.resolve import subscription_for
+from sm_billing.schemas import (
+    ConnectionIn,
+    ConnectionOut,
+    PlanIn,
+    SubscriptionRow,
+    normalise_return_url,
+)
+from sm_billing.services import current_provider
+from sm_billing.sync import resync as resync_subscription
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+    from sqlalchemy.ext.asyncio import AsyncSession
+
+    from sm_billing.schemas import AssignIn
+
+_CLEAR_FLAGS = {
+    "clear_secret_key": "stripe_secret_key",
+    "clear_webhook_secret": "stripe_webhook_secret",
+}
+
+
+def _services(app: FastAPI):
+    return getattr(app.state, c.PACKAGE)
+
+
+# ── plans ───────────────────────────────────────────────────────────
+
+
+async def verify_prices(app: FastAPI, data: PlanIn, existing: Plan | None = None) -> None:
+    """Under Stripe, each price must exist, be active, and match currency + interval.
+
+    A price the plan already carries is not re-checked: Stripe prices get
+    archived over time, and that must not lock the plan against unrelated
+    edits (renaming, hiding, limits).
+    """
+    provider = _services(app).provider
+    if provider is None or not provider.supports_checkout:
+        return
+    for interval, price_id, current in (
+        (
+            c.Interval.MONTH,
+            data.stripe_price_month,
+            existing.stripe_price_month if existing else None,
+        ),
+        (c.Interval.YEAR, data.stripe_price_year, existing.stripe_price_year if existing else None),
+    ):
+        if not price_id or (
+            price_id == current and existing and existing.currency == data.currency
+        ):
+            continue
+        try:
+            info = await provider.verify_price(price_id)
+        except ProviderError as exc:
+            raise BillingError("price_not_found", price=price_id, reason=str(exc)) from exc
+        reason = ""
+        if not info.active:
+            reason = "price is archived in Stripe"
+        elif info.currency != data.currency:
+            reason = f"currency {info.currency} ≠ plan currency {data.currency}"
+        elif info.interval != interval:
+            reason = f"interval {info.interval} ≠ {interval}"
+        if reason:
+            raise BillingError("price_mismatch", price=price_id, reason=reason)
+
+
+async def save_plan(db: AsyncSession, app: FastAPI, data: PlanIn, plan_id: int | None) -> Plan:
+    plans = PlanService(db)
+    await verify_prices(app, data, await plans.get(plan_id) if plan_id is not None else None)
+    return await plans.create(data) if plan_id is None else await plans.update(plan_id, data)
+
+
+# ── subscriptions ───────────────────────────────────────────────────
+
+
+async def subscription_rows(
+    db: AsyncSession,
+    app: FastAPI,
+    *,
+    status: str | None = None,
+    tenant_id: str | None = None,
+    limit: int = 200,
+    offset: int = 0,
+) -> list[SubscriptionRow]:
+    default = await PlanService(db).default()
+    stmt = (
+        select(Tenant, Subscription, Plan)
+        .outerjoin(Subscription, Subscription.tenant_id == Tenant.id)
+        .outerjoin(Plan, Plan.id == Subscription.plan_id)
+        .order_by(Tenant.name, Tenant.id)
+        .limit(limit)
+        .offset(offset)
+    )
+    if status:
+        stmt = stmt.where(Subscription.status == status)
+    if tenant_id:
+        stmt = stmt.where(Tenant.id == tenant_id)
+    found = (await db.execute(stmt)).all()
+    counts = await tenant_service(db, app).member_counts([t.id for t, _, _ in found])
+    rows = []
+    for tenant, sub, plan in found:
+        # The subscribed plan even when lapsed — the status column says so.
+        shown = plan if plan is not None else default
+        rows.append(
+            SubscriptionRow(
+                tenant_id=tenant.id,
+                tenant_name=tenant.name,
+                tenant_slug=tenant.slug,
+                tenant_status=tenant.status,
+                members=counts.get(tenant.id, 0),
+                plan_id=shown.id,
+                plan_key=shown.key,
+                plan_name=shown.name,
+                status=sub.status if sub else None,
+                interval=sub.interval if sub else None,
+                quantity=sub.quantity if sub else None,
+                current_period_end=sub.current_period_end if sub else None,
+                cancel_at_period_end=bool(sub and sub.cancel_at_period_end),
+                suspended_by_billing=bool(sub and sub.suspended_by_billing),
+                provider_subscription_id=sub.provider_subscription_id if sub else None,
+                synced_at=sub.synced_at if sub else None,
+            )
+        )
+    return rows
+
+
+async def one_row(db: AsyncSession, app: FastAPI, tenant_id: str) -> SubscriptionRow:
+    rows = await subscription_rows(db, app, tenant_id=tenant_id, limit=1)
+    if not rows:
+        raise BillingError("tenant_not_found", 404)
+    return rows[0]
+
+
+async def assign(db: AsyncSession, app: FastAPI, tenant_id: str, data: AssignIn) -> None:
+    """Manual provider only: set the tenant's plan and status directly."""
+    if current_provider(app).supports_checkout:
+        raise BillingError("provider_managed", 409)
+    if await db.get(Tenant, tenant_id) is None:
+        raise BillingError("tenant_not_found", 404)
+    plan = await PlanService(db).get(data.plan_id)
+    if plan is None:
+        raise BillingError("plan_not_found", 404)
+    sub = await subscription_for(db, tenant_id)
+    if sub is None:
+        sub = Subscription(tenant_id=tenant_id, plan_id=plan.id)
+        db.add(sub)
+    sub.plan_id = plan.id
+    sub.status = data.status
+    sub.interval = data.interval
+    sub.provider_subscription_id = None
+    sub.cancel_at_period_end = False
+    await db.flush()
+    await apply_lifecycle(db, app, sub)
+
+
+async def resync(db: AsyncSession, app: FastAPI, tenant_id: str) -> None:
+    provider = current_provider(app)
+    if not provider.supports_checkout:
+        raise BillingError("checkout_unavailable", 409)
+    sub = await subscription_for(db, tenant_id)
+    if sub is None or sub.provider_subscription_id is None:
+        raise BillingError("no_provider_subscription", 409)
+    await resync_subscription(db, app, provider, sub.provider_subscription_id)
+
+
+# ── connection ──────────────────────────────────────────────────────
+
+
+def connection_out(app: FastAPI) -> ConnectionOut:
+    services = _services(app)
+    s = services.settings
+    return ConnectionOut(
+        provider=s.provider,
+        active_provider=services.provider.name if services.provider else "",
+        provider_error=services.provider_error,
+        has_secret_key=bool(s.stripe_secret_key),
+        has_webhook_secret=bool(s.stripe_webhook_secret),
+        return_base_url=s.return_base_url,
+        webhook_path=c.WEBHOOK_PATH,
+    )
+
+
+def connection_changes(data: ConnectionIn) -> dict[str, Any]:
+    """Blank secret = keep; a value is stripped and encrypted; ``clear_*`` wins."""
+    try:
+        return_base_url = normalise_return_url(data.return_base_url)
+    except ValueError as exc:
+        raise BillingError("invalid_return_url", message=str(exc)) from exc
+    changes: dict[str, Any] = {"return_base_url": return_base_url}
+    for field in c.SECRET_FIELDS:
+        value = getattr(data, field).strip()
+        if value:
+            changes[field] = crypto.encrypt_value(value)
+    for flag, field in _CLEAR_FLAGS.items():
+        if getattr(data, flag):
+            changes[field] = ""
+    return changes
+
+
+async def save_connection(db: AsyncSession, app: FastAPI, data: ConnectionIn) -> ConnectionOut:
+    from settings.reload import apply_changes_and_reload
+    from settings.service import SettingService
+    from settings.store import SettingsStore
+
+    store = SettingsStore(SettingService(db))
+    await apply_changes_and_reload(
+        app, app.state.sm.event_bus, store, package=c.PACKAGE, changes=connection_changes(data)
+    )
+    # New secrets take effect now; switching provider itself still needs a
+    # restart. A stripe that fell back to manual at startup (secrets missing)
+    # is still the chosen provider, so its new secrets apply too.
+    services = _services(app)
+    running = services.provider.name if services.provider else ""
+    chosen = services.settings.provider
+    if chosen == running or (chosen == c.PROVIDER_STRIPE and services.provider_error):
+        install_provider(services)
+    return connection_out(app)