Appearance
SPEC-016: Billing
APPROVED 2026-10-09 by the Product Owner, with ADR 0037: £19.99 per company per month, the simplest Stripe set-up (Checkout, the Customer Portal and one webhook), entitlement per company. FEAW and WealthTechPros are never billed. Price changed from £30 to £20, Product Owner 2026-10-09, then to £19.99, Product Owner 2026-10-12 (ADR 0037).
AMENDED 2026-10-30 by the Product Owner (ADR 0037 amended, issue #310): the owners' own companies are FEAW, WealthTechPros and WEALTH TECH PROFESSIONALS LIMITED (company 17412331). Migration 0024 comps the third by name or company number plus allowlisted access, including a company whose row the Stripe webhook already created (S14). Per-owner licensing is QD-44.
AMENDED 2026-11-03 (issue #297, codebase review): S4 is tightened by S26. A checkout post must carry this site's Origin and the signed-in person's form token (SPEC-017 S3), as the account pages' other forms do; a post with no Origin was let through before.
AMENDED 2026-11-02 (issue #297): a company's row never follows a second live Stripe subscription. The recorder refuses a live subscription whose id differs from the row's own live one, records nothing, and the webhook logs it and sends one alert with no identifiers (S24, migration 0028). Deleting an account decides every company's cancellation before cancelling any (a Stripe failure part-way still leaves earlier ones cancelled: issue #326), and each company's deletion and the webhook's recorder take the same per-company lock, so the two never interleave (S25).
AMENDED 2026-11-03 (issue #326, Product Owner's choice on merging): deleting an account sets each company's subscription to end at the period end (Stripe's
cancel_at_period_end), which can be undone, instead of cancelling it at once. If marking one fails, or the deletion is then refused, every subscription marked is put back and nothing is deleted, so no kept company is left without a live licence. Only when every company is marked and deleted is it final: the subscription ends at the period end with no further charge, and the webhook for the deleted company stays quiet (S20, S21, S22, S25).
AMENDED 2026-11-03 (issue #297): a Stripe customer stays with the company it was first recorded for. The recorder refuses a record that would change a company's customer, or give a company a customer another company already has (S27, migration 0033), so the app's database login alone cannot point a company's Customer Portal at someone else's card. Checkout already reuses a company's own customer, so no normal subscription is affected. The old five-argument recorder from migration 0016, which skipped every guard and which no release calls, is dropped.
AMENDED 2026-11-04 (issue #297, codebase review): every reply under
/billingcarries the account pages' security headers (a Content-Security- Policy withframe-ancestors 'none',X-Frame-Options: DENY,nosniff,Referrer-Policy: same-origin,no-store) (S28), and a checkout refused for its Origin is logged (S29). A company with any live subscription is treated as paid: its first checkout makes its Stripe customer before Checkout and records it, so two Subscribe forms opened together pay as one customer (S30); when the subscription its row follows stops being live, the webhook records another live subscription of that customer for the company (S31); and a checkout for a company with a live subscription, recorded or found at Stripe, sends the owner back to the company's billing page, which links the Customer Portal, instead (S32). The failure this closes: two checkouts started before either completed each made a new Stripe customer, the recorder (S27) refused the second customer's live subscription, and cancelling the first then left a paying owner refused by every tool, with no later Stripe event able to record the second.
AMENDED 2026-11-04 (issue #326). Decided by: Product Owner, 2026-11-04, in chat. The Terms of service (3.3, 8.1) and the Privacy notice (the data table and "When you delete your account") now say what deleting an account does to a subscription: the subscription of each company only you use is set to end at the end of the period you have paid for, before anything is deleted; if the deletion cannot finish, that is undone and nothing is deleted; you are not charged again. They said it was cancelled at once. Terms 9.1 promises 30 days' notice by email, so the owner emailed every account holder first and the new wording is in force from 4 December 2026 (QD-50). The terms version moves to 2026-12-04.1 (
TERMS_VERSION), so everyone accepts the new wording before using GetMy Books again (SPEC-017 S15) (S33).
Business intent
GetMy Books is to be sold to owner-directors on Xero as a self-service software licence. Each company the owner connects is licensed separately, at £19.99 a month. Stripe takes the card, sends the invoices and lets the owner change the card or cancel; GetMy Books only records whether each company's licence is live, and refuses the tools for a company whose licence is not.
User story
When my company's licence is not live, I want the tools to say so and give me the link to subscribe, so I can start or restart it myself; when I want to change my card or cancel, I want one link to Stripe's own page.
Scope
- Licence state per company.
entity_subscription: one row per entity (its id is the key), the Stripe customer and subscription ids, the Stripe subscription status, the end of the current period,compedand when the row last changed. Row-level security as every entity table (ADR 0003): read under the entity in context with anentity_accessgrant. The app role cannot write it directly; onesecurity definerfunction records what Stripe says, and never touchescomped. - Entitled means
comped, or a Stripe status ofactiveortrialing. Any other status (past_due,unpaid,canceled,incomplete,incomplete_expired,paused), or no row, is not entitled. - Comped companies. FEAW, WealthTechPros and WEALTH TECH PROFESSIONALS LIMITED (company 17412331) are the owners' own companies and are never billed: migrations 0016 and 0024 comp them, by name (0024 also by company number, and case-insensitively), once each exists and an ADR 0020 allowlisted person has access to it (so a stranger's company of the same name is not comped). 0024 also comps a company whose row the Stripe webhook already created, keeping what Stripe reported.
- Checkout.
GET /billing?entity=<name>shows the price and a Subscribe button; it posts toPOST /billing/checkout, which makes a Stripe Checkout Session (subscription mode,STRIPE_PRICE_ID, quantity 1) for the signed-in person's company and redirects to it. The company is the name the person gave, resolved through their access grants (rule 4); its id goes to Stripe asclient_reference_idand as the subscription'sentity_idmetadata. - Customer Portal.
GET /billing/portal?entity=<name>redirects to Stripe's Customer Portal for the company's Stripe customer. - Sign-in on the billing pages (issue #292, 2026-11-03).
/billingand/billing/*sit under the account pages' Access application (8-hour session, ADR 0042), so the app checks that second AUD,CF_ACCESS_ACCOUNT_AUD, there, and refuses a token for the connector's application (CF_ACCESS_AUD, 30 days) with 401 (SPEC-017 S21). Until the variable is set, the connector's AUD is checked, as before. - Webhook.
POST /stripe/webhookis not behind Cloudflare Access (Stripe cannot sign in). Its only check is theStripe-Signatureheader over the raw body withSTRIPE_WEBHOOK_SECRET. It handlescheckout.session.completed,customer.subscription.created,customer.subscription.updated,customer.subscription.deletedandinvoice.payment_failed: for each it reads the subscription from Stripe again and records its current state, so events that arrive late or twice change nothing. Other event types are acknowledged and ignored. - One live subscription per company (issue #297). The recorder (
record_entity_subscription, migration 0028) never replaces a company's live subscription (activeortrialing) with a different live one: a second checkout for the same company would otherwise lock out the paying owner when the spare is cancelled. Such a subscription is refused, nothing is recorded, the webhook logs it with the event id, and one push alert with no names, ids or figures is sent, so the owner can refund the spare in the Stripe dashboard. A later state of the row's own subscription, a live subscription over a row that is not live, and a subscription that is not live over a row that is (ignored, as before) are recorded as before. A company with any live subscription is still treated as paid (issue #297, 2026-11-04): a company's first checkout makes its Stripe customer (one per company, the same one however many checkouts start together) and records it before opening Checkout; when the row's subscription stops being live, the webhook records another live subscription of the same customer that names the company; and a checkout for a company with a live subscription, recorded or found at Stripe, starts nothing and sends the owner back to the company's billing page, which links the Customer Portal. - Entitlement in the tools. Every MCP tool that acts on one company refuses it when it is not entitled, after the company is resolved from the session and before anything is read from Xero or the database. The refusal says why and gives the subscribe link.
connection_checkanddeadlines_upcomingare not refused, so the owner can always see what is due and why the other tools refuse.company_profile_setandbank_account_addare not refused either, deliberately: they only save GetMy Books' own set-up for the company (SPEC-015, SPEC-017), so a new owner can finish setting up before subscribing. Every other tool stays gated. - Deleting an account cancels the subscription (SPEC-017 S16, S17). For each company the deleting person is the only member of, a Stripe subscription that has not already ended is set at Stripe to end at the period end (
cancel_at_period_end, issue #326) through the billing module before anything is deleted; it then ends with no further charge. One the owner had already set to end by the period end is left as it is; one set to end on a later date (cancel_at) is brought forward to the period end, and putting it back restores that date. Every company's cancellation is decided before any is marked: if one would be refused (billing not set up), nothing is marked and nothing is deleted. If marking one fails, or the deletion is then refused, the subscriptions already marked are put back (cancel_at_period_endfalse) and the deletion is refused with a clear message, nothing deleted. With billing not set up, deletion goes ahead only for a company with no Stripe subscription id. The webhooks that follow for the subscription of a company that no longer exists (set to end, then ended) are acknowledged without an alert. Each company's deletion and the webhook's recorder take the same per-company transaction lock (issue #297), so the webhook's record for a company waits for its deletion to finish, or finishes before it starts, and never leaves a partly deleted company. Every company is deleted in one transaction; under its lock, each company's subscription must still be the one decided on, or the deletion is refused with nothing deleted and the owner is asked to try again. - Settings.
STRIPE_SECRET_KEY,STRIPE_WEBHOOK_SECRETandSTRIPE_PRICE_IDare optional. Billing is on only when all three are set; a malformed one stops the web server at start, by name, never by value. Without them/billing/*and/stripe/webhookanswer 503 "Billing is not set up yet", and the tools still refuse a company that is not entitled, saying billing is not yet available instead of giving the subscribe link. The local stdio server does not need them.
Out of scope
- Prices other than £19.99 per company per month, coupons, trials, annual billing, VAT handling beyond what Stripe Tax and the Stripe price do.
- Any human billing service: refunds and disputes are handled in Stripe's dashboard by the Product Owner.
- Usage metering, seats, or more than one price.
- Showing invoices inside GetMy Books (the Customer Portal has them).
Scenarios
gherkin
Feature: Billing
Scenario: S1 the subscribe button opens Stripe Checkout for the person's company
Given rob@example.com is signed in through Cloudflare Access and has access to "Acme Ltd"
When he posts entity "Acme Ltd" to /billing/checkout
Then a Checkout Session is made in subscription mode for STRIPE_PRICE_ID, quantity 1
And its client_reference_id and subscription entity_id metadata are Acme Ltd's entity id
And its Stripe customer is the company's own, made with email rob@example.com when it has none (S30)
And he is redirected (303) to the session's URL
Scenario: S2 a company the person cannot see is refused
Given rob@example.com has no access to "Other Ltd"
When he posts entity "Other Ltd" to /billing/checkout
Then the reply is 404 and no Checkout Session is made
Scenario: S3 the billing pages need a Cloudflare Access sign-in of a known person
When /billing/checkout is posted with no valid Access token
Then the reply is 401
And a signed-in person with no GetMy Books principal gets 403
Scenario: S4 a checkout posted from another site is refused
When /billing/checkout is posted with an Origin that is not this site
Then the reply is 403 and no Checkout Session is made
Scenario: S5 a webhook without a valid signature changes nothing
When /stripe/webhook is posted with a missing or wrong Stripe-Signature
Then the reply is 400 and no subscription is read or recorded
Scenario: S6 a completed checkout records the subscription
Given a signed checkout.session.completed event for Acme Ltd's entity id
When it is posted to /stripe/webhook
Then the subscription is read from Stripe
And Acme Ltd's row holds its customer id, subscription id, status and period end
Scenario: S7 subscription events record Stripe's current state, idempotently
Given a signed customer.subscription.updated or customer.subscription.deleted event
When it is posted twice
Then the row holds the state Stripe reports now, and the second post changes nothing
Scenario: S8 a failed payment raises an alert
Given a signed invoice.payment_failed event for a subscription
When it is posted to /stripe/webhook
Then a push alert with no names, ids or figures is sent
And the subscription's current state is recorded
Scenario: S9 a webhook that cannot be recorded is retried and alerted
Given recording the subscription fails
When a signed event is posted
Then the reply is 500, so Stripe retries, and a push alert is sent
Scenario: S10 a subscription with no entity id, or an unknown one, is acknowledged and alerted
Given a signed event whose subscription carries no entity id, or one no entity has
When it is posted
Then the reply is 200, nothing is recorded, and a push alert is sent
Scenario: S11 other event types are acknowledged and ignored
When a signed customer.created event is posted
Then the reply is 200 and nothing is read or recorded
Scenario: S12 a company without a live licence is refused by the tools
Given Acme Ltd's subscription status is "past_due", or it has no row
When the owner calls xero_list_invoices for "Acme Ltd"
Then the tool refuses with a message naming the company and the subscribe link
And nothing is read from Xero
Scenario: S13 an active, trialing or comped company is served
Given Acme Ltd's status is "active" or "trialing", or it is comped
When the owner calls a tool for it
Then the tool runs as before
Scenario: S14 FEAW, WealthTechPros and WEALTH TECH PROFESSIONALS LIMITED are comped
Given entities named "FEAW" and "WealthTechPros" exist, each with an ADR 0020 allowlisted person granted access
And another entity named "WealthTechPros" that no allowlisted person has access to
And an entity named "WEALTH TECH PROFESSIONALS LIMITED" (in any case), or whose profile has company number 17412331, with an allowlisted person granted access
And another such entity that already has an entity_subscription row the webhook recorded, status "active", comped false, with its Stripe ids
And a namesake of it that no allowlisted person has access to
When the migrations run, once or many times
Then the first two each have one entity_subscription row with comped true
And the "WealthTechPros" namesake has none
And the third company has a comped row, and the one the webhook recorded is comped with its Stripe ids, status and period end unchanged
And its namesake stays uncomped
Scenario: S15 the webhook cannot comp a company
When the recording function is called for a comped company with status "canceled"
Then comped stays true
Scenario: S16 connection_check and deadlines_upcoming still answer
Given Acme Ltd has no live licence
When the owner calls connection_check or deadlines_upcoming
Then each answers as before
Scenario: S17 approving a card for a company without a live licence writes nothing
Given Acme Ltd has no live licence and a preview waiting
When the owner presses Approve
Then the card says the licence is not live and the preview is not claimed
Scenario: S18 the Customer Portal
Given Acme Ltd has a Stripe customer
When rob@example.com opens /billing/portal?entity=Acme Ltd
Then he is redirected (303) to a Customer Portal session for that customer
And without a Stripe customer he is redirected to /billing?entity=Acme Ltd
Scenario: S19 the web server runs without the Stripe settings, with billing off
Given STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET or STRIPE_PRICE_ID is not set
When the web server starts
Then it starts and reports Stripe billing as unavailable
And /billing/* and /stripe/webhook answer 503 "Billing is not set up yet"
And a company that is not entitled is refused, saying billing is not yet available
And a comped company is served as before
But a Stripe setting that is set and malformed stops it, naming the setting and never its value
Scenario: S20 deleting the account cancels the company's subscription
Given rob@example.com is the only member of "Acme Ltd", whose subscription sub_1 is "active"
When he deletes his account
Then sub_1 is set at Stripe to end at the period end before any of Acme Ltd's rows are deleted (issue #326, 2026-11-03)
And after the deletion it ends at the period end with no further charge
And a subscription already "canceled" or "incomplete_expired", or already set to end by the period end, is left as it is
And one set to end on a date after the period end is brought forward to the period end, and putting it back restores that date (issue #326 review, 2026-11-03)
And a company someone else still uses is not cancelled
# Note 2026-11-04 (QD-50): until the new wording takes effect on 2026-12-04,
# the published Terms of service 3.3 and the Privacy notice still say the
# subscription is cancelled "at once". The code's behaviour (set to end at
# the end of the paid period, no further charge, undone if the deletion
# cannot finish) is more favourable to the customer than that wording.
# Terms 9.1 promises 30 days' notice by email, so the wording and
# TERMS_VERSION change in their own pull request after the notice.
Scenario: S21 a cancellation that fails refuses the deletion, and is undone
Given setting sub_1 at Stripe to end at the period end fails
When rob@example.com deletes his account
Then nothing is deleted and the page says the subscription could not be cancelled and to try again
And with billing not set up, a company with a Stripe subscription id refuses the deletion, and one without is deleted
And a subscription set to end before the failing one is put back, so it renews as before (issue #326, 2026-11-03)
And when the deletion is refused after every subscription was set to end, every one is put back
And if one cannot be put back, the page names its company and says to renew it in the billing portal
Scenario: S22 the webhook for a deleted company's cancelled subscription is quiet
Given Acme Ltd was deleted after its subscription was cancelled
When the signed customer.subscription.deleted event arrives
Then the reply is 200, nothing is recorded and no alert is sent
And the same holds for the earlier event of its subscription, still "active" and set to end at the period end (issue #326, 2026-11-03)
But a subscription that is not cancelled and names no company still alerts (S10)
Scenario: S23 setting up a company works before subscribing
Given Acme Ltd has no live licence
When the owner calls company_profile_set or bank_account_add for it
Then the tool runs as before
And every other tool for Acme Ltd is still refused
Scenario: S24 a second live subscription for one company is refused and alerted (issue #297, 2026-11-02)
Given Acme Ltd's row follows sub_1, which is "active"
When the signed event for a different subscription sub_2 that is "active" or "trialing" arrives
Then nothing is recorded and Acme Ltd's row still follows sub_1
And the reply is 200, the event is logged as a warning with its id, and one push alert with no names, ids or figures is sent
And a later state of sub_1, or sub_2 once sub_1 is not live, is recorded as before
Scenario: S25 deleting an account never interleaves with the webhook (issue #297, 2026-11-02)
Given rob@example.com is the only member of "Acme Ltd" and "Old Ltd"
When one company's subscription would be refused (billing not set up, a Stripe subscription id present)
Then no company's subscription is cancelled and nothing is deleted, whichever order the companies are in
And when marking a subscription at Stripe fails part-way, the ones already marked are put back and nothing is deleted (S21, issue #326)
And while a company is being deleted, the webhook's record for it waits until the deletion has finished
And while the webhook is recording a company's subscription, its deletion waits until the record has finished
And a subscription the webhook recorded after the cancellations were decided refuses the deletion: nothing is deleted, every subscription marked is put back, and the owner is asked to try again
Scenario: S26 a checkout needs this site's Origin and the person's form token
Given rob@example.com is signed in and has access to "Acme Ltd"
When /billing/checkout is posted with no Origin, or with no form token, or with the form token of another email
Then the reply is 403 and no Checkout Session is made
And the Subscribe forms on the billing page and the account home carry his form token, so posting one starts the checkout (S1)
Scenario: S27 a Stripe customer stays with its company (issue #297, 2026-11-03)
Given Acme Ltd's row holds customer cus_A
When the recorder is called for Acme Ltd with customer cus_B, whatever the status
Or it is called for a company with no customer yet (no row, or a comped row) with customer cus_A
Then nothing is recorded and it returns false, so a live one is logged and alerted as in S24
And a later state of Acme Ltd's own subscription with cus_A is recorded as before
And a comped company's first record with a customer of its own is recorded, keeping comped
Scenario: S28 every billing reply carries the account pages' security headers (issue #297, 2026-11-04)
When /billing, /billing/checkout, /billing/portal or any other /billing address answers, signed in or not
Then the reply has a Content-Security-Policy with default-src 'none', no script source, form-action 'self' https://checkout.stripe.com and frame-ancestors 'none'
And X-Frame-Options DENY, X-Content-Type-Options nosniff, Referrer-Policy same-origin and Cache-Control no-store
And /stripe/webhook, which Stripe calls, is unchanged
Scenario: S29 a checkout refused for its Origin is logged (issue #297, 2026-11-04)
Given rob@example.com is signed in and has access to "Acme Ltd"
When /billing/checkout is posted with no Origin, or with another site's Origin
Then the reply is 403, no Checkout Session is made, and a warning with no names or ids is logged
And with this site's Origin and his form token the checkout starts (S1)
Scenario: S30 a company's first checkout makes its Stripe customer first (issue #297, 2026-11-04)
Given "Acme Ltd" has no Stripe customer recorded
When rob@example.com posts its Subscribe form, once or from two tabs at once
Then a Stripe customer is made for Acme Ltd with email rob@example.com and its entity id as metadata, with one idempotency key per company
And it is recorded on Acme Ltd's row with no subscription, keeping comped
And the Checkout Session is made for that customer
And a customer that cannot be recorded starts no checkout and is said plainly and logged
Scenario: S31 a company with any live subscription stays paid (issue #297, 2026-11-04)
Given Acme Ltd's row follows sub_1, and its customer also has sub_2 for Acme Ltd, which is "active"
When the signed event saying sub_1 is cancelled, unpaid or past due arrives
Then sub_1's state is recorded, and then sub_2 is read from Stripe and recorded, so Acme Ltd stays live
And a subscription of that customer for another company, or one that is not live, is never recorded for Acme Ltd
Scenario: S32 a checkout for a company with a live subscription goes back to its billing page (issue #297, 2026-11-04)
Given Acme Ltd's row is live, or its row is not but its customer has a live subscription for it at Stripe
When rob@example.com posts its Subscribe form
Then no Checkout Session is made and he is redirected (303) to /billing for Acme Ltd, which links the Customer Portal
And the redirect stays on this site, because the Subscribe page's form-action (S28) does not allow billing.stripe.com
And a live subscription found at Stripe is recorded first
And a comped company is sent back to its billing page, which says it is never billed
Scenario: S33 the legal documents say what deleting an account does to a subscription (issue #326, 2026-11-04)
Given the Terms of service and the Privacy notice at the current terms version (2026-12-04.1 or later)
When they describe deleting an account
Then they say the subscription of each company only you use is set to end at the end of the period you have paid for, before anything is deleted
And that if the deletion cannot finish, that is undone and nothing is deleted
And that you are not charged again
And neither says the subscription is cancelled at onceExit test
The Product Owner, in Stripe's test mode on the deployed app: subscribes a test company through /billing, sees its tools work, cancels it in the Customer Portal, sees the tools refuse with the subscribe link, and sees FEAW and WealthTechPros unaffected throughout.