Skip to content

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 /billing carries the account pages' security headers (a Content-Security- Policy with frame-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, comped and when the row last changed. Row-level security as every entity table (ADR 0003): read under the entity in context with an entity_access grant. The app role cannot write it directly; one security definer function records what Stripe says, and never touches comped.
  • Entitled means comped, or a Stripe status of active or trialing. 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 to POST /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 as client_reference_id and as the subscription's entity_id metadata.
  • 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). /billing and /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/webhook is not behind Cloudflare Access (Stripe cannot sign in). Its only check is the Stripe-Signature header over the raw body with STRIPE_WEBHOOK_SECRET. It handles checkout.session.completed, customer.subscription.created, customer.subscription.updated, customer.subscription.deleted and invoice.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 (active or trialing) 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_check and deadlines_upcoming are not refused, so the owner can always see what is due and why the other tools refuse. company_profile_set and bank_account_add are 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_end false) 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_SECRET and STRIPE_PRICE_ID are 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/webhook answer 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 once

Exit 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.