The plan in this section originally called for a one-time CLI/WPCode sync script. During the build this was upgraded to a permanent admin panel instead, since a script that runs once and disappears is opaque and hard to safely re-run. The panel does everything the script would have done, plus ongoing editing with a two-step confirmation flow.

1. File created: /stripe/bsm-stripe-product-crud.php, built as a front-end page (not wp-admin) included via the same WPCode pattern as the other Stripe files. Reached today only via a “BSM Admin” button that renders exclusively on admin account menus — this is obscurity, not a real permission boundary, since no current_user_can() check exists in the file itself. Planned before launch: extend page-protect.php to explicitly block non-admins from every bsm-admin-* URL.
2. Fetches live products via GET /v1/products?active=true&limit=100 and matches prices via GET /v1/prices?product={id}&active=true on every page load
3. Generates tier_key via sanitize_title($product['name']), exactly as specced
4. Editable: name, description, seats, featured, order. Read-only: both prices, with explanatory warning text
5. Three-stage flow: review/edit → warning confirmation → field-level diff confirmation → green Implement Changes button
6. Implement Changes pushes to Stripe via POST /v1/products/{id} then immediately upserts the bsm_stripe_products row in the same request, so the two can never drift from using this tool
7. Handles tier_key changes on rename (deletes old row, inserts fresh under new slug) to avoid orphaned rows
8. Live-tested and confirmed: edited Family seats 4→5 through the full warn/confirm/implement flow, verified persisted correctly to both Stripe and the table
9. Post/Redirect/Get fix applied: the Implement step now redirects to a clean GET URL with results carried in a short-lived transient, rather than rendering the result directly from the POST. This was added after a real bug was found and reproduced live: refreshing the old result screen silently resubmitted the same form data, which could revert a field back to a stale value if it had changed elsewhere in the meantime. Confirmed fixed — refreshing the result screen after Implement no longer resubmits anything.

This file already existed with a genuinely working invite/remove flow (22,945 bytes) — it was not built from scratch. Three real problems were found and fixed, then the missing other half of the chain (invite acceptance, which lives in onboard-spa.php, not this file) was built and proven end to end with real signups.

manage-sub-members.php fixes

