Billing (Stripe Checkout, the customer portal and signed webhooks that set plans in Entitlements) is optional per installation and off by default: without it the Billing service is not started, every account keeps the plan unlimited and the web app shows nothing billing related. This page is the operator's checklist for selling plans; the design is ADR 0031, the service reference is services/billing/README.md.

Billing needs data only the operator has. Nothing here is legal or tax advice; have the texts checked.

The legal pages are served from the web image (/legal/<page>.md); to replace them, build the image with your files or mount them read-only over /usr/share/nginx/html/legal/{imprint,terms,privacy}.md of the web container (served with no-cache, never precached by the service worker).

# infra/compose/.env
COMPOSE_PROFILES=billing
ENTITLEMENTS_BILLING_ENABLED=true
BILLING_PROVIDER=stripe
BILLING_STRIPE_SECRET_KEY=sk_test_...
BILLING_STRIPE_WEBHOOK_SECRET=whsec_...
BILLING_PRICE_IDS=home=price_...,fleet=price_...
BILLING_APP_URL=https://mowdeck.example.org

docker compose -f infra/compose/docker-compose.yml up -d --build --wait
curl https://mowdeck.example.org/api/v1/billing/status

GET /api/v1/billing/status lists the plans on sale with the prices fetched from Stripe. Without the profile the route does not exist (404) and the web app hides the billing section. docker compose config --services shows billing and billing-migrate only with the profile.

1. Install the Stripe CLI and stripe login.

2. Forward webhooks to the local stack and copy the printed secret into BILLING_STRIPE_WEBHOOK_SECRET (it stays the same across restarts; stripe listen --print-secret prints it again):

   stripe listen --forward-to localhost/api/v1/billing/webhooks/stripe \
     --events checkout.session.completed,customer.subscription.created,customer.subscription.updated,customer.subscription.deleted,customer.subscription.trial_will_end,invoice.paid,invoice.payment_failed

3. Start the stack with the profile, log in as an account owner, open the account page: the plans appear with their prices. "Upgrade" opens Stripe Checkout; pay with the test card 4242 4242 4242 4242 (any future date, any CVC). Back on the account page the plan shows trial (or active without a trial) with source billing; the operator console's account history shows service:billing:sub_....

4. "Manage subscription" opens the customer portal; cancel there and watch customer.subscription.updated (cancel at period end) arrive.

5. Payment problems: use the test card 4000 0000 0000 0341 (attaches, then fails), or stripe trigger invoice.payment_failed; the subscription goes past_due and the account grace (viewing and emergency stop only). Paying again (update the card in the portal) restores active. customer.subscription.trial_will_end cannot be triggered: use a subscription with a short trial or Stripe test clocks.

6. Replays: stripe events resend evt_... delivers an event again; the answer says "duplicate": true and nothing changes.

• Fake provider (local demo, nothing charged): BILLING_PROVIDER=fake, any BILLING_STRIPE_WEBHOOK_SECRET, price ids of your choice. Checkout and the portal return links back to the account page; send signed, Stripe shaped webhooks with

  docker compose -f infra/compose/docker-compose.yml --profile billing exec billing \
    python -m billing.cli send-fixture --account-id <account uuid> --status past_due

  (--status active|trialing|past_due|unpaid|canceled|...; the account id is in GET /api/v1/identity/me).

• stripe-mock (stripe/stripe-mock, pinned in .github/workflows/ci.yml for the python job): BILLING_STRIPE_API_BASE=http://stripe-mock:12111 with any sk_test_... key validates every request against Stripe's API definition, but it keeps no state and sends no webhooks.

• Logs: webhook event handled (event id, type, outcome, account), webhook event already handled (a replay), checkout started. The ledger is the webhook_events table of the billing database (outcomes applied, ignored, stale, unknown_account, rejected, failed).
• Stripe retries failed deliveries for up to three days; a 500 from MowDeck (Entitlements not reachable) is retried automatically. rejected (e.g. a price whose plan is unknown to Entitlements) is not retried: fix the price ids and resend the event from the Stripe dashboard.
• The webhook route is rate limited per client address in Traefik (120 per minute, burst 60); Stripe retries a 429. In Kubernetes attach the same middleware to the -auth Ingress (ingress.auth.annotations), which carries the webhook path when Billing is enabled.
• Disabling: remove the profile (and set ENTITLEMENTS_BILLING_ENABLED=false to give every account unlimited again). Subscriptions keep running at Stripe until they are cancelled there.

Mirrored from docs/ops/billing.md at commit 94c46ef36cabac4c3a0bacfc0cc0c0af4defdca3. Edit the file in the repository, not this wiki page.