Appearance
0037: Billing through Stripe, £19.99 per company per month
Context
- GetMy Books is to be sold to tech-savvy UK owner-directors on Xero as a self-service software licence, not a service. The not-doing list had "Billing or Stripe" while there was nothing to charge for; the Product Owner reversed that on 2026-10-09.
- Each company is connected and used separately, so the licence is per company (per entity), not per person.
- FEAW and WealthTechPros are the owners' own companies.
- The web app sits behind Cloudflare Access (ADR 0004, 0020), which Stripe's webhook calls cannot pass.
Decision
- Price. £19.99 per company per month, one Stripe price (
STRIPE_PRICE_ID). Price changed to £20 (from £30), Product Owner 2026-10-09, then to £19.99, Product Owner 2026-10-12. No VAT is charged: Get My Books Ltd is not VAT-registered (Product Owner 2026-10-12), and registration is compulsory only once taxable turnover passes the threshold (£90,000 in 12 months). On registering, the price becomes VAT-inclusive with a 20% inclusive Stripe tax rate on each checkout (built and withdrawn on 2026-10-12, in the history of #253). The amount lives only in the Stripe price; no code holds it. Stripe Checkout takes the card; the Stripe Customer Portal changes the card, shows invoices and cancels. GetMy Books stores no card data. - Entitlement per entity.
entity_subscriptionholds one row per entity: the Stripe ids, the subscription status, the period end andcomped. A company is entitled when it is comped or its status isactiveortrialing. MCP tools that act on one company refuse it otherwise, with the subscribe link;connection_checkanddeadlines_upcomingalways answer. - Comped. Migration 0016 comps FEAW and WealthTechPros by name. Only a migration changes
comped: the app role cannot write the table, and the onesecurity definerfunction it may call records Stripe's state and leavescompedalone. - Webhook.
/stripe/webhookis excluded from the Access check in code and needs a Cloudflare Access bypass rule for that one path. Its trust comes only from theStripe-Signatureover the raw body. The entity id is ours, set at checkout (client_reference_idand the subscription'sentity_idmetadata), and is believed only from a signed event. Each handled event re-reads the subscription from Stripe and records its state, so late or repeated events are harmless. - The company comes from the session (rule 4). Checkout and the portal take a company name and resolve it through the signed-in person's access grants, as the MCP tools do. No id is taken from a browser.
- Settings.
STRIPE_SECRET_KEY,STRIPE_WEBHOOK_SECRETandSTRIPE_PRICE_IDcome from Dopplerprdthrough the deploy's env allowlist. They are optional, so production keeps starting before they are in Doppler: billing is on only when all three are set (a value that is set must be well formed). Until then/billing/*and/stripe/webhookanswer 503 "Billing is not set up yet", and the tools still refuse a company that is neither subscribed nor comped, saying billing is not yet available.
Consequences
- The CI step that refused a Stripe dependency is removed.
- Billing stays off until the three Stripe settings are in Doppler
prd, and checkout fails until the price and the Customer Portal are set up in Stripe. Meanwhile only comped companies (FEAW, WealthTechPros) can use the tools. - A Cloudflare Access bypass rule for
/stripe/webhookis an owner action; without it Stripe's calls are stopped at the edge and no state is recorded. - Stripe being down does not stop a subscribed company's tools: entitlement is read from our own table.
- A refund or dispute is handled in Stripe's dashboard; GetMy Books staff never touch a customer's books.
Amended 2026-10-30
Product Owner, 2026-10-30 (issue #310). The owners' own companies are FEAW, WealthTechPros and WEALTH TECH PROFESSIONALS LIMITED (company 17412331). The third was connected through self-service onboarding (ADR 0038), so it is named after its Xero legal name, which migration 0016 does not match, and Stripe Checkout charged it £19.99 on 26 Oct 2026. Decision 3 now reads: migrations 0016 and 0024 comp the owners' own companies; 0024 matches WEALTH TECH PROFESSIONALS LIMITED by name (case-insensitively) or by company number 17412331, only when an ADR 0020 allowlisted person has access, and sets comped on a row the webhook already created (keeping the Stripe ids, status and period end) or inserts one. Only a migration changes comped, as before. The refund of that payment and the cancellation of its subscription are owner actions in Stripe's dashboard, after the comp is deployed, so the tools never refuse the company in between (status canceled with comped false would). Whether one subscription should cover every company one owner connects, in place of £19.99 per company, is QD-44; the licence stays per company until it is decided.
Note 2026-11-03: what the recorder can check (issue #297)
Engineering note, not a change to the decisions above. The webhook records with no person in context, so record_entity_subscription cannot check its caller the way the owners' view's functions do (SPEC-018 S21, issue #349). Anyone holding the app role's database login can call it. Options that need no owner action were weighed:
- Remember Stripe event ids and record each once. Rejected: whoever calls the function chooses the id, so a new one is always available, and the webhook already re-reads the subscription from Stripe, so a repeated event is harmless.
- Refuse a subscription or customer id that does not look like Stripe's. Rejected: shape is easy to fake and narrows nothing.
- A Stripe customer stays with its company. Chosen (SPEC-016 S27, migration 0033). A record that would change a company's customer, or give a company with no customer yet one that another company's row holds, is refused. Checkout reuses a company's own customer and makes a new one for a company with none, so no normal record changes. It stops the one escalation from the database to Stripe: putting another company's customer on a company one controls, then opening its Customer Portal (its card, invoices and cancel button).
- The five-argument recorder from migration 0016 skipped every guard and could be called by anyone; no release calls it, and 0033 drops it.
What stays possible with the app role's login alone: marking a company live, or not live, with made-up ids. That grants or withholds the tools, not money or Stripe access, and the owners' view and the Stripe dashboard would disagree. Closing it needs a separate database role for the webhook, with its own secret in Doppler: an owner action, out of scope here.
The owners' view has the same limit. Its caller check (issue #349, migration 0035, live since 2026-11-04): admin_overview, admin_revenue and admin_trends each first call require_operator, which refuses with error 42501 unless app.principal_id names a person whose email is one of the two ADR 0020 operators. It refuses a caller with no one in context, an empty or malformed context, or anyone else in context. It trusts app.principal_id, as row-level security does: the app role sets it, and principal_id_for_email gives the app role any operator's id, so it does not stop someone holding the app role's login. Closing that needs the same kind of separate role. It is an open point here too.
Note 2026-11-04: one customer per company, made before Checkout (issue #297)
Engineering note, not a change to the decisions above. With the customer guard above, a company's two checkouts started before either completed (two tabs, or the billing page and the account home) made two Stripe customers: the second customer's live subscription was refused, and if the first was then cancelled, the paying owner was refused by every tool, and no later Stripe event could record the second. So (SPEC-016 S30 to S32):
- A company's first checkout makes its Stripe customer itself, with one idempotency key per company, and records it on the company's row (with no subscription, through the same recorder) before opening Checkout. Every later checkout, and every checkout started at the same moment, uses it.
- When the subscription a company's row follows stops being live, the webhook lists that customer's subscriptions and records another live one that names the company, so a company with any live subscription stays paid.
- A checkout for a company that is live, on its row or at Stripe, starts nothing and goes back to the company's billing page, which links the Customer Portal (a form post may not be redirected to billing.stripe.com under the page's form-action).
No migration: the recorder already takes a customer with no subscription. A company that already has two customers from before this change keeps the old behaviour; the alert for a refused live subscription still says to check the Stripe dashboard.