1. Removed an active unconditional test override that was forcing every single visitor to see themselves as a paid Family member with 4 seats, regardless of their real status — this was live and affecting every real user before today
2. Removed hardcoded $tier_labels and $seat_limits arrays (only knew about family and partner, with partner wrongly set to 10 seats instead of Instructor's real 28), replaced with the same live table lookup used everywhere else: SELECT name, seats FROM bsm_stripe_products WHERE tier_key = %s AND active = 1
3. Removed hardcoded “Family or Partner” / “1 + 4 members” / “1 + 10 members” wording from the locked and individual-plan states, replaced with generic wording that stays accurate regardless of how many tiers exist
4. Rewrote the invite email as a proper HTML email: role-aware opening line (Family invite says “as a member of”, Instructor says “as a client of”, Business says “as an employee of”), full feature list, styled CTA button, and a personal sign-off using the inviter's own first name rather than “The BodySleepMind Team” — this is framed as a personal gift, not a corporate notice
5. Split the single “Joined” column into separate “Invited” and “Joined” columns in the members table, since a master previously could not tell at a glance who had actually completed onboarding versus who was still just a pending invite
6. Built a proper mobile card-stack layout for the members table (each row becomes a card with labelled fields) rather than the previous approach of simply hiding columns on small screens

onboard-spa.php — invite token acceptance (the missing other half)

1. The invite email links to /onboard-spa/?bsm_invite={token}. The onboarder previously had no awareness of this parameter at all — it would run as a completely generic signup with no connection back to the inviter.
2. On page load, the token is now read from the URL and the stored transient is fetched, pre-filling the name and email fields shown on screens 6 and 7 with whatever the master originally typed — fully editable, since whatever the invitee confirms becomes the source of truth
3. The token travels through the form submission via a hidden field so it is available inside the save_all AJAX handler
4. After the new user's own GOD JSON row is created and written (this has to happen first — the row does not exist until this point), two further writes happen: the new user's own GOD JSON gets parent_user_id set to the inviter's user ID and member_role set based on tier (Family → member, Instructor → client, Business → employee); separately, the master's sub_members[] entry is found by matching either the original invite email or the confirmed email, then updated to status: "active", the real user_id, the confirmed name and email, and joined_date
5. Invite tokens are deliberately not deleted after use (low risk, no observed downside, and they may get reused in edge cases) — left in place per explicit decision

Removal behaviour, confirmed correct by design and by test

1. Removing an active sub-member clears parent_user_id and member_role on their own GOD JSON only — their account, user_status, and all their own wellness data are completely untouched. They become an ordinary free user, nothing is deleted.
2. The master's sub_members[] entry for that person is deleted entirely (not marked “lapsed” — simply removed from the array) and membership_seats decrements, freeing the seat for a new invite

Known gap, deliberately not fixed today

An invited entry with no user_id sits in the master's sub_members[] list indefinitely if the invitee never completes onboarding — there is no auto-expiry or resend mechanism. The master can manually remove a stale invited entry using the existing Remove button, which works correctly on invited (not just active) entries. A “resend invite” button and/or token-expiry cleanup is a worthwhile future addition, not yet built.

1. Added helper function bsm_stripe_upsert_product_row($product_id) at the top of the file (inside the function definitions block). Fetches the full product from Stripe API, generates tier_key via sanitize_title, reads metadata, fetches its prices, upserts the bsm_stripe_products row.
2. Added helper function bsm_stripe_deactivate_product_row($product_id) — sets active = 0, matched directly by stripe_product_id so it still works even when the product can no longer be fetched from Stripe
3. Handles product.created, product.updated: call bsm_stripe_upsert_product_row($event_data['id'])
4. Handles product.deleted: call bsm_stripe_deactivate_product_row($event_data['id'])
5. Handles price.created, price.updated, price.deleted: identify the parent product via $event_data['product'], call bsm_stripe_upsert_product_row for that product. price.deleted naturally clears the deleted price’s ID/amount since the upsert only ever reads currently-active prices.
6. The four other existing event handlers (subscription.updated, subscription.deleted, invoice.payment_succeeded, invoice.payment_failed) are completely untouched by this round of work — only additive changes, same if ($event_type === '...') style as the rest of the file
7. checkout.session.completed updated separately (see Section N for the related cancel/undo-cancel work that prompted finding this): the Checkout Session object has no billing-period dates of its own — those live on the Subscription object, not the session, so stripe_next_billing was staying blank for every brand-new signup until a later subscription.updated event happened to fire. The handler now makes one extra API call via the existing bsm_webhook_stripe_get() helper to fetch the actual subscription object right after checkout completes, reads current_period_end from items.data[0] (same nested location fix as the subscription.updated handler), and writes it into stripe_next_billing immediately. Confirmed via two real new signups: the first showed a blank next billing date (the bug, caught in testing), the second — after this fix — correctly showed a real date from the moment of signup.
8. ⚠️ This fix is forward-only. Any user who signed up before this fix was deployed will still have a blank stripe_next_billing until they go through a cancel/undo-cancel cycle (which exercises the already-fixed subscription.updated path) or the field is backfilled manually.
9. Live-tested twice and confirmed working both directions: editing an existing product’s metadata (Instructor seats 20→22→24→25, exercising the UPDATE branch) and creating a brand new product from scratch (Business, seats=100, exercising the INSERT branch for a tier with no prior row) both correctly produced a 200 OK webhook delivery and the matching row change in bsm_stripe_products, confirmed directly in phpMyAdmin both times.

1. Removed the get_option('bsm_stripe_price_' . $tier . '_' . $period) lookup
2. Removed the hardcoded $valid_tiers array entirely — this array still referenced the old “partner” tier name rather than “instructor”, so it was already stale
3. Replaced both with a single query: SELECT * FROM bsm_stripe_products WHERE tier_key = %s AND active = 1 LIMIT 1. If no row is found, the tier does not exist or is inactive and the user is redirected to the plans page exactly as the old invalid-tier path did.
4. Reads price_monthly_id or price_annual_id off that row depending on the $period parameter
5. All other logic in the file is unchanged — subscription cancellation, Stripe customer matching, checkout session creation

1. Removed the bsm_get_stripe_prices() function and all transient caching/live Stripe API call logic
2. Removed the hardcoded $tiers array (individual, family, partner entries)
3. Replaced with: SELECT * FROM bsm_stripe_products WHERE active = 1 ORDER BY display_order ASC
4. Builds the $tiers array dynamically from the query results — label and description come straight from the table's name/description columns (which sync from Stripe), prices formatted via bsm_format_price() (kept, still needed), featured flag drives the “Most popular” badge
5. Free tier kept hardcoded as the first entry, prepended before the DB results — it is not a Stripe product and never will be. Its button behaviour (Current plan / Downgrade to free / In cancellation period) remains fully dynamic, driven by user_status and cancellation_pending, exactly as before.
6. Seats label changed to format “Max: X Members” (or “Max: 1 Member” for solo tiers) generated from the table's raw seats integer, applied consistently to both the dynamic tiers and the hardcoded Free tier
7. Removed the legacy “Reactivate with X” button wording entirely. Per the Golden Rule there is no reactivation concept anywhere in this system — switching tiers while in a cancellation notice period now shows the exact same “Switch to X” / “Upgrade to X” wording as any other tier change, linking to the same /checkout/?tier=X&period=Y URL.

1. Removed the hardcoded $tier_labels array (had gone stale — still said “Partner” after the Stripe-side rename to Instructor)
2. Removed the hardcoded $seat_limits array (also stale — said 10 for the old Partner tier, real Instructor seats is 28)
3. Replaced both with a single query: SELECT name, seats FROM bsm_stripe_products WHERE tier_key = %s AND active = 1 LIMIT 1 using the user's $membership_tier, falling back to “Individual” / 0 seats if no row matches (e.g. a stale tier_key with no corresponding product)
4. Removed three more hardcoded tier-name mentions in body copy (the change-plan link subtitle, two My-Members empty-state messages), replaced with fully generic wording that names no specific tier, so new tiers never make this copy stale again
5. Fixed three broken/wrong links found at the same time: the cancellation banner's “reactivate via billing portal” link now reads “Stop the cancellation” and points to /undo-cancel/; the “Cancel subscription” button now points to /cancel-subscription/ instead of the never-built /bsm-stripe-cancel/; the danger-row “Reactivate” button is now “Stop cancellation” linking to /undo-cancel/

1. stripe_product_id VARCHAR(100) NOT NULL DEFAULT '' column included in the CREATE TABLE SQL from the start (see Step 7)
2. Stores the native Stripe product ID (e.g. prod_Abc123...) alongside the BSM tier_key slug
3. Used by both the admin panel and the webhook's upsert/deactivate functions to match rows by Stripe ID rather than regenerating the slug, which matters for product.deleted events where the product can no longer be fetched
4. Verified via SHOW INDEX — PRIMARY on tier_key only, separate non-unique index on stripe_product_id

The core of this is now built and proven with real users. What remains is listed separately below as genuinely outstanding.

Built and proven

1. sub_members[], member_role and parent_user_id all exist in the real GOD JSON schema, confirmed against live data
2. bsm-stripe-cancel.php: the confirmation screen now counts only active sub-members (a pending invite never had access to lose) and lists each one by name and email before the master confirms — tested live, confirmed correct
3. On confirm, every active sub-member is sent a styled HTML email immediately, stating the real end date (pulled from stripe_next_billing), reassuring them their account and data are untouched, and a CTA button to /plans-page/ encouraging them to start their own Individual or Family plan. The master's own co-ordinator role label in that email is pulled live from bsm_stripe_products.name (with Business reframed to “Employer” for this one sentence only), so a renamed or newly added tier flows through with no code change.
4. customer.subscription.deleted handler in the webhook now auto-detaches every active sub-member the moment the master's subscription genuinely ends — clears parent_user_id and member_role on each sub-member's own GOD JSON, and empties the master's sub_members[] array. This mirrors the manual single-remove logic in manage-sub-members.php, just triggered automatically instead of by a button click.
5. Manual single-member removal by the master (Section A2) was already done and proven separately, and is unaffected by the above — both paths now exist side by side correctly

Still genuinely outstanding

1. The cancel confirmation is still a single-click confirm, not a typed-confirmation step (type “CANCEL” or their email). Worth deciding whether the current impact screen with a named list is sufficient friction, or whether typed confirmation is still wanted on top of it.
2. No contextual dashboard notice exists yet for a sub-member after they've actually lapsed (e.g. “Your membership via Sammy has ended”) — they currently just become a normal free user with no in-app explanation, only the email sent at cancellation time
3. Downgrade between two paid tiers (e.g. Family → Individual) has not been tested against this lifecycle at all — does switching tiers via the plans page correctly trigger the same sub-member detachment, or does it only happen on a genuine cancellation? This needs checking directly, not assumed.
4. No email is sent to the master themselves confirming the cancellation went through and listing who was affected — only the sub-members are emailed currently
5. No notification exists for a sub-member independently upgrading and leaving the group, or deleting their own account — the master is not told a seat has freed up in either case

Two separate real scripts exist for this, not one: bsm-delete-account-spa.php (self-delete, with a 4-step friction flow and a typed “DELETE” confirmation, already includes admin-self-deletion protection and a hard block on user ID 1) and bsm-admin-user-delete.php (an admin tool to delete any other user, with its own search-then-confirm flow and typed confirmation). Both were confirmed to have zero Stripe references before today's fix.

Built today

1. Both files now cancel any live Stripe subscription immediately (not at period end) before the data wipe runs — deletion is itself immediate and irreversible, so the subscription must end the same way, otherwise a card keeps being billed with no account behind it
2. The Stripe call is deliberately fire-and-forget: if it fails, the data wipe still proceeds, since the person has already confirmed deletion and a failed Stripe call becomes a billing support issue to chase afterwards, not a reason to block someone's own deletion request
3. bsm-admin-user-delete.php additionally now detaches every active sub-member if the deleted user was a master — clears parent_user_id and member_role on each sub-member's own GOD JSON before the master's row is wiped, identical to the logic already proven in the webhook's customer.subscription.deleted handler. Without this, a sub-member would be left pointing at a parent that no longer exists.
4. Added a visible impact summary to the admin's confirmation screen, shown before they commit: if the target has a live Stripe subscription, a note that it will be cancelled; if they're a master, the real names and emails of every active sub-member who will be detached
5. Self-delete (bsm-delete-account-spa.php) only ever affects the deleting user's own subscription — it has no sub-member detach logic, since a sub-member deleting themselves was already correctly understood to never cascade to anyone else (they were never the source of any group's paid status)

