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/: user guide (admin screens and the owner's Billing page), API reference (endpoints, errors, gating a feature on a plan), operations (install, Stripe setup, reconcile, troubleshooting) and architecture.

Install

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:

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:

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.

• 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:

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

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

Routes

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.