Account plans & Stripe products
Operators use this runbook when creating or rotating account-level subscription products in Stripe and when wiring them to the platform. Customer-facing copy lives on lovely-home.co.uk/pricing; engineering source of truth for plan ids and retail GBP amounts is functions/api/platform/platformAccountHomeLimits.js.
Related: Platform billing (hub signup Stripe, webhooks, Terraform) · Platform apply checklist (Grafana / Pages env) · Ops handbook home
Product model (what customers buy)
Account plan id (normalizeAccountSubscriptionPlan) | Marketing name | Homes included | Full features on each hub | Retail GBP (month / year) |
|---|---|---|---|---|
free | Lovely Home Free | 1 | No — Free hub limits | £0 |
lovely_home_plus | Lovely Home+ | 1 | Yes — unlimited guides, stays, bins, Alexa controls | £4.99 / £44.99 |
lovely_multi_3 | Multi Home (3) | 3 | Yes on every included hub | £9.99 / £99.99 |
lovely_multi_10 | Multi Home (10) | 10 | Yes on every included hub | £14.99 / £149.99 |
Legacy aliases still accepted for ACCOUNT_HOME_PLAN_OVERRIDE and D1 values: lovely → lovely_multi_3, lovely_plus → lovely_multi_10, lovely-home-plus → lovely_home_plus.
Two billing layers today (transitional):
- Hub rows (
site_billing) — Stripe subscription per hub for public signup and per-hub Free ↔ Lovely Home+ changes. Env:STRIPE_PRICE_ID,STRIPE_PRICE_ID_YEARLY,STRIPE_PRICE_ID_FREE(+_LIVEtwins). See Platform billing — One-time setup. - Account allowance — How many live hubs one email may run and whether Add another home provisions with Lovely Home+ features (
platformAccountHomeAllowance.js). Plan is inferred fromaccount_subscription_planon billing rows (set by account Stripe checkout webhooks),ACCOUNT_HOME_PLAN_OVERRIDE, or the number of live paid (Lovely Home+) homes (grandfathering when the column is empty; Free homes never count, #930).
Do not paste sk_…, whsec_…, or price_… values into git or this handbook — use GitHub Actions secrets, hub.tfvars, and the operator tracking table below.
Stripe checklist (test and live)
Complete test mode first, then repeat every step in live mode before taking real multi-home upgrades.
1. Create Products and Prices (Stripe Dashboard)
For each paid account plan (lovely_home_plus, lovely_multi_3, lovely_multi_10):
- Stripe Dashboard → toggle Test mode (top) → Product catalog → Add product.
- Name (customer-visible) — use marketing names exactly, e.g.
Lovely Home+,Multi Home (3),Multi Home (10). - Description (optional) — e.g. “Account subscription — up to N homes on lovely-home.co.uk”.
- Tax — same rules as hub Lovely Home+: product tax code not labelled “Eligible for Managed Payments”; keep Managed Payments off on Checkout (platform already sends
managed_payments[enabled]=false). See Platform billing — Managed Payments note. - Add two recurring Prices per product:
- Monthly — GBP, amount matching
ACCOUNT_PLAN_PRICE_GBPinplatformAccountHomeLimits.js. - Yearly — GBP, amount matching the yearly column in the same file.
- Monthly — GBP, amount matching
- Copy each
price_…id into your operator table (below). - Metadata (recommended) on Product or Price:
account_plan=lovely_multi_3(etc.) so webhooks can map subscription → plan id when engineering enables account checkout.
Lovely Home+ overlap: Public first-hub signup already uses STRIPE_PRICE_ID / STRIPE_PRICE_ID_YEARLY for Lovely Home+. You may use the same Product/Prices for account-level Lovely Home+ or create a dedicated “Account — Lovely Home+” product — engineering will confirm when account checkout merges subscriptions. Multi Home (3) and Multi Home (10) should be separate Products from single-home signup.
Free tier: Keep the existing £0 Price on STRIPE_PRICE_ID_FREE — used for first-hub public signup only (per-hub metadata site_id). It is not sold as a separate account subscription product.
Add another home / reinstate (account-managed): When the owner already has a paid account plan (lovely_home_plus, lovely_multi_3, lovely_multi_10) or an existing account-level Stripe subscription, platform does not create another £0 subscription. It reuses the account Stripe customer, writes site_billing for the new hub (no per-hub stripe_subscription_id when covered by the account sub), and enqueues registry + provision. Duplicate £0 account-plan subs created before a paid upgrade are canceled by account-plan webhooks (duplicate_free_account_plan_canceled).
2. Map Price ids → platform Pages env vars
Terraform manages platform Pages env on home-dashboard-platform. Dashboard-only edits are overwritten on the next Platform admin Terraform or Platform site provision apply.
| Purpose | Test Pages env | Live Pages env | hub.tfvars variable | GitHub secret |
|---|---|---|---|---|
| Lovely Home+ monthly (signup / per-hub upgrade — today) | STRIPE_PRICE_ID | STRIPE_PRICE_ID_LIVE | stripe_price_id | STRIPE_PRICE_ID |
| Lovely Home+ yearly (today) | STRIPE_PRICE_ID_YEARLY | STRIPE_PRICE_ID_YEARLY_LIVE | stripe_price_id_yearly | STRIPE_PRICE_ID_YEARLY |
| Free £0 hub subscription | STRIPE_PRICE_ID_FREE | STRIPE_PRICE_ID_FREE_LIVE | stripe_price_id_free | STRIPE_PRICE_ID_FREE |
| Account Lovely Home+ monthly | STRIPE_ACCOUNT_PRICE_LOVELY_HOME_PLUS | STRIPE_ACCOUNT_PRICE_LOVELY_HOME_PLUS_LIVE | stripe_account_price_lovely_home_plus | STRIPE_ACCOUNT_PRICE_LOVELY_HOME_PLUS |
| Account Lovely Home+ yearly | STRIPE_ACCOUNT_PRICE_LOVELY_HOME_PLUS_YEARLY | STRIPE_ACCOUNT_PRICE_LOVELY_HOME_PLUS_YEARLY_LIVE | stripe_account_price_lovely_home_plus_yearly | STRIPE_ACCOUNT_PRICE_LOVELY_HOME_PLUS_YEARLY |
| Multi Home (3) monthly | STRIPE_ACCOUNT_PRICE_LOVELY_MULTI_3 | STRIPE_ACCOUNT_PRICE_LOVELY_MULTI_3_LIVE | stripe_account_price_lovely_multi_3 | STRIPE_ACCOUNT_PRICE_LOVELY_MULTI_3 |
| Multi Home (3) yearly | STRIPE_ACCOUNT_PRICE_LOVELY_MULTI_3_YEARLY | STRIPE_ACCOUNT_PRICE_LOVELY_MULTI_3_YEARLY_LIVE | stripe_account_price_lovely_multi_3_yearly | STRIPE_ACCOUNT_PRICE_LOVELY_MULTI_3_YEARLY |
| Multi Home (10) monthly | STRIPE_ACCOUNT_PRICE_LOVELY_MULTI_10 | STRIPE_ACCOUNT_PRICE_LOVELY_MULTI_10_LIVE | stripe_account_price_lovely_multi_10 | STRIPE_ACCOUNT_PRICE_LOVELY_MULTI_10 |
| Multi Home (10) yearly | STRIPE_ACCOUNT_PRICE_LOVELY_MULTI_10_YEARLY | STRIPE_ACCOUNT_PRICE_LOVELY_MULTI_10_YEARLY_LIVE | stripe_account_price_lovely_multi_10_yearly | STRIPE_ACCOUNT_PRICE_LOVELY_MULTI_10_YEARLY |
Terraform maps each hub.tfvars key → Pages env in terraform/modules/platform_admin/pages.tf. Empty values are omitted (safe until you paste price_… ids). Do not commit real ids — use the operator tracking table locally.
Sync secrets to CI: after updating hub.tfvars, run node scripts/sync-hub-tfvars-to-github-secrets.mjs (or set GitHub repo secrets manually to match).
Account Lovely Home+ reuses the per-hub Lovely Home+ prices (#982). You don't need separate Stripe prices. Account-plan code (webhook, reconcile, duplicate-cancel) recognises account subscriptions by metadata (account_plan / checkout_kind, never site_id) before it looks at the price, so a per-hub subscription is never taken for an account plan.
To set the four STRIPE_ACCOUNT_PRICE_LOVELY_HOME_PLUS* secrets from the stripe_price_id* values in hub.tfvars:
node scripts/sync-account-plus-price-secrets.mjs # dry run
node scripts/sync-account-plus-price-secrets.mjs --apply --sandbox # set secrets + write sandbox-hub.tfvars keysThen run Platform admin Terraform for production, and tf-platform.sh sandbox apply plus the sandbox deploy for sandbox. The Billing page hides the Lovely Home+ card while these are empty.
3. Deploy platform Pages secrets
Update
terraform/environments/hub.tfvars(local, not committed) with Stripe keys and all currently supported price ids.Run Platform admin Terraform (GitHub Actions → confirm
apply-platform-admin) or localterraform applywith the platform stack — same flow as Platform billing.Verify Pages env:
bashbash scripts/verify-platform-stripe-env.shRe-run verify after pasting account price ids — account checkout CTAs on Billing stay hidden until the matching
STRIPE_ACCOUNT_PRICE_*vars are set for the active Stripe mode.
Stripe mode: STRIPE_MODE repo variable + D1 platform_settings.stripe_mode (test | live). Account and hub prices both respect active mode via platformStripeMode.js.
4. Test without Stripe (engineering / support)
On the platform Pages project only (never on production for real customers without approval):
| Env var | Values | Effect |
|---|---|---|
ACCOUNT_HOME_PLAN_OVERRIDE | free, lovely_home_plus, lovely_multi_3, lovely_multi_10 (legacy aliases above) | Forces account allowance for add-home and My Homes UI regardless of Stripe |
Remove the override after testing. It also makes every live hub on that platform Lovely Home+ (the hub's plan follows the account plan), so the Free lifecycle regression fails while it is set; the hub's /api/hub/plan-usage shows it as accountPlan (#928). Allowance logic: evaluateAccountHomeAllowance() in platformAccountHomeAllowance.js.
Account plan cancel and downgrades (#1450)
Account-level cancel and switches to a smaller plan (e.g. Multi Home (10) → Multi Home (3)) happen on Billing, on the Account plan card, and take effect at the end of the paid period. The owner picks which homes carry on (the next plan's allowance); the other homes close on that date and can be reinstated within 12 months. Details and the daily run are in platform-billing.md.
| Rule | Detail |
|---|---|
| Where | Billing → Account plan card: Invoices & card (Stripe portal), Switch to … for each smaller paid plan, Cancel plan. Hub cards on an account plan show Open hub and Close hub only; no per-hub Stripe button (#1453). |
| Stripe portal | Configuration card_and_invoices_v2: subscription_cancel and subscription_update off; card, invoices and contact details on. ensureAccountPlanPortalConfiguration updates the configured bpc_… id in place on first use after deploy, so no Dashboard step is needed. Cancelling in the Dashboard still works: the webhook treats it as the plan ending now with a 14-day grace for extra homes. |
| Before the date | Billing shows the date, which homes carry on and which close; Keep my plan undoes it (not once Stripe ended the plan); Change which homes carry on / Keep this home instead re-pick. Emails: on the change, a week before, when done (#1452). |
| Card failed | invoice.payment_failed on the account subscription emails the owner once and Billing shows a notice; a paid invoice clears it. Stripe's own retries and final cancel are left as configured in the Dashboard (Settings → Billing → Subscriptions). |
| Per-hub billing | Hub rows may still show Free tier on site_billing while account entitlement grants Lovely Home+ features on every included hub — do not push per-hub Lovely Home+ checkout in that state. |
Engineering: platformAccountPlanEnding.js (schedule, keep, finalise, daily run), platformAccountPlanEmails.js, routes plan-cancel / plan-switch / plan-keep / plan-homes / account-plan-run in functions/api/public/[[path]].js, migration 0029_account_plan_changes.sql. The hub-jobs Worker calls account-plan-run from the 09:00 cron, so a hub-jobs deploy goes with this platform deploy.
5. Verify customer journeys
| Step | URL / API | Expected |
|---|---|---|
| Pricing | lovely-home.co.uk/pricing | Four account plans; Multi cards link to Account → Billing |
| Sign in | lovely-home.co.uk/account | OTP email. Limits (#1569): a code takes 5 tries, each counted in the same database step that reads the code, and a right code opens one session only; one email gets at most 6 codes an hour whoever asks (counted for unknown emails too, so the limit gives nothing away); one address gets 30 guesses an hour across all emails. Over a limit: 429 RATE_LIMITED with Retry-After. Counters live in signup_attempts (scopes account-otp-email, account-verify) |
| Stays | lovely-home.co.uk/account/stays | Lovely Home+ / Multi: upcoming stays (90 days) across homes, colour per home on Multi; the home names filter the list and calendar to one home (All homes clears it, #1142). Deep link: ?siteId= on load sets the home filter (#850). Add / edit / cancel stays on the page (#1098). The form checks fields as you type, including a clash with another stay at that home (#1142). Month view (#1149): on homes editable here, click a stay to edit it, or drag an upcoming stay to another day to move it: it keeps its length, holding it over ‹ / › turns the month, and near the top or bottom of the window the page scrolls. The days show green where it would land, red where it can't (a clash, or the past), and a drop sends only the new sitStart / sitEnd as an update (the hub keeps guests, label and cleaner). Stays already in progress don't drag (use Edit / End stay now). Click a day from today on (its number, or empty space) to open Add stay with that arrival date, at the home picked in the filter if any; the calendar shows even with no stays so a day can be picked. After a save only that home is read again (siteId on the list call); until that read is drawn the calendar has aria-busy="true" and takes no drag or Edit, so an older read can't land after a move and draw the stay back (#1446), Manage in hub → hub ?open=stays only for homes that can't be edited from the account; Free: locked card (#1088) |
| Stays edits API | POST /api/public/account/stays/manage (session) | { siteId, action: create | update | detail | cancel | end-now, stayId?, stay? } → hub /api/platform/stays (platform health token + archive secret). Only Lovely Home+ / Multi homes the owner owns; the hub validates and updates guest Access as Settings does. One stay at a time per home (#1140): the hub refuses dates that share a day with another scheduled stay (STAY_OVERLAP, naming it), except a changeover, where one stay ends on the day the next begins. This applies to every way of adding or editing a stay. Edits check the owner, the live home and the plan from the stored billing rows: no Stripe or usage calls, so a save is one hub call. Add stay / Edit on Account → Stays (#1098); hubs not yet redeployed answer HUB_NEEDS_UPDATE |
| Cleaners | lovely-home.co.uk/account/cleaners | Lovely Home+ / Multi: read-only list of each home's cleaner-role home providers (name, optional phone, email, notes) stored on that home's hub D1 (home_providers, migration 0012_home_providers.sql; renamed from cleaners). Add / edit / remove providers in the hub under Settings → People → Providers (#1125 / LH-32). Account → Cleaners shows the same contacts with Manage in hub; pick a cleaner when adding or editing a stay (stays list shows Cleaner: name). Nothing is sent to cleaners. Phone and email validation matches hub rules (hubCountryCode, website/vendor/lovely-phone.js). Free: locked card (#1125) |
| Cleaners API | POST /api/public/account/cleaners (session); …/cleaners/manage deprecated | List fans out to each home's hub GET /api/platform/providers?role=cleaner. Manage returns 410 with a message to use the hub (#LH-32). Hub CRUD: /api/platform/providers (platform health token + archive secret). Stays take cleanerId (must be a cleaner-role provider on that hub). Providers are in the hub backup and restored before stays. Do not run platform billing migrations for hub schema — use npm run d1:migrate:all in worker/ for hub D1 |
| My Homes | lovely-home.co.uk/my-homes | Plan label; N of M homes when on multi; each live home has Share QR code (printable card + SVG download, #1051). Lovely Home+ / Multi: per-home overview — next stay (with in-progress badge), next bin collection, alert line, sitter summary, link to Account → Stays filtered to that home (#850) |
| Overview API | POST /api/public/account/overview (session) | Fans out per live home to hub GET /api/platform/upcoming-stays, …/upcoming-bins, …/home-alerts, and …/sitter-summary (platform health token + archive secret). Same eligibility as Stays. Hub Worker deploy required for the three new hub routes; platform Pages deploy for the overview route. Partial failure: per-home ok / error on stays; bins/alerts/sitter expose their own ok when a hub is not updated yet |
| Add home | lovely-home.co.uk/add-home | Included-with-plan panel when account has full entitlement; no per-hub £4.99 checkout. The button says Creating your home… / Starting checkout… while the platform works (#1140) |
| Billing | lovely-home.co.uk/account/billing | Account plan card: upgrade checkout, Invoices & card, Switch to a smaller plan, Cancel plan; per-hub Stripe portal / upgrade only for hubs with their own subscription |
| Eligibility API | POST /api/public/account/add-home/eligibility (session) | accountPlan, limit, homeCount, canAdd, accountPlanCheckout, accountPlanChange (pending cancel / switch, #1450) |
| Account checkout API | POST /api/public/account/plan-checkout (session) | checkoutUrl for accountPlan + billingInterval; Checkout shows Add promotion code when coupons are enabled for promotion codes in Stripe |
| Account plan portal | POST /api/public/account/plan-portal (session) | url for Stripe Customer Portal: card and invoices only (#1453) |
| Account plan changes | POST /api/public/account/plan-cancel, …/plan-switch, …/plan-keep, …/plan-homes (session) | Cancel or shrink at period end with keepSiteIds; keep the plan; re-pick homes (#1450) |
Slow hubs (#1483). Every read the account pages make of a hub (session, people, providers, overview, stays, downgrade check) stops after HUB_READ_TIMEOUT_MS (8 s, functions/api/platform/platformHealthFetch.js). A hub that hasn't answered by then counts as unreachable for that page load, so one slow or waking hub can't hold up the whole page. If My Homes can't load at all, it shows the error with Try again instead of staying on "Loading your hubs".
Where the time goes (#1144). The account list and edit calls (/api/public/account/stays, …/stays/manage, …/cleaners, …/cleaners/manage) answer with Server-Timing. Open DevTools → Network, pick the request and open Timing:
| Entry | Step |
|---|---|
session | Account session check (D1) |
billing | The owner's billing rows (D1) |
homes | Building the home list from stored rows (D1) |
hub (desc = site id) | The call to that home's hub; one per home for lists |
hub-db / hub-access | Inside the hub, on stay saves: the D1 change, then the guest-access update (D1 reads + Cloudflare Access) |
Timing-Allow-Origin is set to the marketing origin, so the entries also show in the Resource Timing API.
Use Stripe test card 4242… in test mode only. Repeat account upgrades for each SKU on a fresh test account after wiring Price ids.
6. Webhooks
No separate webhook URL — same endpoint as hub billing:
https://platform.lovely-home.co.uk/api/stripe/webhook
Ensure Bypass Cloudflare Access for that path (Platform billing). When account subscriptions go live, confirm engineering registers any new metadata handling on customer.subscription.* events.
Operator tracking table (fill in per environment)
| Plan id | Mode | Product name | Monthly price_… | Yearly price_… | Created (date) | Notes |
|---|---|---|---|---|---|---|
lovely_home_plus | test | May match existing STRIPE_PRICE_ID | ||||
lovely_home_plus | live | |||||
lovely_multi_3 | test | |||||
lovely_multi_3 | live | |||||
lovely_multi_10 | test | |||||
lovely_multi_10 | live |
Troubleshooting
| Symptom | Check |
|---|---|
| Add home blocked at 1 home | Account plan still free; override for QA; or need Multi upgrade |
| Add home shows per-hub Plus checkout | Account lacks full entitlement — expected on Free account |
| Terraform wiped Stripe vars | Values missing from hub.tfvars / GitHub secrets — restore and re-apply |
| No Lovely Home+ card on Billing (Multi Home cards show) | STRIPE_ACCOUNT_PRICE_LOVELY_HOME_PLUS* empty — node scripts/sync-account-plus-price-secrets.mjs --apply (#982) |
| Checkout 503 / price not configured | Active mode price id empty — verify with verify-platform-stripe-env.sh |
| Wrong plan label on My Homes | inferAccountSubscriptionPlan — check override, account_subscription_plan column when populated, live hub count |
| Extra Lovely Home Free subs after add-home | Expected only on first hub signup; on Multi Home accounts cancel orphan £0 subs in Stripe (keep the paid account subscription). See resolveSignupStripeReuseForAccountOwnedHub in platformAccountHomeAllowance.js |
Code references
- Plan ids, limits, retail GBP:
functions/api/platform/platformAccountHomeLimits.js - Allowance, override, add-home provisioning tier:
functions/api/platform/platformAccountHomeAllowance.js - Hub signup / Plus checkout (today):
functions/api/platform/platformBilling.js,platformPublicSignup.js - Per-hub account upgrade:
POST /api/public/account/upgrade-checkoutinplatformPublicAccount.js - Account plan checkout:
POST /api/public/account/plan-checkout,createAccountPlanCheckoutSession/ account plan webhooks inplatformBilling.js, prices inplatformAccountStripePrices.js - Account plan portal (downgrade v1):
POST /api/public/account/plan-portal,handleAccountPlanPortalinplatformPublicAccount.js - Marketing pricing display:
website/pricing.html,GET /api/public/signup/pricing