Still genuinely outstanding

1. Neither file sends any notification email on deletion — a master deleting their own account does not notify their sub-members the way cancellation now does (Section L); an admin deleting a master likewise sends nothing to affected sub-members
2. No notification to a master when a sub-member independently deletes their own account, even though that frees a seat
3. page-protect.php whitelist gap found and fixed for the delete-account page (see Section Q) — the real live slug is confirmed as account-delete-my-account (the older delete-account slug referenced elsewhere was a stale naming, now removed from the whitelist)

Built because the user explicitly does not want people leaving the site to manage cancellation. Both files are deliberately lightweight MVP versions — a single warning card with one confirm action — not the full heavyweight impact-screen/typed-confirmation flow described in Part 4 (Section L), which is still a separate future build item.

1. bsm-stripe-cancel.php (new file, /cancel-subscription/): single confirm screen, calls Stripe directly to set cancel_at_period_end: true on the user's subscription. Deliberately does not write GOD JSON itself — relies entirely on the webhook to record the change, so there is exactly one code path that ever writes subscription_cancelled_date. Checks the user's current tier's seat count and, if greater than zero, adds an explicit bolded warning that invited members will also lose access and need re-inviting.
2. bsm-stripe-undo-cancel.php (new file, /undo-cancel/): same lightweight pattern, calls Stripe to set cancel_at_period_end: false, again relies entirely on the webhook rather than writing GOD JSON directly.
3. bsm-stripe-webhook.php updated: the existing customer.subscription.updated handler did not previously read cancel_at_period_end at all, meaning it had no way to ever set subscription_cancelled_date at the moment of scheduling (only customer.subscription.deleted set it, which fires later at actual period end). Now reads cancel_at_period_end and sets/clears subscription_cancelled_date accordingly on every subscription update.
4. Real bug found and fixed: current_period_end does not exist at the top level of the subscription object in API version 2026-05-27.dahlia — it moved to items.data[0].current_period_end. The handler now reads it from the correct nested location (with a fallback to the old top-level location), which is what makes stripe_next_billing / “Active until [date]” actually populate.
5. Real bug found and fixed, unrelated to the above: a Post/Redirect/Get-style issue did not apply here directly, but a genuine deployment-confusion bug did — testing repeatedly showed stale wording (“reactivate”, “billing portal”) despite files being edited, which traced back to the live plans-page file simply never having been re-uploaded after the early steps of this build (only the two new cancel/undo-cancel files had been deployed; the plans-page swap was prepared but the walkthrough never reached it). Lesson: when live behaviour does not match the latest code, check the actual deployed file content directly before assuming a logic bug.
6. Plans page: removed a redundant warning (“Switching plans cancels your subscription…”) that was showing on every other tier's card regardless of relevance. The real warning now lives in exactly one place — the cancel confirmation screen itself, at the actual decision point.

Decision made: the Stripe billing portal is not for users at all going forward. Two of the three remaining functions moved fully on-site; the third (payment method) deliberately stays on Stripe's hosted flow, not as an oversight but as a considered choice.

1. bsm-billing-history.php (new file, /billing-history/): read-only invoice list, calling GET /v1/invoices?customer={id} via the same Stripe GET helper pattern already proven in the webhook. Shows date, description, amount, status badge, and a direct PDF download link per invoice. No write operations of any kind — lowest-risk of the three builds. Live-tested with two real invoices on Sammy's account, both displaying correctly with working downloads.
2. bsm-update-details.php (new file, /update-details/): updates name and email in three places together on save — the WordPress user record, GOD JSON (first_name/email), and Stripe's customer record if one exists. Deliberately fire-and-forget on the Stripe write: if that call fails, the save still succeeds (WordPress and GOD JSON are correct, which is what the user actually sees) and an amber warning notes the Stripe side will be corrected separately, rather than blocking the whole save over a third-party hiccup. Live-tested: name change saved and persisted correctly on reload.
3. Payment method update deliberately stays on the Stripe portal, not moved on-site. Reasoning: Stripe Elements already keeps raw card data off the server entirely (the card field is a Stripe-hosted iframe regardless of where it's embedded), so building it “on-site” would not actually reduce risk — it would only add maintenance burden (Stripe JS SDK upkeep) and reinvent edge cases (3D Secure, declined updates, expired cards) that Stripe's own hosted flow already handles. This was a considered decision, not the leftover default.
4. account_page_index.php updated: the old single “Manage billing” link is now three distinct links — “View invoices” → /billing-history/, “Update my name or email” → /update-details/, “Update payment method” → /billing-portal/ (explicitly labelled “via Stripe” so it reads as a deliberate choice, not an unfinished link)
5. page-protect.php whitelist updated proactively with billing-history and update-details before either was tested, rather than waiting for the same redirect bug found twice already today (Section Q) to surface a third time

A separate standalone HTML document, built for a non-technical new employee with no programming background, who needs to understand and operate the membership system day to day. Not part of this developer-facing guide — a different document with a different audience.

1. Plain-language explanation of how memberships work: free vs paid, master/primary vs sub-member, what a seat is
2. A definitive feature-by-tier comparison table, with every main feature broken into its real sub-features, each carrying its own Free/Paid status — including the two genuine split cases (Wellness Channel: rotating selection on Free vs full permanent access on Paid; AI Cheat Foods: capped at 3 on Free vs unlimited on Paid). Built from three cross-checked sources: the investor/marketing plan, a separate Product Knowledge Reference document, and the onboarder’s own drip-content panels — not invented.
3. A companion Product Knowledge Reference document holding the deeper “how it works” explanations (the wholefood database, the AI Cheat System’s photo-scoring, the four Neuro States, the Wellness/Busy/Fun/Recovery Day model) as a shared source of truth, written neutrally enough to later feed a Katie AI knowledge base without rewriting the underlying facts
4. A dedicated section on the membership CRUD (the internal Stripe-driven admin panel) explicitly separating what it can edit (name, description, seats, featured, order) from what it cannot (creating a new plan, changing a price — both of which must happen in Stripe’s own dashboard first, then synced)
5. Common support scenarios written as real questions (“I invited someone but they say they never got the email”), each with a plain explanation followed by an explicit numbered click-path
6. One explicit open gap logged honestly rather than guessed at: there is currently no documented way for staff to look up and open a specific customer’s account by name or email. Flagged in three places in the document (contents, a warning box in the relevant section, and the changelog) rather than invented.

Found through real testing, not code review: a sub-member email pointed correctly at /plans-page/, but clicking it sent a free user to /upgrade-page/ instead. Both bsm-plans-page.php and account_page_index.php were deliberately built to handle free users gracefully (each has its own if ($user_status === 'paid') branching with a correct free-user view) — but page-protect.php’s whitelist model intercepts every request before either file ever runs, and neither slug was in its $free_slugs array. Every free user hitting either page was redirected to /upgrade-page/ before the page-level free-user logic ever had a chance to render.

1. Added plans-page and account to the $free_slugs whitelist in page-protect.php
2. No change needed to bsm-plans-page.php or account_page_index.php themselves — their free-user views were already correct, they just couldn't be reached
3. Confirmed live: a real sub-member (William, free tier) clicking his cancellation-notice email link now lands on /plans-page/ showing “Choose your plan” with no current-plan/cancelling block, instead of being redirected to /upgrade-page/

Second real occurrence, same day

The predicted sweep above turned out to be necessary almost immediately: the “Delete account” button on the account page links to /account-delete-my-account/, which was also missing from $free_slugs, causing the exact same symptom — clicking it redirected to /upgrade-page/ instead of reaching the delete flow. Added account-delete-my-account (the confirmed real slug), cancel-subscription, undo-cancel and manage-sub-members to the whitelist in the same pass, since all four follow the identical pattern and were equally unconfirmed rather than waiting for each to surface as its own bug report. The older delete-account slug referenced in earlier sessions was stale naming and has been removed from the whitelist.