Capability status

B2B Edition support — variant detection + admin enrollment (Epic 22, called "Phase 2 planned" by stale audit)

PR #547 (admin enrollment) + PR #548 (storefront detection)

DSAR endpoint — per-customer export + erasure (Epic 28, called "Phase 2 planned" by stale audit)

PR #546

BigEng Slices B/C/D shipped — typed errors + schema retrofit + audit decorator (called "in flight" by stale audit)

PRs #542 (B) + #543 (C) + #545 (D)

Phase 2 GCP Terraform scaffold (called "Phase-2 candidate / future" by stale audit; in flight now)

PR #561

idempotency_keys ledger table for request-level idempotency (Hive #581)

Hive #581

Middleware reads Idempotency-Key header, caches mutation responses, returns 409 on fingerprint mismatch

Hive #581

OpenAPI 3.0 spec at apps/api/openapi.yaml (Hive #580)

Hive #580

GET /docs Swagger UI handler exists (Hive #580) — route mount in worker.ts required

Hive #580

24h TTL cleanup cron for idempotency_keys table

Hive #581

CI gate validates OpenAPI spec on PRs touching API or spec (Hive #580)

Hive #580

charges table — first-class entity for each subscription billing attempt

BRD.md §Epic-10 (charge scheduling), §Epic-11 (dunning), §Epic-12 (refunds)

customers table — mirror of BC customers with subscription-specific fields (payment_customer_ref, consent_metadata)

BRD.md §Epic-1 (BC customer identity), §Epic-19 (PM management depends on customers FK)

payment_methods table — gateway-tokenized PMs with NTI (Network Transaction ID) for MIT credential continuity

BRD.md §Epic-19 (subscriber PM management), §D17 PRD-COMPANION (MIT/NTI)

reconciliation_runs table — observability for the periodic reconcile sweep

BRD.md §Epic-13 (reconciliation), migration 0013

Dependabot configured for weekly dependency updates across all workspaces

Hive #582 / test-stack-baseline skill

Gitleaks CI workflow scans every PR for secrets; allowlist documented

Hive #582 / test-stack-baseline skill

CHANGELOG.md exists at repo root

Hive #586

Workflow auto-generates changelog drafts on tag push

Hive #586

Successful OAuth callback creates stores row with encrypted access token and emits store.installed

BRD.md §US-1.1: Given I click "Install" from the BC Marketplace, When BC redirects with code/scope/context, Then we exchange the code for an access token and persist encrypted credentials

OAuth handshake failure shows descriptive error message; BC does not show app as installed. SetupError admin page surfaces partial-failure recovery for the post-OAuth scenarios (extension_scope_missing, webhook_register_5xx, scope_drift, duplicate_install).

BRD.md §US-1.1: Given the install fails mid-flight, When the handshake errors out, Then the merchant sees a descriptive message and the BC side does not show the app as installed

Valid signed_payload_jwt on /api/load mints session cookie: httpOnly, Secure, SameSite=none, Partitioned

BRD.md §US-1.2: Given I click the app icon in BC, When BC redirects to /api/load?signed_payload_jwt=..., Then we verify the JWT and mint an internal session cookie

Malformed or wrong-secret JWT returns 401 and does not set a cookie

BRD.md §US-1.2: Given the JWT is malformed or signed with a wrong secret, When verification fails, Then we return 401 and do not set a cookie

Install callback issues GraphQL createAppExtension mutations for PANEL context on Orders, Products, and Customers models

BRD.md §US-1.3: Given the OAuth handshake completes, When the install callback finishes, Then we issue GraphQL createAppExtension mutations for PANEL context on Orders, Products, and Customers models

Reinstall extension conflict (extension already exists) is detected and skipped gracefully

BRD.md §US-1.3: Given an extension already exists (reinstall), When we try to create it, Then we detect the conflict and skip gracefully

Install registers store/order/*, store/cart/*, store/customer/*, store/product/*, store/app/uninstalled webhook subscriptions

BRD.md §US-1.4: Given install completes, When we subscribe to webhooks, Then store/order/*, store/cart/*, store/customer/*, store/product/*, store/app/uninstalled are all registered

Uninstall webhook verifies signed payload, revokes credentials, deregisters extensions, pauses all active subscriptions

BRD.md §US-1.5: Given I uninstall from BC, When BC POSTs to /api/uninstall, Then we verify the signed payload, revoke credentials, deregister extensions, and pause all active subscriptions

Subscription data retained 30 days after uninstall for potential reinstall recovery

BRD.md §US-1.5: Given subscriptions exist on uninstall, When uninstall processes, Then we retain subscription data for 30 days for potential reinstall recovery

After 30 days post-uninstall without reinstall, subscriber PII is hard-deleted, only anonymized revenue records retained

BRD.md §US-1.5: Given 30 days pass post-uninstall without reinstall, When the retention window closes, Then we hard-delete subscriber PII and retain only anonymized revenue records

Every successful /api/load JWT verify upserts a users row keyed by (store_hash, bc_user_id) with email, is_owner, first_seen_at, last_seen_at

BRD.md §US-1.6: Given a successful signed_payload_jwt verify on /api/load, When we extract user.{id, email}, Then we upsert a users row keyed by (store_hash, bc_user_id)

Mutating events carry actor_user_id from session JWT; system events carry null actor_user_id with actor_kind set

BRD.md §US-1.7: Given a session-authenticated mutating call, When we write the change, Then the resulting events row carries actor_user_id resolved from the session JWT

Processor setup page pre-selects and marks "BC Payments" as Ready when BC Payments is enabled on the store

BRD.md §US-2.1: Given I open the processor setup page, When BC Payments is enabled on my store, Then "BC Payments" is pre-selected and marked "Ready"

When BC Payments is not enabled, shows "Enable BC Payments" link to BC onboarding flow

BRD.md §US-2.1: Given BC Payments is not enabled, When I view the page, Then I see an "Enable BC Payments" link to BC's own onboarding flow

Selecting Stripe and clicking Connect redirects through Stripe Connect OAuth and returns with stripe_account_id attached

BRD.md §US-2.2: Given I pick "Stripe" on the processor page, When I click "Connect," Then I am redirected through Stripe Connect OAuth and returned with an attached stripe_account_id

Successful Stripe connection shows "Connected" state with last 4 of account name and a "Test charge" button

BRD.md §US-2.2: Given the connection succeeds, When I return, Then I see "Connected" with the last 4 of my Stripe account name and a "Test charge" button

Access revoked in Stripe is detected and prompts re-auth in our app

BRD.md §US-2.2: Given I revoke access in Stripe, When I return to our app, Then we detect the disconnection and prompt re-auth

Install-time compatibility detection lists active BC payment methods with Supported/Supported in Phase 2/Not supported badges

BRD.md §US-2.3: Given I complete install, When the processor-detection step runs, Then it lists my active BC payment methods with each marked "Supported," "Supported in Phase 2," or "Not supported"

When none of merchant's active gateways are MVP-supported, shows three options: switch to BC Payments, add Stripe, or decline install

BRD.md §US-2.3: Given none of my active gateways are MVP-supported, When I reach the setup screen, Then I see three explicit options: switch to BC Payments, add Stripe, or decline install

When BC Payments is detected but Stored Payments is not enabled, ConnectProcessor wizard shows an orange warning banner with a link to gateway settings

BRD.md §US-2.3 / ADR-0037 (P-comp Sub-B): stored payments enablement check in auto-detect

Test mode toggle routes subscription charges to processor sandbox without debiting real cards

BRD.md §US-2.4: Given I toggle "Test mode" on, When I create a subscription, Then charges route to the processor's sandbox and no real card is debited

Test-mode charges generate BC orders tagged with [TEST] in staff_notes and filterable in merchant dashboard

BRD.md §US-2.4: Given test-mode charges succeed, When they generate BC orders, Then the orders are tagged with [TEST] in staff_notes

Toggling test mode off with active test subscriptions prompts merchant to archive them before going live

BRD.md §US-2.4: Given I toggle test mode off, When I have test subscriptions active, Then I am prompted to archive them before going live

Processor 401/403 or account suspension turns health badge red and emails merchant contact; recovery auto-restores green

BRD.md §US-2.5: Given a processor is connected, When its API returns 401/403 or the account is suspended, Then our health badge turns red and an email goes to the merchant contact

Merchant can connect multiple processors and route subscriptions by channel or currency

BRD.md §US-2.6: Given I add a second processor, When I save, Then I can designate one as default and assign others to specific channels or currencies

Setup checklist surfaces a capture-timing summary card with current setting, link to Payment Settings (US-10.9), and Phase 1 advisory note; EU stores see a compliance highlight

BRD.md §US-2.7: Given I complete processor onboarding, When I reach the final setup-checklist step, Then a capture-timing summary card is shown with current setting, link to Payment Settings, and Phase 1 advisory note

Recharge CSV export upload triggers row-by-row validation and creates subscriptions; RechargeAdapter implements MigrationSourceAdapter

BRD.md §US-3.1: Given I upload a Recharge CSV export, When I map fields in the wizard, Then the system validates row-by-row and shows pass/fail counts

Cross-gateway PM flag surfaced as edge_pm_revault_required audit event; revault required for non-bc_payments gateways

BRD.md §US-3.2: Given I import a Recharge export, When Recharge gateway token is not bc_payments, Then we flag pm_revault_required

Imported next_charge_at preserved exactly; imported subscription status=active; cron picks up on normal schedule

BRD.md §US-3.3: Given the import includes next_charge_at, When I activate post-migration, Then no charge is scheduled earlier than the imported date

PayWhirl CSV source selection auto-defaults field mappings to PayWhirl schema; plan-to-product mappings surfaced for confirmation

BRD.md §US-3.4: Given I pick "PayWhirl" as the source, When I upload their CSV, Then field mapping defaults match PayWhirl's schema

Bold Subscriptions v1 (Recurring Orders) and v2 adapters implement MigrationSourceAdapter with six-state machine and edge case flagging

BRD.md §US-3.5: Given I pick the respective source, When I upload the export, Then vendor-specific field mappings are applied

dry_run=true on import endpoint returns per-row outcomes without DB writes; base class respects ctx.dryRun at write()

BRD.md §US-3.6: Given I upload an export, When I click "Dry run," Then the system simulates the import

POST /api/v1/admin/subscriptions/import — batch import; per-row idempotency via external_id; JSON + NDJSON; dry_run support

BRD.md §US-3.1/3.6: batch import with dry-run, per-row failure isolation, dedup via external_id

Subscriptions App Extension panel appears on BC product edit page showing plan status, intervals, pricing, eligibility

BRD.md §US-4.1: Given I open any BC product, When the product edit page renders, Then the "Subscriptions" App Extension panel appears

When no plan is configured, clicking the panel opens the plan wizard via a "Configure subscription plan" CTA

BRD.md §US-4.1: Given no plan is configured, When I click the panel, Then a "Configure subscription plan" CTA opens the plan wizard

Plan wizard has steps: Interval → Pricing → Options → Eligibility → Review

BRD.md §US-4.2: Given I click "Configure," When the wizard opens, Then it has steps: Interval(s) → Pricing → Optional extras → Eligibility → Review

Completing wizard and clicking Activate saves the plan and makes the product subscribable

BRD.md §US-4.2: Given I complete all steps, When I click "Activate," Then the plan is saved, the product is flagged subscribable, and the storefront widget renders on the PDP

Variant eligibility step shows all variants with checkboxes, defaulting to all eligible

BRD.md §US-4.3: Given a product has multiple variants, When I reach the eligibility step, Then I see all variants with checkboxes, defaulting to "all eligible"

Unchecked variant in eligibility step causes storefront widget to hide subscribe option for that variant

BRD.md §US-4.3: Given I uncheck a variant, When I activate, Then the storefront widget hides the subscribe option for that variant

Deactivating an active plan warns about active subscribers and offers: stop new signups / end at next cycle / cancel all immediately

BRD.md §US-4.4: Given a plan is active, When I click "Deactivate," Then I am warned about active subscribers and asked to choose

"Stop new signups" hides storefront widget but existing subscriptions continue unaffected

BRD.md §US-4.4: Given I choose "Stop new signups," When the change saves, Then the storefront widget disappears but existing subs continue unaffected

Copy plan to multiple products via multi-select with search

BRD.md §US-4.5: Given a plan exists on product A, When I click "Copy to products," Then I select target products via multi-select

Confirming copy shows summary of successful/failed copies and conflicts

BRD.md §US-4.5: Given I confirm the copy, When the operation completes, Then I see a summary of successful/failed copies and any conflicts

Plan supports any combination of every N days/weeks/months (N ≤ 24) intervals

BRD.md §US-5.1: Given plan design, When I add intervals, Then I can specify any combination from: every N days/weeks/months (N ≤ 24)

Multiple configured intervals shown as dropdown/radio on PDP with per-interval savings indication

BRD.md §US-5.1: Given multiple intervals are configured, When a subscriber reaches PDP, Then a dropdown/radio shows all options with per-interval savings indication

Fixed discount % pricing computes renewal charge as current_catalog_price * (1 - discount/100)

BRD.md §US-5.2: Given I select "Fixed discount %" and enter 10, When a subscriber renews, Then the renewal charge is computed as current_catalog_price * 0.9 per unit

Catalog price changes flow through to next renewal (unless lock-at-creation enabled)

BRD.md §US-5.2: Given the catalog price changes, When the next renewal runs, Then the renewal uses the new base price

Price List strategy reads charge amounts from the BC Price List for the subscriber's variant at renewal

BRD.md §US-5.3: Given I select "Price List" and pick one, When subscribers renew, Then charge amounts are read from the Price List's price for their variant

Deleted or archived Price List triggers exception queue entry for merchant attention at renewal

BRD.md §US-5.3: Given the Price List is deleted or archived in BC, When the renewal runs, Then the charge goes into the exception queue for merchant attention

Fixed price strategy charges the configured absolute amount regardless of catalog changes

BRD.md §US-5.4: Given I select "Fixed price" and enter amount + currency, When renewals run, Then the charge amount ignores catalog changes

Trial of N days skips or discounts first charge and schedules second charge at N + interval days

BRD.md §US-5.5: Given I enable a trial of N days, When a subscriber signs up, Then the first charge is skipped (free trial) or discounted (paid trial) and the second charge is scheduled N + interval days out

Cancelling during trial results in no charge and no cancel penalty

BRD.md §US-5.5: Given a trial is active, When a subscriber cancels before the trial ends, Then no charge occurs and no cancel-penalty applies

Invalid payment method when trial ends triggers standard dunning on first full charge

BRD.md §US-5.5: Given a trial ends and payment method is invalid, When the first full charge runs, Then standard dunning applies

trial.ending_soon notification is sent exactly once per trial (idempotency guard prevents re-emission on every cron tick)

BRD.md §US-5.5: T-3 notification fires once; scheduler idempotency via trial_ending_soon_sent sentinel column

Lock-price-at-creation snapshots locked_price_cents on subscription record; renewals use snapshot regardless of catalog changes

BRD.md §US-5.6: Given I enable "Lock price at creation" in plan settings, When a new subscription starts, Then locked_price_cents is snapshotted on the subscription record

Minimum cycles commitment shown in widget; cancel flow blocked or shows early-termination notice

BRD.md §US-5.7: Given I configure min_cycles: 6, When a subscriber signs up, Then they are shown "Requires 6-cycle commitment" in the widget

Plan-level commitment_cycles drives subscription.lock_expires_at computation; cancel-lock-policy service returns locked + lock_expires_at; portal cancel route returns 409 conflict with lock_expires_at while locked

BRD.md §US-5.8: Given I set minimum_term_cycles on a plan with early_cancel_policy: block, When a subscriber signs up, Then lock_expires_at is computed and stored; cancel attempts during lock window return 409.

plans.billing_anchor_month + billing_anchor_day power calendar-anchored renewals; scheduler reads anchor columns to converge next_charge_at to the configured anchor date

BRD.md §US-5.9: Given I enable calendar anchoring on a plan, When a subscriber signs up, Then their next_charge_at is computed as the nearest future anchor date; existing subscribers on the plan converge to the anchor.

Gift-giver pays upfront for N cycles; recipient gets reveal email; claiming creates subscription in recipient's BC account with no PM required

BRD.md §US-6.1: Given a subscribable product and a "Gift this subscription" toggle, When I pick it and enter recipient info, Then I pay upfront for N cycles and the recipient receives a gift-reveal email

Recipient gift-reveal link claims gift and creates subscription with cycles_prepaid counting down from N

BRD.md §US-6.1: Given the gift recipient clicks the reveal link, When they claim the gift, Then a subscription is created in their BC customer account with no payment method required and cycles counting down from N

Recipient explicitly opts in to convert gift sub to paid after all gift cycles ship (FTC Negative Option: silence = lapse, never auto-convert)

BRD.md §US-6.1 AC4: recipient POST /portal/subscriptions/:id/gift-convert with consent:true; convert_consent_at recorded; lapse sweep keys on this field

Prepaid checkout collects full period amount in one charge; prepaid_cycles_remaining tracked; BC orders created per cycle with captured payment

BRD.md §US-6.2: Given a plan with prepaid options, When I check out with "6 months prepaid," Then a single charge collects the full period amount

Prepaid period end prompts subscriber to renew or lapse; no dunning during prepaid window

BRD.md §US-6.2: Given the prepaid period ends, When the next cycle would occur, Then I am prompted to renew or let it lapse

Build-a-box plan with box_size, eligible_products, customization_window; subscriber picks items; previous composition rolls forward if not customized

BRD.md §US-6.3: Given a build-a-box plan with box_size, When I sign up, Then I pick my initial items from the set

Bundle plan generates single BC order per cycle with all bundle SKUs at bundle discount; OOS SKU flags exception queue

BRD.md §US-6.4: Given I configure a bundle plan with fixed composition, When a subscriber signs up, Then each cycle generates a single BC order with all bundle SKUs at the bundle discount

Membership plan creates Entitlement rows per configured key; PENDING→ACTIVE on charge success; ACTIVE→SUSPENDED on dunning exhausted; SUSPENDED→ACTIVE on recovery; terminal REVOKED on cancel

BRD.md §US-6.5: Given a "Membership" plan type with entitlements, When a subscriber signs up, Then one Entitlement row is created per configured key with status=pending

Usage-based plan accumulates meter units per cycle via API; cycle charge = sum(usage) * price_per_unit + fixed base

BRD.md §US-6.6: Given a usage-based plan with meter_name and price_per_unit, When subscribers report usage, Then usage accumulates per cycle

Curated plan pulls merchant-selected or rule-selected SKU per cycle honoring subscriber preferences

BRD.md §US-6.7: Given a "Curated" plan with merchant-configured rotation rules, When each cycle runs, Then the merchant-picked SKU is included in the BC order

Active subscriber earns merchant-configured credit on referral first-charge success; credit applied to next charge; fraudulent referrals reversed

BRD.md §US-6.8: Given I have an active subscription, When a referred user signs up through my link and their first charge succeeds, Then I earn merchant-configured credit applied to my next charge

allotment_grants table tracks recurring quota per customer/org with current_balance, refresh_cadence, rollover_policy; allotment_debits links to BC orders or Charges

BRD.md §US-6.9: Given I create an AllotmentGrant, When I issue it to a customer, Then a grant row is created with current_balance = amount_per_period and next_refresh_at set per cadence

actors table with owner/payer/beneficiary/manager/org_admin roles; payer PM used for renewals; beneficiary gets delivery notifications; manager cc'd on dunning

BRD.md §US-6.10: Given a subscription is created, When persisted, Then an actors row is written for at least the owner role; payer.role is unique-per-subscription

custom_field_definitions table per plan/subscription/grant with scope, key, type, required, validation_regex, subscriber visibility; 422 on missing required field

BRD.md §US-6.11: Given I configure a CustomFieldDefinition, When I save, Then the field appears in admin/storefront UI immediately

Plan with channel_ids restricts widget rendering and subscription creation to allowed BC channels; channel_id stamped on subscription

BRD.md §US-7.1: Given a plan has channels: [1, 2], When a subscriber browses channel 3, Then the subscription widget does not render on that product's PDP

Plan with customer_groups restricts widget to matching groups; grandfathering/cancel/pause behavior on group-loss is merchant-configurable

BRD.md §US-7.2: Given a plan has customer_groups: [vip], When a non-VIP subscriber reaches the PDP, Then the subscription widget does not render

Plan with country_codes restricts storefront plan discovery to subscribers in allowed countries; country_code stamped on subscription from BC order billing_address

BRD.md §US-7.3: Given a plan has allowed_countries: [US, CA], When a subscriber enters a shipping address outside the allowed list, Then checkout blocks with a clear message

Plan with price_list_ids restricts storefront plan discovery to customers whose active price list is in the allowed set; BC native Price List resolution order for multi-list membership is Phase 3

BRD.md §US-7.4: Given a plan pricing strategy is "Price List" and a customer belongs to multiple Price Lists, When a charge computes, Then BC's native Price List resolution order is respected

Admin GET /api/v1/admin/plans/:id/coverage returns scoping rollup (channels × customer_groups × countries × price_lists); admin Coverage.tsx renders the matrix

BRD.md §US-7.5: Given I open "Plan coverage" in the admin, When it loads, Then I see a matrix of channels × customer groups × countries with count of applicable plans per cell

Stencil PDP widget renders: one-time/subscribe radio, interval dropdown, savings indication, next-charge preview

BRD.md §US-8.1: Given a subscribable product and a Stencil theme, When I load the PDP, Then a widget renders with: "One-time purchase" vs. "Subscribe and save" radio, interval dropdown, savings indication, and next-charge preview

Picking "Subscribe" and adding to cart injects subscription intent custom fields on the cart line-item

BRD.md §US-8.1: Given I pick "Subscribe," When I add to cart, Then the cart line-item carries subscription intent custom fields

Mixed cart shows subscription items with distinct badge, interval label, and "Remove subscription commitment" shortcut

BRD.md §US-8.2: Given my cart contains both subscription and one-time items, When the cart renders, Then subscription items show a distinct badge, interval label, and "Remove subscription commitment" shortcut

Changing subscription line quantity or interval in cart updates the line-item custom fields

BRD.md §US-8.2: Given I change a subscription line's quantity or interval in cart, When the cart updates, Then the line-item custom fields update accordingly

useSubscriptionOptions(productId) returns { intervals, pricingPreview, eligibility }

BRD.md §US-8.3: Given I install @bc-subscriptions/react, When I call useSubscriptionOptions(productId), Then I get { intervals, pricingPreview, eligibility }

addSubscriptionToCart updates BC cart with correct line-item custom fields

BRD.md §US-8.3: Given I call addSubscriptionToCart({ productId, variantId, intervalKey }), When it resolves, Then the BC cart is updated with correct line-item custom fields

Eligibility failure (customer group, region, channel) returns typed ineligibility reason from hook

BRD.md §US-8.3: Given eligibility fails, When I call the hook, Then I receive a typed ineligibility reason

Widget reads --color-primary, --font-body theme CSS variables on mount; falls back to neutral defaults when absent

BRD.md §US-8.4: Given a Stencil theme with standard CSS variables, When the widget mounts, Then it reads --color-primary, --font-body etc. and uses them

Merchant-created copy variant shown 50/50 by subscriber session with conversion rate and confidence reporting

BRD.md §US-8.5: Given I create a copy variant in admin, When the widget renders, Then it splits 50/50 between control and variant by subscriber session

Webcomponent IIFE bundle is published to a reachable CDN (bc-subscriptions-cdn.pages.dev/v1/) and the API + admin reference that URL consistently

Hive #1149 Option B-pages — Cloudflare Pages-served distribution until cdn.subscriptions.bigcommerce.com is delegated.

Education panel expands to show FAQ items (Cancel anytime, Change cadence, Skip); dismissal remembered per session

BRD.md §US-8.6: Given a merchant-enabled education panel, When I expand it on the widget, Then I see short FAQ items with icons

Subscription add-to-cart sets line_item.custom_fields with {sub_plan_id, sub_interval_key, sub_quantity}

BRD.md §US-9.1: Given a subscriber adds a subscription item, When the cart POST fires, Then line_item.custom_fields includes {sub_plan_id, sub_interval_key, sub_quantity}

Cart quantity edit keeps custom fields consistent with subscription intent

BRD.md §US-9.1: Given the subscriber edits quantity in cart, When the line updates, Then custom fields stay consistent

store/order/created webhook creates Subscription row (status: active) with cycle-0 charge marked succeeded, bc_order_id set

BRD.md §US-9.2: Given a new order contains a line with sub_plan_id, When the webhook processes, Then a Subscription row is created with status active, first charge marked succeeded with bc_order_id of the triggering order

Order with multiple subscription items creates one Subscription per item

BRD.md §US-9.2: Given the order contains multiple subscription items, When processing, Then one Subscription per item is created

Order with missing or deactivated plan flags the order in the exception queue without blocking BC checkout

BRD.md §US-9.2: Given the order creation fails our validation (missing plan, deactivated plan), When processing, Then we flag the order in the exception queue without blocking the BC checkout

Thank-you page JS detects subscription intent from sessionStorage and POSTs to fallback endpoint if custom fields absent from order

BRD.md §US-9.3: Given an order is created without subscription custom fields, When our thank-you-page JS detects the subscriber intended a subscription (from pre-checkout session storage), Then it POSTs to our fallback endpoint

Successful fallback links the subscription to the just-created order

BRD.md §US-9.3: Given the fallback triggers, When it succeeds, Then the subscription is linked to the just-created order

Fallback timeout or error shows subscriber clear message with support link

BRD.md §US-9.3: Given the fallback fails, When it times out or errors, Then the subscriber sees a clear message with a support link

Mixed checkout produces order with both item types; only subscription lines create Subscription rows

BRD.md §US-9.4: Given a mixed cart, When checkout completes, Then the order contains both item types and only the subscription lines create Subscription rows

Merchant using incompatible third-party checkout sees dashboard banner with named fallback options

BRD.md §US-9.5: Given the merchant uses a third-party checkout that doesn't support line-item custom fields, When they install, Then the dashboard shows an "Incompatible checkout" banner

At order/created, a consent-bearing intent persists an immutable consent_record and the subscription is active; a consent-less intent (when the merchant has enabled per-store enforcement) creates the subscription paused — not chargeable — with a consent_missing signal. Recording is additive/always-on; the pause is opt-in (require_subscribe_consent, ADR-0079).

BRD.md §US-9.6: Given consent is captured, When the subscription is created, Then a consent record is persisted (disclosed terms, timestamp, actor); and a subscription cannot run the recurring MIT without captured affirmative consent

Scheduler queries charges with status=scheduled AND scheduled_at <= now() + 15min and enqueues each; already-processing charges not re-enqueued

BRD.md §US-10.1: Given a Vercel Cron runs every 15 minutes, When it fires, Then it queries charges with status=scheduled AND scheduled_at <= now() + 15min and enqueues each into Vercel Queue

Charge executor acquires Redis lock on charge.id (5-min TTL) and sets status=processing before dispatching to processor

BRD.md §US-10.2: Given a charge is dequeued, When the workflow starts, Then it acquires a Redis lock on charge.id (5-min TTL) and sets status=processing

Processor called with idempotency key = charge.id; same key presented twice returns same result without double-charging

BRD.md §US-10.2: Given the workflow calls the processor with idempotency key = charge.id, When the same key is presented again, Then the processor returns the same result without double-charging

Mid-flight workflow crash resumes from last completed step using durable workflow state

BRD.md §US-10.2: Given the workflow crashes mid-flight, When it restarts, Then it resumes from the last completed step using the workflow's durable state

Next charge scheduled at anchor_date + N×interval; handles month-length edge cases (Jan 31 + 1mo = Feb 28/29)

BRD.md §US-10.3: Given a monthly subscription with anchor_date = 2026-04-10, When cycle N closes, Then the next charge is scheduled at anchor_date + N months with month-length edge case handling

Charge that retries and succeeds late still schedules next charge at original anchor, not late completion time

BRD.md §US-10.3: Given a charge retries and succeeds late, When it resolves, Then the next charge is still anchored to the original schedule

Time-of-day component of scheduled charge derived from deterministic hash of subscription.id to distribute load across 24h

BRD.md §US-10.4: Given a subscription's anchor_date is set, When scheduling, Then the time-of-day component is deterministically derived from a hash of subscription.id

Pausing for N days shifts next_charge_at by exactly N days and all future scheduled charges shift accordingly

BRD.md §US-10.5: Given an active subscription with next_charge_at = T, When I pause for 14 days, Then next_charge_at moves to T+14d and all future charges shift accordingly

Un-pausing early snaps schedule back to closest future anchor interval

BRD.md §US-10.5: Given I un-pause early, When I resume, Then the schedule snaps back to the closest future anchor interval

Subscription detail shows next 5 upcoming charges with date, estimated amount, and status

BRD.md §US-10.6: Given I open a subscription detail, When the upcoming-charges panel renders, Then it lists the next 5 charges with date, amount (estimated), status

Subscriptions created with future starts_at land in status="pending_start"; scheduler's processPendingStarts scan flips them to active when starts_at <= now and emits subscription.activated with reason=starts_at_reached

BRD.md §US-10.7: Given a subscriber selects a future start date at checkout, When starts_at <= now, Then the deferred-activation scan transitions the subscription to active, enqueues first charge, and anchor_date is initialized from starts_at.

Mid-year sign-ups on calendar-anchored plans pay a prorated first charge for the partial period; plans.proration_policy controls proportional vs skip_stub behaviour

BRD.md §US-10.8: Given an annual plan with billing_anchor_month/day set, When a subscriber signs up mid-year, Then the first charge is prorated as (days_to_anchor / 365) × annual_price; proration_policy=skip_stub bypasses stub cycles within 7 days of the anchor.

stores.capture_timing column persists merchant choice (immediate / on_fulfillment / on_ship); PaymentSettings admin UI renders dropdown + Phase 1 advisory banner + EU compliance note; capture-timing-resolver service surfaces effective mode for Phase 2 enforcement

BRD.md §US-10.9: Given I open Payment Settings, When I select capture_timing, Then it persists and an advisory banner explains Phase 1 = display-only / Phase 2 = enforced; EU stores see a compliance prompt.

Merchant can configure retry intervals, on_exhaustion behavior, and grace period in dunning settings

BRD.md §US-11.1: Given I open dunning settings, When I edit the policy, Then I can set: retry intervals, on_exhaustion, grace period

Saved dunning policy applies to new charge scheduling

BRD.md §US-11.1: Given I save the policy, When new charges are scheduled, Then retries follow the new policy

Failed charge with soft decline schedules retry per policy next interval

BRD.md §US-11.2: Given a charge fails with a soft decline, When the workflow branches to dunning, Then it schedules a retry per the policy's next interval

Failed charges retry up to 3 times with 1h/4h/24h exponential backoff (ADR-0011 gap 1)

BRD.md §US-11.2 / ADR-0011 §5: retry curve 1h/4h/24h; idempotency key stable across retries; after 3 failures → failed_permanently + exception queue entry

When all retries exhaust, subscription transitions per on_exhaustion policy and final email sends

BRD.md §US-11.2: Given all retries exhaust, When the on_exhaustion action triggers, Then subscription transitions to cancelled/paused per policy and a final email goes out

Hard decline codes result in no further retries, subscription moves to past_due with subscriber notification

BRD.md §US-11.3: Given a processor returns a hard decline code, When classified by the adapter, Then no further retries are scheduled

Soft decline (insufficient funds, network timeout) proceeds to retry per policy

BRD.md §US-11.3: Given a processor returns a soft decline (insufficient funds, network timeout), When classified, Then retries proceed per policy

Adapter normalizes mitContext to processor-specific indicator (BC Payments MREC flag, Stripe mit_exemption, Braintree transactionSource)

BRD.md §US-11.3: Given a charge dispatch carries mitContext, When the adapter handles it, Then the adapter normalizes the context to its processor-specific indicator

Expired/replaced cards auto-updated via network services (Visa VAU, Mastercard ABU) without triggering dunning

BRD.md §US-11.4: Given the processor supports Automatic Card Updater, When a card is replaced by the issuer, Then stored PM details update automatically

Subscriber updating PM during dunning resets retry counter to 0 and enqueues retry within 1 minute

BRD.md §US-11.5: Given my charge has failed and I am in dunning, When I update my PM via the portal, Then the retry counter resets to 0 and a retry is enqueued within 1 minute

Email sent when retry fails and next retry is >24h away, with what went wrong, next retry time, and PM update CTA

BRD.md §US-11.6: Given a retry fails, When the next retry is scheduled > 24h out, Then an email is sent with: what went wrong, when the next retry is, a CTA to update PM

SMS sent when retry is imminent (<6h) for opted-in subscribers with PM update link

BRD.md §US-11.6: Given I have opted in to SMS, When a retry is imminent (< 6h), Then an SMS is sent with the update-PM link (P2)

Daily merchant digest of subscribers in dunning, sorted by MRR desc with attempt count and days-in-dunning

BRD.md §US-11.7: Given subscribers are in dunning, When the daily digest fires, Then it lists them by MRR desc, shows attempt count, days in dunning

Full or partial charge refund issued via processor adapter; BC order status updated; Event written; charge marked refunded

BRD.md §US-12.1: Given I click "Refund" on a succeeded charge, When I enter amount and reason, Then the refund is issued via the processor adapter

Store credit balance reduces next charge amount; remainder rolls forward; credit balance decremented atomically with charge decrement

BRD.md §US-12.2: Given I issue $10 store credit to a subscriber, When the next charge runs, Then the charge amount is reduced by up to $10 and the credit balance decrements

Skip next charge marks upcoming charge abandoned with reason=skipped and advances next_charge_at by one interval

BRD.md §US-12.3: Given I click "Skip next charge" on an upcoming scheduled charge, When I confirm, Then the charge is marked abandoned with reason skipped and next_charge_at advances by one interval

Manual ad-hoc charge executed against stored PM with optional BC order creation; blocked without opt-in auth

BRD.md §US-12.4: Given I click "Add manual charge" on a subscription, When I enter amount and confirmation, Then the charge is executed immediately against the PM and a BC order is created optionally

Processor chargeback webhook auto-pauses subscription, marks charge disputed, emails merchant with evidence-upload link

BRD.md §US-12.5: Given a chargeback is received (processor webhook), When we process it, Then the subscription is auto-paused, the charge is marked disputed, and an email goes to the merchant with evidence-upload link

Partial refund includes proportional tax; BC order reflects adjusted tax amount

BRD.md §US-12.6: Given a $100 charge with $7 tax is partially refunded $30, When the refund processes, Then the refund includes proportional tax (~$2.10) and the BC order reflects the adjusted tax

Subscription event timeline lists every lifecycle event with timestamp, actor, and payload snippet; filterable by event type and actor

BRD.md §US-13.1: Given I open a subscription, When the timeline renders, Then it lists every lifecycle event with timestamp, actor, and payload snippet

Daily reconciliation cron detects: succeeded charges with no bc_order_id, stuck processing charges >1h, BC order/charge mismatches; drifts create exception_queue entries

BRD.md §US-13.2: Given the reconciliation cron runs, When it executes, Then it samples charges without bc_order_id, BC orders without matching charge, stuck processing charges

Failed charge can be replayed with same idempotency key via admin; never double-charges; every replay audited with Support user ID

BRD.md §US-13.3: Given a charge is stuck in failed, When I click "Replay" in the admin, Then the workflow re-runs using the same idempotency key and does not double-charge

Every log line carries subscription_id, charge_id, and request correlation ID; queryable end-to-end across services

BRD.md §US-13.4: Given any logged event, When I query by charge_id, Then I see every log line across all services for that charge

Internal metrics dashboard shows per-store and aggregate charge outcomes, latency distributions, queue depth, dunning recovery rates

BRD.md §US-13.5: Given I open the internal metrics dashboard, When it renders, Then I see per-store and aggregate charge outcomes, latency distributions, queue depth, dunning recovery rates

Successful charge triggers POST /v2/orders with customer, addresses, line items, payment_provider_id, staff_notes, external_source; charge.bc_order_id stored

BRD.md §US-14.1: Given a charge succeeds, When the workflow continues, Then a BC order POST happens with customer, billing/shipping addresses, line items, payment_status=captured, payment_provider_id, status_id

BC order creation failure routes charge to exception queue while processor settlement remains

BRD.md §US-14.1: Given the order creation fails, When the error is caught, Then the charge goes into the exception queue while the processor settlement remains

staff_notes starts with [SUB] {subscription_id} cycle {N} on every subscription order

BRD.md §US-14.2: Given a subscription order is created, When it posts, Then staff_notes starts with [SUB] {subscription_id} cycle {N}

external_source set to bc-subscriptions-app on every subscription order

BRD.md §US-14.2: Given a subscription order is created, When it posts, Then external_source is set to our app identifier

custom_fields {subscription_id, charge_id, cycle_number, plan_id} posted via follow-up /v2/orders/{id}/custom_fields

BRD.md §US-14.2: Given a subscription order is created, When it posts, Then custom_fields contains {subscription_id, charge_id, cycle_number, plan_id}

store/order/created webhook PATCHes the order custom_fields and staff_notes to add subscription linkage after Subscription creation

BRD.md §US-14.3: Given a store/order/created webhook creates a Subscription, When we process, Then we PATCH the order's custom_fields and staff_notes to add subscription linkage

Merchant-configured default_sub_status_id column on stores; materializeBcOrderForCharge reads it and falls back to 11 when NULL

BRD.md §US-14.4: Given the merchant settings page, When I select a default status_id, Then new subscription orders post into that status

store/order/updated webhook handler reacts to external order changes (status sync + advisory audit on field edits)

BRD.md §US-14.5: Given I edit a subscription order's shipping address in BC, When store/order/updated fires, Then the parent Subscription's default shipping address optionally updates per merchant setting or logs as an Event only

merchant-setting-driven propagation of order shipping_address edits to parent subscription row (sync_order_edits_to_subscription = true); pending charges in active bundles are unbundled so re-materialization honours the new address

BRD.md §US-14.5 Tier 3: optional shipping_address update per merchant setting (Phase 2 — Hive #924, PR #981)

prorate_now policy captures (new_price - old_price) * (N-D)/N immediately on plan upgrade; next renewal at new price

BRD.md §US-14.6: Given a plan-upgrade and policy is prorate_now, When the upgrade saves, Then a one-time charge is captured for the prorated delta

skip_and_bill_next and overcapture delta-capture policies implemented; destination plan policy applies on cross-plan upgrades

BRD.md §US-14.6: Given policies skip_and_bill_next and overcapture, When upgrade saves, Then correct charge timing and cycle semantics apply; destination plan policy governs cross-plan upgrades

Stale NTI triggers MUSE verification charge before renewal MIT; success refreshes last_nti_refreshed_at; failure routes to dunning

BRD.md §US-14.7: Given subscriptions.last_nti_refreshed_at > merchant.nti_freshness_days, When renewal worker runs, Then a MUSE verification charge fires before the renewal MIT

Pre-charge hook chain for renewal-time pre-charge logic; hooks register via preChargeRegistry

Epic 14 design plan / Hive #589

Inventory check runs before charge execution; low-inventory triggers merchant policy: allow/skip/substitute/pause

BRD.md §US-15.1: Given a charge is about to execute, When the inventory check runs, Then BC API returns current inventory per variant; low inventory triggers merchant backorder policy

Price List re-read at renewal for Price List strategy; fixed discount uses current catalog × discount; locked_price_cents overrides all

BRD.md §US-15.2: Given a plan using "BC Price List" strategy, When the charge computes, Then the Price List is re-read at renewal time

BC tax-calculation endpoint called with current shipping address jurisdiction at renewal; final charge includes computed tax

BRD.md §US-15.3: Given a subscription has shipping address and current line items, When the charge runs, Then BC's tax-calculation endpoint is called with current jurisdiction

BC shipping-quote endpoint called at renewal; merchant-selected method rate applied; invalid shipping method routes to exception queue

BRD.md §US-15.4: Given a subscription renews, When the charge computes, Then BC's shipping-quote endpoint is called and the merchant-selected shipping method's rate is applied

Plan "Free shipping for subscribers" setting zeros shipping cost on all renewals regardless of cart value

BRD.md §US-15.5: Given plan setting "Free shipping for subscribers: on," When a renewal runs, Then shipping cost is zeroed regardless of cart value

Pre-renewal proactive inventory scan runs ahead of charge window; plans.oos_renewal_policy (proceed/pause/skip_cycle/notify_and_wait) drives outcome; on_hold_oos status + Exception Queue oos_renewal_blocked entry surface to merchant for resolution (Resume now / Skip cycle / Substitute product)

BRD.md §US-15.6: Given a plan with oos_renewal_policy set, When the scheduler pre-renewal OOS check runs, Then the policy is applied (pause / skip_cycle / notify_and_wait / proceed) with subscriber notification and merchant Exception Queue resolution UI.

Subscriber with ≥2 active subscriptions to same address sees "Bundle shipments" toggle in portal

BRD.md §US-16.1: Given I have ≥ 2 active subscriptions shipping to the same address, When I open the portal, Then I see a "Bundle shipments" toggle

Enabling bundle toggle snaps eligible renewals to a common date within merchant-configured window

BRD.md §US-16.1: Given I toggle on, When my next charges are scheduled, Then the scheduler snaps eligible renewals to a common date

Bundled renewals produce a single BC order with combined line items tagged with all bundle subscription_ids and charge_ids

BRD.md §US-16.2: Given two charges in a bundle succeed on the same cycle, When creating the BC order, Then one order is posted with line items from both subscriptions

Failed charge in a bundle is excluded from the BC order while succeeded ones proceed; failed charge continues own dunning

BRD.md §US-16.2: Given a charge fails while others succeed, When creating the order, Then only the succeeded subscriptions' line items are included

Bundled BC orders have staff_notes showing [BUNDLE] and contributing subscription IDs

BRD.md §US-16.3: Given a bundled order exists, When I view it in BC, Then the staff_notes show [BUNDLE] and list contributing subscription IDs

Admin bundle detail view: line-item → subscription attribution + lifecycle events

BRD.md §US-16.3: Given I click into the bundle detail in our admin, When it renders, Then I see line-item → subscription attribution

Bundle shipping rate allocated proportionally by line-item value across contributing subscription charges

BRD.md §US-16.4: Given a bundle renewal runs, When shipping is quoted, Then the single shipping rate is applied to the bundle order and charged proportionally

Phase 3 deferred-build scaffold: plans.billing_cadence + plans.shipping_cadence decoupled; billing scheduler fires MIT charges on billing cadence; fulfillment scheduler fires BC orders on shipping cadence (no additional MIT); delivery_instances rows track per-shipment fulfillment

BRD.md §US-16.5: Phase 3 — decoupled billing and shipping cadence (WCSubs feature-request #1, 727 votes — top blue-ocean differentiator). Architecture per ADR-0075.

Entering email on portal login page sends a magic link email

BRD.md §US-17.1: Given I enter my email on the portal login page, When I submit, Then a magic link is emailed

Clicking valid magic link within 15 minutes logs subscriber in with session cookie scoped to portal subdomain

BRD.md §US-17.1: Given I click the link within 15 minutes, When it resolves, Then I'm logged in with a session cookie scoped to the portal subdomain

Expired or reused magic link shows "Request a new link" page

BRD.md §US-17.1: Given the link is expired or reused, When I click, Then I'm shown a "Request a new link" page

Subscriber logged into BC storefront can access portal without re-authenticating via BC customer JWT exchange

BRD.md §US-17.2: Given I am logged into the BC storefront and click "Manage subscriptions," When I land on our portal, Then the BC customer JWT is exchanged for a portal session

Portal served from merchant custom subdomain with provisioned TLS cert after CNAME verification

BRD.md §US-17.3: Given I add a CNAME pointing to our portal hostname, When I verify it, Then the portal serves on my custom domain

Portal applies merchant logo, colors, and Google Font via CSS variables when subscriber loads the portal

BRD.md §US-17.4: Given I upload logo + pick colors + pick a Google Font in admin, When a subscriber loads the portal, Then those values apply via CSS variables

Headless SDK getSubscriptions(customerToken) returns typed subscription list

BRD.md §US-17.5: Given the headless SDK is installed, When I call getSubscriptions(customerToken), Then I get a typed list

Headless SDK performAction(subscriptionId, action, params) applies action server-side and returns updated subscription

BRD.md §US-17.5: Given I call performAction(subscriptionId, 'pause', params), When it resolves, Then the action is applied server-side and the updated subscription is returned

Skip next charge marks upcoming charge as abandoned (reason: skipped) and advances next_charge_at by one interval

BRD.md §US-18.1: Given I view a subscription, When I click "Skip next," Then the upcoming charge is marked abandoned (reason: skipped) and next_charge_at advances one interval

Already-skipped charge shows Unskip CTA for up to 24h before originally scheduled date

BRD.md §US-18.1: Given I have already skipped the next charge, When I view the subscription, Then the CTA changes to "Unskip" for up to 24h before the originally scheduled date

Selecting eligible alternate product/variant updates subscription to new product/variant from next cycle forward

BRD.md §US-18.2: Given plan-eligible alternate products/variants exist, When I click "Swap" and pick an alternate, Then the subscription updates to the new product/variant from the next cycle forward

Alternate with different price shows new estimated charge amount before confirm

BRD.md §US-18.2: Given the alternate has a different price, When I confirm, Then I see the new estimated charge amount before confirming

Swap CTA is disabled with explainer when no eligible alternate exists (plan locked to single variant)

BRD.md §US-18.2: Given no alternate is eligible, When I click swap, Then the CTA is disabled with an explainer

Choosing a resume date moves subscription to paused status with no charges until resume

BRD.md §US-18.3: Given I click "Pause," When I pick a resume date, Then subscription status moves to paused and no charges occur until resume

Pause without resume date (indefinite) sets status to paused until manual resume

BRD.md §US-18.3: Given I did not pick a resume date (indefinite pause), When I save, Then status is paused until I manually resume

Rescheduling to a date within allowed window (+90 days) updates next_charge_at and shifts all future charges

BRD.md §US-18.4: Given I click "Reschedule," When I pick a date within the allowed window, Then next_charge_at updates and all future charges shift

Cancel flow captures reason first before showing interventions

BRD.md §US-18.5: Given I click "Cancel," When the flow starts, Then I capture a reason first

Accepting an offered intervention (e.g. pause) applies the action and exits cancel flow without cancelling

BRD.md §US-18.5: Given an intervention is shown and I accept it, When I confirm, Then the action is applied and I don't cancel

Declining interventions and confirming cancel moves subscription to cancelled with cancel reason logged

BRD.md §US-18.5: Given I decline interventions and confirm cancel, When I save, Then subscription status moves to cancelled with cancel reason logged

Incrementing quantity prices next and all subsequent charges at new quantity

BRD.md §US-18.6: Given I view my subscription, When I increment quantity and save, Then the next charge and all subsequent are priced at new quantity

Out-of-range quantity is silently clamped to [1..100] rather than rejected; audit event records original_quantity + clamped:true

BRD.md §US-18.6 / Tier α polish decision e21ea786: silent-clamp closes UX gap where subscribers typing "0" got a 400

Paused subscriptions with current_period_end <= now() are automatically flipped to active by a scheduled sweep

BRD.md §US-18.3: Given pause period has elapsed, When the scheduler fires, Then subscription auto-resumes and subscription.resumed event is logged

Skipping a delivery instance immediately triggers fillForSubscription to refresh the rolling horizon rather than waiting for the next cron

Tier α polish decision e21ea786: lazy-fill horizon materializes immediately on skip action

Skip/pause/swap handlers exclude the affected charge from any non-terminal bundle (pending/locked/partially_failed) via unbundleCharge before applying the lifecycle action; materialized bundles return 409 (Epic 12 refund path).

docs/architecture/order-bundling.md §5 (Conflict Resolution Protocol) + ADR-0049 + Hive #887; Epic-18 must not desync bundle composition by skipping/pausing/swapping a member without unbundling.

Subscriber can reactivate cancelled subscription within 90 days, restoring active status with fresh next_charge_at

BRD.md §US-18.7: Given I have a cancelled subscription < 90 days old, When I click "Reactivate" in the portal, Then status returns to active with a fresh next_charge_at

Reactivating when product or plan is no longer active prompts subscriber to pick an alternate

BRD.md §US-18.7: Given the product or plan is no longer active, When I reactivate, Then I'm prompted to pick an alternate

Changing interval applies new cadence from next cycle onward with recomputed next_charge_at

BRD.md §US-18.8: Given the plan offers multiple intervals, When I change interval and save, Then the new interval applies from the next cycle onward and next_charge_at is recomputed

term_end_at - nudge_lead_days fires "renew your subscription" email and flags subscription pending_renewal_decision

BRD.md §US-18.9: Given a subscription has term_end_at set, When term_end_at - merchant.nudge_lead_days arrives, Then a "renew your subscription" email fires

Subscriber confirming re-up advances term_end_at by one term and returns subscription to standard renewal flow

BRD.md §US-18.9: Given the subscriber confirms re-up, When confirmation is recorded, Then term_end_at advances by one term and subscription returns to standard renewal flow

Subscriber declining or ignoring nudge through term_end_at transitions subscription to completed (terminal)

BRD.md §US-18.9: Given the subscriber declines or ignores the nudge through term_end_at, When the term ends, Then the subscription transitions to completed

Portal cancel route returns 409 cancel_locked with lock_expires_at while plan-commitment lock is active; admin override available via POST /api/v1/admin/subscriptions/:id/force-cancel with reason capture and audit emission

BRD.md §US-18.10: Given lock_expires_at > now() and early_cancel_policy=block, When the subscriber attempts cancel, Then 409 is returned; manager/admin role can override via admin-cancel with required reason; audit event subscription.admin_cancel emitted.

Same-medium, single-step, no-obstruction cancellation — online-enrolled subscriptions cancel online "at least as easy as" sign-up

BRD.md §US-18.11: Given a subscriber enrolled online, When they want to cancel, Then an online cancel path completes in the same session with no mandatory retention call or delay

Subscriber updates PM on a subscription via processor-hosted tokenization form; payment_method_ref updated; dunning retries reset on PM update

BRD.md §US-19.1: Given I click "Update payment method" on a subscription, When the secure form loads, Then I enter new card details and submit; update succeeds and dunning retries reset

Subscriber can update default PM (applies to all subs) or per-subscription PM (single sub only)

BRD.md §US-19.2: Given I have 3 subscriptions, When I update "Default PM," Then all 3 subs point at the new default; per-sub update affects only that sub

Subscriber updates shipping address; next charge uses new address for tax/shipping recalc; blocked with message if plan disallows new country

BRD.md §US-19.3: Given I open address editor, When I save a new address, Then the next charge uses that address for tax/shipping recalc

Subscriber can enter separate billing address stored with the PM

BRD.md §US-19.4: Given I toggle "Different billing address" in the PM editor, When I enter and save, Then the billing address is stored with the PM

Subscriber records preferences (allergens, dislikes, sizes) used by merchant curation logic; exposed via API and merchant admin

BRD.md §US-19.5: Given the merchant has enabled the preferences schema, When I edit preferences in the portal, Then the updated values are available to the merchant's curation logic

Customer-level PM update atomically applies to all N subscriptions; single events row with all affected subscription IDs; partial-update failure state not exposed

BRD.md §US-19.6: Given I have N active subscriptions, When I update my PM at the customer/wallet level, Then all N subscriptions reflect the new PM by next renewal with atomic semantics

Cancel flow presents merchant-configured reason list + "Other"; selected reason persisted with the cancel event

BRD.md §US-20.1: Given I click "Cancel," When the flow starts, Then I see a radio list of merchant-configured reasons + "Other"; reason is persisted with the cancel event

"Don't need right now" reason triggers pause-offer screen with 30/60/90 day options; accepting applies pause and exits cancel flow

BRD.md §US-20.2: Given reason = "Don't need right now," When the flow proceeds, Then an offer screen shows "Pause 30/60/90 days" options

"Too expensive" reason triggers merchant-configured discount offer; acceptance applies time-limited promotion; frequency cap enforced

BRD.md §US-20.3: Given reason = "Too expensive," When the flow proceeds, Then a merchant-configured discount is offered; acceptance is frequency-capped per customer

"Ordering too much" reason offers longer available intervals; acceptance changes interval and exits cancel flow

BRD.md §US-20.4: Given reason = "Ordering too much," When the flow proceeds, Then longer available intervals are offered; accepting changes cadence

"Product issue" reason routes subscriber to merchant-configured support handoff (Gorgias ticket, email, or phone link)

BRD.md §US-20.5: Given reason = "Product issue," When the flow proceeds, Then a merchant-configured support handoff happens

Admin-configured intervention variants A/B tested; save rates attributable per variant

BRD.md §US-20.6: Given I create variants in admin, When subscribers enter the flow, Then they're randomized and save rates are attributable per variant

Save-attempt cap (merchant-set, platform-capped) with a live one-action cancel control on every save-flow step; over-cap configs rejected at save time

BRD.md §US-20.7: Given a cancel-time save flow runs, When it presents offers, Then it presents at most a bounded round and the cancel control completes the cancel from any step

Dashboard shows MRR, active subs, new subs (30d), cancels (30d), gross churn %, net revenue churn % tiles

BRD.md §US-21.1: Given I open the dashboard, When it renders, Then tiles show: MRR (with trailing 30-day delta), active subs, new subs (30d), cancels (30d), gross churn %, net revenue churn %

Clicking a KPI tile navigates to the corresponding filtered subscriptions or exceptions list with time-series sparkline visible on the tile itself

BRD.md §US-21.1: Given I click a tile, When it drills in, Then I see time-series and supporting detail

Dashboard shows upcoming charge $ value, count, and mini-chart for next 7 and 30 days

BRD.md §US-21.2: Given upcoming charges exist, When the panel renders, Then I see $ value, charge count, and a mini-chart over the period

Exception queue groups items by type (failed charge, OOS renewal, reconciliation drift) sorted by MRR impact and days in exception

BRD.md §US-21.3: Given exceptions exist, When I open the queue, Then items are grouped by type and sorted by impact

Resolving an exception with a note removes it from the queue and event-logs the resolution

BRD.md §US-21.3: Given I resolve an item, When I click "Mark resolved" with a note, Then it leaves the queue and Event-logs the resolution

Escalating an exception flags it in the queue (status stays open, escalated_at set) and event-logs the escalation

BRD.md §US-21.3: exception queue row actions — "Mark resolved" + "Escalate"

Subscription list shows paginated table with customer, plan, status, MRR, next charge, cycles completed columns

BRD.md §US-21.4: Given I open "Subscriptions," When it loads, Then I see a paginated table with columns: customer, plan, status, MRR, next charge, cycles completed

Applied filters (status, plan, query) are reflected in the URL as query params; sharing the URL restores the filter state

BRD.md §US-21.4: Given I apply filters (status=past_due, plan=X), When results update, Then the URL is shareable

Merchant can bulk-skip, bulk-pause, or bulk-cancel subscriptions matching a filter via a single admin endpoint that returns a per-id succeeded/failed result shape

BRD.md §US-21.5: Given I filter and select rows, When I click "Bulk action → Skip next," Then I confirm scope and the action is queued and progress-tracked

Subscription detail shows state, next charge, payment method health, addresses, charge history, event timeline, and manual-action buttons

BRD.md §US-21.6: Given I click a subscription, When the detail opens, Then I see: state, next charge, payment method health, shipping/billing addresses, charge history with links to BC orders, event timeline, manual-action buttons

Filtered subscription list exports as CSV via a streaming admin endpoint; admin SPA exposes an "Export to CSV" CTA that downloads the result

BRD.md §US-21.7: Given I click "Export" on a filtered list, When the export builds, Then a background job generates a CSV and I'm notified when it's ready

Analytics page shows cohort × cycle retention table with CSS color-scale approximating a heatmap (acquisition month rows × cycle columns, % retained values)

BRD.md §US-21.8: Given I open Analytics, When the cohort tab loads, Then I see a heatmap of acquisition cohort × cycle (% retained)

Analytics page shows per-plan estimated 12- and 24-month LTV using geometric series from average charge amount and observed monthly survival rate

BRD.md §US-21.8: Given I open LTV, When it loads, Then I see estimated 12/24-month LTV per plan using cohort-derived survival curves

Support can create subscription manually via admin wizard (customer + plan + PM + schedule), marked with manual origin event

BRD.md §US-22.1: Given I click "New subscription," When I pick customer + plan + PM + schedule, Then the subscription is created with an Event marking the manual origin

BC customer edit page shows Subscriptions extension panel listing all customer subscriptions with deep-links

BRD.md §US-22.2: Given I open a BC customer, When the extension panel loads, Then it lists all the customer's subscriptions with deep-links to our admin

Support can view subscriber portal in read-only impersonation mode with all actions logged as actor=support

BRD.md §US-22.3: Given I click "View as subscriber," When impersonation starts, Then I see the portal in read-only mode and my actions are logged as actor=support

Support can create subscriptions in bulk via CSV upload, staging then activating on confirmation

BRD.md §US-22.4: Given I upload a valid CSV, When the job processes, Then subscriptions are created in a staging state and activated on confirmation

Support can force an immediate charge with confirmation and audit note

BRD.md §US-22.5: Given I click "Force charge now," When I confirm, Then an immediate charge is enqueued with an audit note

Support can force an immediate refund with amount, reason, and processor call

BRD.md §US-22.5: Given I click "Force refund," When I confirm the amount and reason, Then the processor is called immediately

Support can add internal notes to a subscription; note appears timestamped and attributed on detail view

BRD.md §US-22.6: Given I add a note, When it saves, Then it appears on the subscription detail, timestamped and attributed to me

Admin can issue AllotmentGrant rows with unit_type, amount_per_period, refresh_cadence, rollover_policy, expires_at

BRD.md §US-22.7: Given an admin-grant form, When I select target customer or buyer-org with parameters, Then an AllotmentGrant row is created

AllotmentGrant detail shows current_balance, next_refresh_at, debit history, and admin actions (suspend/revoke/manual-refresh/override-balance)

BRD.md §US-22.7: Given an existing grant, When I view the detail page, Then I see current_balance, next_refresh_at, the full debit history, and admin actions

Revoking an AllotmentGrant sets status=revoked, blocks further debits, and hides balance from portal

BRD.md §US-22.7: Given I revoke a grant, When confirmed, Then status='revoked', no further debits accepted, subscriber-facing balance disappears

Admin subscription detail renders active CustomFieldDefinitions with current values and type-appropriate inputs

BRD.md §US-22.8: Given a subscription with active CustomFieldDefinitions in scope, When I view the admin detail page, Then each defined field renders with its current value

Invalid custom field (regex mismatch, type mismatch, required-but-empty) blocks save with inline error

BRD.md §US-22.8: Given I edit a field that fails validation, When I attempt save, Then save is blocked with the field-level error displayed inline

Saving custom field updates metadata.custom_fields, fires audit Event with actor_id and value diff

BRD.md §US-22.8: Given I save valid changes, When the API persists, Then subscriptions.metadata.custom_fields updates and an audit Event records actor_id and value diff

Archived CustomFieldDefinition renders read-only on subscription detail with "field archived" hint, data preserved

BRD.md §US-22.8: Given a field is archived after a subscription has data, When I view the page, Then the archived field renders read-only with a "field archived" hint

Support can enroll B2B buyer-org in subscription via admin impersonation with multi-actor assignment (payer, beneficiary, manager)

BRD.md §US-22.9: Given a B2B Edition buyer-org and CS-rep, When I impersonate and navigate to "Create Subscription," Then I can configure and confirm B2B subscription

Lifecycle events (welcome, upcoming charge, charge succeeded/failed, paused/resumed/cancelled, shipment) trigger emails via Resend with merchant template + variables

BRD.md §US-23.1: Given each lifecycle event fires, When it matches an enabled notification type, Then an email is sent via Resend with merchant's template + variables

Subscriber opt-in SMS for time-sensitive events (charge failed, shipment shipped) via Twilio

BRD.md §US-23.2: Given I opt into SMS in the portal, When relevant events fire, Then SMS is sent via Twilio

Merchant edits email templates (subject, body, branding) with Markdown/MJML editor and sample-data preview

BRD.md §US-23.3: Given I open template editor, When I edit Markdown/MJML with variable placeholders, Then I can preview with sample data and save

Configurable threshold alerts for high-value events (chargeback, large cancel, dunning spike) and daily digest with key metrics and exception queue summary

BRD.md §US-23.4: Given I set alert thresholds, When events cross them, Then an email/Slack alert fires; daily digest includes key metrics and exception queue summary

Subscription lifecycle events synced to Klaviyo (Subscription Created, Cancelled, Charge Succeeded/Failed, etc.) with standard properties

BRD.md §US-23.5: Given Klaviyo is connected, When subscription events fire, Then Klaviyo profile events are pushed with standard properties

Cancel with reason "Product issue" auto-creates helpdesk ticket in Gorgias/Zendesk with subscription + order context

BRD.md §US-23.6: Given a cancel with reason "Product issue" occurs, When the event fires, Then a ticket is auto-created in Gorgias/Zendesk with subscription + order context

Subscription revenue posted to NetSuite/QuickBooks/Xero as journal entries with subscription metadata on charge success

BRD.md §US-23.7: Given an accounting integration is connected, When charges succeed, Then journal entries post with subscription metadata

Developer-registered webhook endpoints receive subscription lifecycle events POST with HMAC signature, retried with exponential backoff on failure

BRD.md §US-23.8: Given I register a webhook endpoint, When matching events fire, Then they're POSTed with signature header and retried on failure with exponential backoff

Merchant configures custom domain for email sending; Resend domain provisioned with DKIM; emails send from merchant domain with DMARC alignment

BRD.md §US-23.9: Given I configure notifications.{merchant.com} in settings, When I trigger DNS verification, Then we provision a Resend domain + DKIM record

Portal login magic-link sent with 32-byte opaque token, 15-min TTL, single-use bcrypt lookup; dunning PM-update link has 7-day TTL; domain mismatch rejected

BRD.md §US-23.12: Given a subscriber requests portal login, When the magic-link email is sent, Then the link contains a 32-byte opaque token with TTL 15 min, single-use, bcrypt-lookup server-side

Resend send-outcome webhooks (bounced, complained, delivered, opened, clicked) ingested, verified by signature, update email_sends and suppression tables

BRD.md §US-23.16: Given Resend POSTs email.bounced / email.complained / email.delivered / email.opened / email.clicked, When verified by signature, Then we update email_sends and downstream tables

Per-merchant-domain bounce/complaint rolling-window threshold monitoring drives send throttling + alerts; recovery auto-resumes send

BRD.md §US-23.10: Given a merchant domain crosses bounce > 5% (or complaint 0.1%/0.3% warn/hard), When detected, Then sending throttles and an alert fires; recovery auto-resumes.

Subscriber email opt-out + hard-bounce / complaint events suppress recipient across the merchant; transactional bypasses marketing-only opt-out per PRD §9.8 routing rule; re-opt-in via portal removes the suppression and emits subscriber.resubscribed

BRD.md §US-23.11: Given a subscriber unsubscribes or hard-bounces, When the event lands, Then we suppress the recipient for that merchant; re-opt-in via portal removes the entry and emits subscriber.resubscribed.

Dunning email subject + body translate issuer decline codes (card_declined, insufficient_funds, expired_card, do_not_honor, requires_action) to subscriber-friendly copy; SCA failures route to magic-link SCA-completion flow; hard-fraud cancels without email (US-23.6)

BRD.md §US-23.13: Given a charge fails with card_declined / insufficient_funds / expired_card / do_not_honor / requires_action, When the dunning email fires, Then the subject + body translate the issuer code to subscriber-friendly copy.

Merchant template compile/render failures fall back to a system template + emit template.render_failed event with merchant alert; unallowed-variable references substitute safe placeholders

BRD.md §US-23.14: Given a merchant template fails to compile, When the render runs, Then we render with a system fallback template + send + emit template.render_failed event with merchant alert.

Per-send idempotency key {template_key}:{recipient}:{source_event_id} guards workflow-restart re-sends via the email_idempotency table; Resend Idempotency-Key header round-trips our send key so Resend collapses any race that slips past the pre-send DB check

BRD.md §US-23.15: Given a workflow restart re-enters the send step, When the per-send key is presented, Then the second attempt returns the original send record without re-sending.

Per-locale email templates resolved from subscriber language preference (portal pref > store default > Accept-Language); Intl.NumberFormat / DateTimeFormat for numeric/date/currency; RTL languages emit dir="rtl" MJML; renderer accepts locale parameter from MVP onward (architecture-now, content-later)

BRD.md §US-23.17: Given a subscriber language preference, When a template fires, Then we render the matching (merchant × template × locale) cell, falling back to merchant default locale.

Pre-renewal reminders for annual-or-longer cycles disclosing terms, renewal date/amount, and cancel link; material-change notice; logged for audit

BRD.md §US-23.18: Given a subscription on an annual-or-longer cycle, When renewal approaches, Then a reminder is sent within the merchant-configured window stating product, date, amount, frequency, and how to cancel

B2B Edition subscriptions attached to company_id not customer_id; all authorized company users see company subscriptions in portal

BRD.md §US-24.1: Given B2B Edition is detected, When a subscription is created via a company-buyer checkout, Then it is associated with company_id, not customer_id

B2B buyer with view_only role sees empty allowed_actions list; buyer/admin roles see full action set; effective_role + allowed_actions returned from server so UI needs no role logic

BRD.md §US-24.2: Given company roles are defined in BC B2B Edition, When a buyer with view_only role opens the portal, Then action buttons are disabled and labeled "Requires higher permissions."

B2B buyer submits change request via portal; pending → approved/rejected by admin; subscription_change_requests table tracks state; view_only buyers blocked from submitting

BRD.md §US-24.3: Given approval workflows are enabled, When a buyer initiates a change, Then the change enters a pending state awaiting approval

PO-payment subscriptions have payment_method_id=null + metadata.payment_method_type=po + po_number + net_terms_days; renewal worker should generate BC orders with payment_status: pending (renewal worker update is an [Operator-Task])

BRD.md §US-24.4: Given BC B2B supports PO payments, When a company subscribes with PO, Then payment_method_type: po is stored and renewal charges generate BC orders with payment_status: pending

B2B Edition PDP shows B2B widget variant with "contact CS rep" CTA; CS rep enrollment via Epic 22 admin tools; subscriptions appear in Buyer Portal with managed-by annotation

BRD.md §US-24.9: Given a B2B-Edition store, When a buyer browses a subscription-enabled PDP, Then the standard subscription widget renders a B2B variant with "contact your CS rep" CTA

Catalyst PDP with B2B Edition Buyer Portal SDK shows B2C widget for non-B2B sessions and B2B variant for B2B sessions; window.B2B SDK presence probed by widget init

BRD.md §US-24.11: Given a Catalyst storefront with the B2B Edition Buyer Portal SDK loaded, When a B2C shopper views the PDP, Then the standard B2C subscription widget renders; B2B buyer sees B2B variant

Dashboard MRR rolls up across BC B2B parent-company hierarchy; merchant filtering by parent company aggregates child-company subscriptions

BRD.md §US-24.5: Given BC B2B hierarchy is defined, When I view the dashboard filtered by a parent company, Then MRR rolls up across all child companies.

Renewals read negotiated volume-tier pricing from BC B2B at charge time; applicable tier applies to enterprise-deal renewals

BRD.md §US-24.6: Given a company has volume-tier pricing in BC, When renewals compute, Then the applicable tier is read at renewal time.

Contract-term commitments with auto-renewal + notice-period semantics; B2B buyer cancellation within notice window is blocked or routes to merchant-configured legal workflow

BRD.md §US-24.7: Given a contract term of 12 months with 60-day notice, When a buyer tries to cancel with < 60 days until term end, Then cancellation is blocked or routes to legal workflow per merchant config.

Single B2B subscription ships to multiple company locations on a cycle (e.g., monthly delivery to 5 offices); each cycle creates one order per location with agreed quantity; total charge = sum of all locations

BRD.md §US-24.8: Given a multi-location subscription is configured, When a cycle renews, Then one order per location is created with the agreed quantity; total charge equals the sum.

org_admin role reserved in multi-actor extension schema; Phase 1 permission-resolution path treats org_admin as a recognised role enum value; per-org processor_connection_ref column reserved for marketplace MoR v2 routing (ADR-0022)

BRD.md §US-24.10: Given a B2B subscription with actors[].role=org_admin, When the org_admin views the Buyer Portal, Then they see all subscriptions for their org and can act per merchant-configured permissions.

Merchant can mark a promotion as subscription_only via admin UI toggle; flag stored in promotion_settings table; storefront visibility endpoint gates coupon display by cart composition

BRD.md §US-25.1: Given I create a coupon with applies_to: subscription_only, When a shopper applies it in cart, Then it discounts only subscription line items; recurring: true carries through renewals

Plan whose amount_cents is below the one-time product price renders a "Subscribe and save X%" badge in the storefront widget; the discount applies at checkout without coupon-code entry because the cart line uses plan.amount_cents directly.

BRD.md §US-25.2: Given a plan's pricing strategy is fixed_discount_pct: 10, When a shopper views a subscribable PDP, Then the widget shows "Subscribe and save 10%" prominently; the discount applies without coupon code at checkout.

Plan-level cycle-scoped discount declaration (cycle_discount_pct/scope/count) snapshots onto subscription_discounts at creation with cycle_min/cycle_max bounds. Scheduler applies the discount only when current renewal cycle is within range. Plan edits do NOT affect in-flight subscriptions (lock-at-creation per ADR-0052).

BRD.md §US-25.3: Given a plan with cycle_discount_scope=first_n_cycles, count=3, pct=50, When cycle 1/2/3 charges compute, Then discount applies; cycle 4+ does not. Given a merchant edits the plan after sub creation, Then in-flight subscriptions keep the original discount.

Tenure loyalty tiers ride the subscription_promotions table as `tiered_cycles` window; tier ladder reconfigurable mid-flight via re_resolve lock_policy; scheduler emits `loyalty.tier_reached` on boundary cycle and `loyalty.discount_applied` every cycle the discount fires; cycles_completed preservation via reactivate.ts implements the AC2 rejoin path.

BRD.md §US-25.4: Given tenure tiers are configured, When a renewal computes, Then the discount matching current cycle count is applied; Given subscriber cancels and rejoins within N days, Then prior cycle count is restored

Two-layer stacking rule enforcement: resolveDiscountStack (subscription_discounts) and evaluateSubscriptionPromotions (subscription_promotions) each implement exclusive (highest computed value wins) + stackable (additive, capped). Exclusive disambiguation per Hive #900: highest computed amount_cents for the specific charge, not abstract discount_percent.

BRD.md §US-25.5: Given I set stacking_rule: exclusive on a coupon, When another discount is present on a renewal, Then only the higher-value one applies; Given stacking_rule: stackable, Then they are combined additively

Free-shipping rule with cycle-condition (from_cycle) and/or order-value threshold (min_amount_cents) zeros the shipping line on the materialized BC order (single + bundle paths).

BRD.md §US-25.6 + Hive #901 body

gift_item promo with application_window=all_cycles + config.cycle_modulo:N fires on every Nth cycle, injecting a $0 product line into the BC order on those cycles. OOS fallback (skip/substitute) configurable per promo.

BRD.md §US-25.7 + Hive #901 body §US-25.7

gift_item promo with application_window=first_cycle_only injects a $0 product line into the first BC order on subscription creation; no further fires.

BRD.md §US-25.8 + Hive #901 body §US-25.8

Two-table subscription-promotion substrate: subscription_promotions (coupon definition) + subscription_promotion_applications (per-charge attribution). Replaces spike #117 jsonb-on-charges proposal with relational tables for FK integrity, reporting joins, and refund-on-cancel joins.

BRD.md §US-25.1 + promo-projection.md §3.1, §3.3 + ADR-0053

lock_policy is derived from application_window at insert time (not merchant-settable): first_cycle_only/first_n_cycles -> lock_at_creation; all_cycles/tiered_cycles/event_triggered -> re_resolve. Enforces promo-projection.md §2.1 invariant mechanically.

promo-projection.md §2.1 + ADR-0053 (lock policy is DERIVED)

Promotion CRUD routes: POST/GET/PUT/DELETE /api/v1/admin/subscription-promotions and storefront POST /api/v1/storefront/subscription-promotions/validate-coupon. All 4xx use typed-error helpers.

BRD.md §US-25.1 + Hive #891 §What to implement

Scheduler evaluates subscription_promotions on every renewal via evaluateSubscriptionPromotions(); writes subscription_promotion_applications attribution rows in success branch; emits subscription.promotion_applied audit event per attribution. Zero-regression on empty active_promotion_ids.

promo-projection.md §4 (charge-compute algorithm) + Hive #891 step 7+8

createSubscription() accepts optional coupon_code; resolves against subscription_promotions, validates (active+window+cap+applies_to), attaches to active_promotion_ids, increments current_redemptions. Best-effort: a miss does not roll back the subscription.

BRD.md §US-25.1 + Hive #891 step 6

Per-promotion report endpoint + admin UI: redemptions, charges_discounted, total_discount_cents (with subs/bc source breakdown), active subs carrying promo, attributed MRR (from plans.amount_cents), and retention lift (avg cycles_to_cancel partitioned by promo_applied_ever, suppressed below 30 cancellations).

BRD.md §US-25.9 (P2): "Per-promo: redemptions, total discount given, attributable MRR, estimated lift, retention lift" + Hive #903 response schema

Portal cancel-flow discount intervention records one-time percent discount on next charge via subscription_discounts table

BRD.md §US-20.3 / §US-25: Given a cancel-flow "Too expensive" discount intervention is accepted, When saved, Then a subscription_discounts row is created for the next charge

include_categories rule causes subscribe widget to render only on products in those categories

BRD.md §US-26.1: Given a rule include_categories: [5, 12], When I enable a plan with this rule, Then the subscribe widget renders only on products in those categories

Product added to an included category later automatically becomes subscribable without rule update

BRD.md §US-26.1: Given a product is added to an included category later, When I view it on storefront, Then it automatically becomes subscribable

Excluded products (by product, category, or brand rule) show no subscribe widget on storefront

BRD.md §US-26.2: Given a rule exclude_products/categories/brands, When a shopper views an excluded product, Then no subscribe widget renders

Exclusion wins when a product matches both inclusion and exclusion lists

BRD.md §US-26.2: Given exclusion lists + inclusion lists are both set, When a product matches both, Then exclusion wins

Selecting excluded variant switches widget to "one-time only" and hides subscribe option

BRD.md §US-26.3: Given a per-variant eligibility list, When a shopper picks an excluded variant, Then the widget switches to "one-time only"

require_custom_field rule controls widget visibility based on BC product custom field value

BRD.md §US-26.4: Given a rule require_custom_field: {name:subscribable, value:true}, When a shopper views a product, Then the widget only renders if the custom field matches

include_customer_groups rule hides subscribe option for non-eligible customer groups

BRD.md §US-26.5: Given a rule include_customer_groups: [vip], When a non-VIP browses, Then the subscribe option is hidden

API contract: guest (customer_group_id=0) hitting only-group-gated plans returns excluded:true + excluded_by:customer_group so the widget can switch to a sign-in CTA

BRD.md §US-26.5 (API contract slice): Given a guest shopper and a group-restricted plan, When the storefront plans endpoint resolves, Then it returns plans:[], excluded:true, excluded_by:"customer_group"

Storefront widget renders a sign-in CTA (not a plain empty state) when the API returns excluded_by:customer_group for a guest

BRD.md §US-26.5 (UI rendering slice): Given the API signals excluded_by=customer_group, When the widget renders, Then a sign-in CTA replaces the subscribe surface

allowed_countries rule hides or shows "Not available in your region" for shoppers outside allowed countries

BRD.md §US-26.6: Given a rule allowed_countries: [US], When a shopper browses from outside the US, Then the widget is hidden or shows "Not available in your region"

min_qty/max_qty rules block subscribe action with clear message when quantity is out of range

BRD.md §US-26.7: Given min_qty: 2, max_qty: 10, When a shopper attempts to subscribe with qty 1 or qty 11, Then the widget blocks the action with a clear message

Subscriber with active plan A is blocked from subscribing to mutex-conflicting plan B

BRD.md §US-26.8: Given a mutex rule between products A and B, When a shopper with active A subscription tries to subscribe to B, Then they're blocked with "Already subscribed to a conflicting plan"

requires_prior_purchase rule redirects shopper to prerequisite product flow if they lack required prior purchase

BRD.md §US-26.9: Given a rule requires_prior_purchase: [starter-kit], When a shopper without prior purchase tries to subscribe to Y, Then they're redirected to the prerequisite flow

Support audit tool shows which eligibility rule evaluated which way for a customer + plan combination

BRD.md §US-26.10: Given a shopper was denied, When Support opens the audit tool and enters customer + plan, Then the tool shows which rule evaluated which way with input values visible

Documented REST API for subscriptions, charges, plans, events; paginated, filterable; rate-limited with 429 + Retry-After; X-RateLimit-* informational headers on all /api/v1/ responses; OpenAPI spec at /openapi.json (BRD §US-27.1)

BRD.md §US-27.1: Given I have an API key, When I call GET /api/v1/subscriptions?filter[status]=active, Then I get paginated JSON; rate limits return 429 with Retry-After; OpenAPI schema published at /openapi.json

Merchant creates scoped API keys (read-subs, write-subs, etc.); revoked keys immediately fail 401

BRD.md §US-27.2: Given I create an API key and pick scopes, When I use the key, Then it works only for those scopes; revoked keys fail 401

Developer registers endpoint with event-type filters; events POSTed with HMAC signature; non-2xx retried with exponential backoff up to 24h then dead-lettered

BRD.md §US-27.3: Given I register an endpoint for subscription.created, When the event fires, Then a POST is sent with payload and HMAC signature; non-2xx triggers exponential backoff retries for 24h

@bc-subscriptions/subscriber-sdk exports typed createClient with methods for all subscriber actions; breaking changes announced with deprecation warnings

BRD.md §US-27.4: Given I install @bc-subscriptions/subscriber-sdk, When I import createClient({ token }), Then I get typed methods for all supported subscriber actions

GraphQL endpoint at /graphql supports complex reads with nested subscription+charge+order in one request; only requested fields resolved

BRD.md §US-27.5: Given I POST a query to /graphql, When it includes nested resources, Then only requested fields are resolved

Developer sandboxes provisioned with isolated store, API keys, and test subscriptions without affecting production

BRD.md §US-27.7: Given I request a sandbox, When it's provisioned, Then I get isolated store + API keys + test subscriptions

@bc-subscriptions/subscriber-sdk + @bc-subscriptions/react 2-package workspace scaffold + type-generation pipeline + npm release workflow (ADR-0034)

ADR-0034 §Build sequence step 1

Third-party partner extensions installable into a merchant tenant; sandboxed permission model registers webhooks + admin UI panels per extension (retention apps, analytics, custom interventions)

BRD.md §US-27.6: Given an approved partner extension, When I install it, Then it registers webhooks and admin UI panels under a sandboxed permission model.

DSAR generates JSON+CSV bundle of all subscriber-scoped data within 30 days; encrypted with passphrase, uploaded with expiring secure link

BRD.md §US-28.1: Given a DSAR is submitted, When processed, Then a downloadable JSON + CSV bundle is generated within 30 days and delivered via secure link

Erasure request anonymizes PII within 30 days (email hashed, name "Erased User", addresses null); financial records retained with PII stripped; processor PM deletion at erasure is an operator task requiring live processor adapter

BRD.md §US-28.2: Given an erasure request, When processed, Then all PII is deleted/anonymized within 30 days; financial records retained with PII stripped per legal basis

GET /api/v1/admin/audit-log?from=&to= returns every Event row in date range with actor, action, resource, Convention-12 SCA columns; paginated with cursor

BRD.md §US-28.3: Given I request an export for a date range, When it generates, Then every Event row is included with actor, action, subject, before/after and SCA-defense fields

Card data collected only by processor hosted element (Stripe Elements/Braintree Hosted Fields); our DB stores only opaque payment_method_ref tokens; no PAN/CVV in schema or API

BRD.md §US-28.4: Given any user flow involves card data, When implemented, Then card data is collected only by the processor's hosted element and never touches our servers or DB

SOC 2 Type II evidence captured automatically from controls (access reviews, backup tests, incident drills) via compliance tooling

BRD.md §US-28.5: Given SOC 2 controls are defined, When operations run, Then evidence is captured and stored in our compliance tool

EU-region stores have Postgres and Redis primaries in EU regions

BRD.md §US-28.6: Given a store declares region: eu, When data is stored, Then Postgres and Redis primaries are EU-region

Append-only, tamper-evident retention of every consent + disclosure + reminder record, exportable as a compliance trail; auto-renewal disclosure posture derives from ADR-0079

BRD.md §US-28.7: Given a subscription is created with captured consent, When it is stored, Then an immutable consent record persists and the full compliance trail is exportable on demand

Vitest scenario layer with defineScenario story helper + separate CI run (Hive #583)

Hive #583 — BDD scenario test layer scaffolding + first seed flow

Lifecycle scenario covers create → pause → resume → cancel with event timeline assertions

Hive #583 / BRD §lifecycle flows (US-18.x)

P1 Maya scenarios: annual wine subscription happy-path with U-20 calendar anchor + OOS exception queue surfacing (U-18 partial) + mid-year signup calendar anchor edge case

Hive task fe8d3bd5 / parent synthesis 5cff25f1 / A3 ratification fa3dc5f3 / BRD §US-9.2 + US-10.3 + US-15.1

P2 Alex persona BDD scenarios: AllotmentGrant lifecycle (debit + refresh), cancel, mid-cycle upgrade with proration

Hive #8834674a / BRD §US-6.9 allotment, US-5.x cancel, US-7.x upgrade

P3 Jordan persona BDD scenarios: gift purchase (status=paused + extension + event), gift claim (recipient active), expired claim window (412)

Hive #e9d7f5dc / BRD §US-6.1 gift subscriptions, US-6.2 prepaid

P4 Sam B2B persona BDD scenarios: CS-rep enrollment with PO, commitment_cycles data model (U-17 foundation), buyer-org AllotmentGrant quarterly refresh

Hive #63e46415 / BRD §US-22.9 B2B enrollment (ADR-0023), US-5.7 commitment, US-6.9 allotment

P5 Taylor persona BDD scenarios: subscribe-and-save renewal, dunning retry self-heal, dunning exhaustion → cancel

Hive #b980c6b7 / BRD §US-11.1 dunning policy, US-11.2 retry logic, US-5.7 commitment

processor-auto-detect returns storedPaymentsEnabled field — probes GET /v3/payments/stored-instruments and surfaces warning when disabled

ADR-0037 / P-comp Sub-deliverable B

Portal stored-instruments picker: GET /api/v1/portal/stored-instruments route + StoredInstrumentsPicker.svelte — shoppers pick from vaulted instruments (ADR-0037)

ADR-0037 / P-comp Sub-deliverable C

Portal add-PM IAT flow: POST /api/v1/portal/stored-instruments/iat route + AddStoredInstrumentButton.svelte — shopper adds new card via BC hosted flow (ADR-0037)

ADR-0037 / P-comp Sub-deliverable C

Portal stored-instrument select: backend rejects empty subscription_id with invalidBody; UpdatePaymentForm no longer passes subscriptionId="" to picker in cross-sub mode (proposal #774)

proposal #774 / PR follows

charge-retry-sweep uses await getAdapter(..., storeHash, env) — 4-arg async call per T1S adapter-registry contract (Hive #799). Sync 3-arg call removed.

Hive #799 / PR #798 sibling fix

subscription.renewed event triggers a renewal confirmation email via Resend — email consumer Worker subscribes to subs-events queue and sends to the customer email on file

BRD.md §US-23.1: Given a subscription.renewed event fires, When the email consumer Worker processes the queue message, Then a renewal confirmation email is sent via Resend to the subscriber's email address

Email consumer Worker is wired to the subs-events queue via [[queues.consumers]] in wrangler.toml

BRD.md §US-23.1 + ADR-0010: email consumer must subscribe to subs-events to receive event outbox messages

portal.magic_link_requested event triggers a magic-link sign-in email via Resend — worker.ts routes the queue message to processMagicLinkMessage; link_url + email come from the queue payload (no DB lookup required)

BRD.md §US-17.1: Given a subscriber requests portal access, When the API enqueues portal.magic_link_requested, Then a sign-in email with the magic-link URL is sent via Resend within seconds

Renewal confirmation uses Resend transactional email API (POST /emails); platform-level RESEND_API_KEY secret for v0.1

BRD.md §US-23.1: emails sent via Resend with merchant template + variables; v0.1 uses platform API key, v0.2 adds per-merchant key

Merchant admin can cancel a subscription on behalf of the subscriber, stamping actor_user_id on the events row

BRD.md §US-18.1, §US-18.5: Given admin views a subscription, When they click "Cancel on behalf", Then status becomes cancelled and event records actor_user_id + actor_kind=merchant_user

Cancel-on-behalf action stamps actor_user_id + actor_kind=merchant_user on the events row per US-1.7

BRD.md §US-1.7: Given any merchant-actor mutation, Then events row carries actor_user_id and actor_kind=merchant_user

Merchant admin can retry a specific failed charge by ID from the subscription detail view

BRD.md §US-18.1: Given a failed charge row, When admin clicks "Retry", Then a new pending charge is queued and charge.retry_queued event is emitted

Subscription detail page shows per-charge Retry button for failed charges

BRD.md §US-18.1: Given a failed charge in the history panel, When rendered, Then a Retry button appears that calls retryCharge()

Admin API client module for subscription cancel-on-behalf and per-charge retry

BRD.md §US-18.1: Admin SPA calls typed API client functions rather than raw fetch

Magic-link gated subscription detail page at /portal/subscriptions/[id] — shows plan info, charge history, next charge date, and cancel CTA. Client-side rendered; auth token sourced from sessionStorage.

BRD.md §US-17.x: subscriber portal v0.1.1 — view subscription detail + hard cancel (no churn-prevention flow in v0.1)

Hard-cancel CTA in subscriber portal — CancelSubscriptionButton.svelte shows inline confirmation then calls POST /api/portal/subscriptions/:id/cancel. Churn-prevention (US-18.5) deferred to v0.2.

BRD.md §US-18: subscriber-initiated cancel; v0.1.1 scope is hard-cancel only (no offers, no retention flow)

GET /api/v1/portal/subscriptions/:id — portal-session JWT gated detail endpoint. Returns subscription row with plan info. Anti-IDOR: ownership verified via customer_id from JWT payload.

BRD.md §US-17 + ADR-0014: portal-session JWT HS256 over BC_CLIENT_SECRET; ownership check collapses unknown-id and cross-tenant into 404

SubscriptionDetailView.svelte — displays plan info, status, charge history table, and hosts CancelSubscriptionButton for active subscriptions

BRD.md §US-17.x: portal detail view — plan name, amount, cadence, next charge, charge history

Scripted end-to-end demo at /try/end-to-end orchestrates subscribe → cart → confirm → portal → admin → CTA against the visitor's connected store; mute-by-default Web Speech narration, manual + auto-advance controls

Hive #1259 (AC-5e), dossier docs/handoffs/hive-1143-ac5e-demo-end-to-end-flow.md, parent Hive #1143 AC-5

DomainConfig admin component — provision Resend custom sending domain, display DKIM DNS records, and trigger/display DNS verification status

BRD.md §US-23.9: Given I configure a custom domain, When I provision it, Then I receive DKIM DNS records to publish and can verify propagation

TemplateEditor admin component — subject + body + format fields with debounced live preview via MarkdownPreviewPane; saves to PUT /api/v1/admin/email-templates/:key

BRD.md §US-23.3: Given I open the template editor, When I edit subject/body with variable placeholders, Then I see a debounced preview rendered with sample data

TemplatesList admin component — table of store email templates with Default/Custom badge; clicking Edit navigates to TemplateEditor; warns on empty list with fallback-send notice

BRD.md §US-23.3: Given I open the notifications section, When templates are loaded, Then I see all templates with Default/Custom badges and an Edit action per row

email_send_log schema table — one row per outbound email dispatched; send_key dedup guard (event_id:recipient); vendor_status + bounce_class track Postmark/Resend delivery outcomes for suppression decisioning

ADR-0017 §4 + §6: email_send_log is the idempotent send canonical record; send_key = {event_id}:{lowercased_recipient}; vendor_status IN (queued/sent/delivered/bounced/complaint/failed); bounce_class drives three-strike rule on customers.email_status

Catalog-wide admin list of all merchant plans with status badges and archive actions

BRD.md §Epic 5 — Plan Design: merchant-facing plan management surface; GET /api/plans returns merchant-scoped list

Multi-plan comparison matrix surfacing configuration drift across pricing strategy, commitment, and trial settings

BRD.md §US-5.1: prototype [Plan Comparison](https://subs-portal.pages.dev/design/prototypes/plan-design/comparison)

Merchant editor for typed custom-field definitions on a plan (text, enum, number fields per BRD US-6.11)

BRD.md §US-6.11: As a Merchant Admin, I want to define typed custom fields per plan/subscription/allotment grant

Merchant editor for build-a-box plan configuration (box_size, eligible_variant_ids, customization_window_days)

BRD.md §US-6.3: Build-a-box subscriptions — subscriber picks N items from curated set each cycle

Mutual exclusion rule management for a plan/product pair — prevents overlapping subscription eligibility

BRD.md §US-26.8: Mutual exclusion rules — mutually-exclusive plan/product pairings enforced at checkout

Frontend-only heuristics that scan a merchant plan list for configuration drift (mixed pricing strategies, mismatched trials)

BRD.md §US-5.1: Plan Comparison prototype — per-plan configuration consistency

Plan wizard scope step — channel multi-select (US-7.1) and customer-group multi-select (US-7.2) with Phase-2 country/price-list additions

BRD.md §US-7.1: Plan scoped to specific channels; §US-7.2: Plan scoped to customer groups

Pure helpers and BC API fetchers for ScopeStep — channels proxy (/api/admin/bc/channels) and customer-groups proxy (/api/admin/bc/customer-groups)

BRD.md §US-7.1: Plan scoped to specific channels; §US-7.2: Plan scoped to customer groups

Admin product list with subscription status badges — joins BC catalog products with D1 plan data to show per-product subscription state

BRD.md §US-4.1: "Subscriptions" panel on a BC product — merchants see plan status (none/draft/active) per product

Product detail panel showing current plan status (none/draft/active/paused), offered intervals, pricing summary, and plan CTA

BRD.md §US-4.1: Given I open any BC product, When the product edit page renders, Then the Subscriptions panel appears showing plan status, intervals, pricing, eligibility summary

Step-by-step wizard to enable subscriptions on a product (Interval → Pricing → Options → Eligibility → Review)

BRD.md §US-4.2: Given I click "Configure," When the wizard opens, Then it has steps: Interval(s) → Pricing → Optional extras → Eligibility → Review

Post-activation confirmation screen shown after plan wizard completes — confirms plan saved and storefront widget enabled

BRD.md §US-4.2: Given I complete all steps, When I click "Activate," Then the plan is saved, the product is flagged subscribable, and the storefront widget renders on the PDP

CRUD admin UI for the merchant category-inclusion allowlist — when non-empty, a product is eligible only if at least one BC category is in the list

BRD.md §US-26.1: Product inclusion by category — merchant defines category allowlist for subscription eligibility

CRUD admin UI for the merchant product-exclusion list — excluded products are hidden from subscription enablement

BRD.md §US-26.2: Product exclusion — merchant explicitly excludes products from subscription eligibility

Cross-page session cache that lets ProductDetail/PlanWizard/PlanActivated resolve a product without re-fetching after ProductsList has loaded

BRD.md §US-4.1: Product panel and wizard navigation flow — products stay accessible across wizard steps

Welcome page — post-OAuth landing with hero CTA to setup and next-step cards for plan creation and storefront activation; first-visit gate redirects unconfigured merchants to /v2/onboarding/setup

BRD.md §US-1.2 (signed payload JWT → app load), Hive #1096 + #1148

Registration Health page — surfaces App Extension + webhook registration status with per-item re-register actions; backed by /api/v1/onboarding/health

BRD.md §US-1.3 (App Extensions), §US-1.4 (webhook subscriptions), Hive #392 finding 1 (synthesis #393)

Setup Checklist page — required + optional onboarding items with progress bar; driven by /api/onboarding/checklist; dismissal writes stores.metadata.checklist_dismissed_at

BRD.md §US-1.2 (app first load), Hive #1148 (first-visit gate)

Uninstall Policy page — static disclosure of 30-day data retention, subscription pausing, and PII purge timeline; reached from Welcome before a merchant uninstalls

BRD.md §US-1.5 (uninstall hook, 30-day retention, PII purge)

Storefront onboarding API client — thin fetch wrappers for the auto-detect wizard (channel list, Stencil enable/disable endpoints)

BRD.md §US-1.3 (storefront activation path), Hive #1069 AC-5

Settings → Store → General admin page — surfaces capture_timing (immediate / on_fulfillment / on_ship), read-only country_code, and test_mode_enabled; backed by GET/PATCH /api/v1/admin/settings/store; every save emits settings.changed per Hive #1070 AC-6

BRD.md §US-10.9: capture timing configuration per store (capture_timing persists and is readable at runtime, Phase 1 advisory banner for deferred modes). Hive #1070 Phase 1 AC-2.

Settings → Store → Dunning admin page — thin settings-IA wrapper that mounts RetryRulesPage at the new Settings route; existing /dunning/retry-rules deep links continue to resolve; no UX change per Hive #1070 "relocate-don't-rebuild" pattern

BRD.md §US-11.1: As a Merchant Admin I want to configure retry intervals and exhaustion behavior so that dunning matches my brand and risk tolerance.

Settings → Store → Notifications admin page — navigation hub that cross-links to the existing TemplatesList (/v2/email/templates) and DomainConfig (/v2/email/domain) pages; preserves existing deep-link route shapes; Phase 1 cross-link shape per Hive #1070

BRD.md §US-23.3 (template editor) + §US-23.9 (custom sending domain): merchant discovers and navigates to notification settings from the unified Settings tree.

Settings → Store → Feature Flags admin page — merchant-self-serve behavioural toggles: nudge_lead_days (BRD §US-18.x renewal nudge lead), sync_order_edits_to_subscription, bundle_window_days + allow_mixed_bundle (BRD §US-16.x bundling), reactivation_grace_days (BRD §US-18.7); backed by PATCH /api/v1/admin/settings/store; operator-only flags explicitly excluded per Hive #1063 taxonomy

BRD.md §US-18.x: nudge_lead_days governs term-end renewal nudge timing. BRD §US-16.x: bundle_window_days + allow_mixed_bundle govern order-bundling window. BRD §US-18.7: reactivation_grace_days governs subscriber reactivation window post-cancel.

Settings → Store → Promotions admin page — Phase 1 stub for global promotion settings (stacking rule, subscription-only defaults); cross-links to the existing PromotionsList at /v2/promotions; full content ships in a follow-up slice per Hive #1070 spec note

BRD.md §US-25: global promotion settings (stacking rules, default scope). Phase 1 stub with cross-link to per-promotion management.

Dunning → Retry Rules admin page — merchant UI for configuring per-store dunning_policies: retry stages table (stage_index, delay_hours, on_exhaustion, email_template_key, grace_period_days); inline editing + reset-to-defaults; backed by GET/PUT /api/v1/admin/dunning/policy; referenced by ADR-0031 max-attempts policy constraint

BRD.md §US-11.1: As a Merchant Admin I want to configure retry intervals and exhaustion behavior — retry intervals (array of hours), on_exhaustion (cancel / pause / notify_only), grace period — so that dunning matches my brand and risk tolerance.

referral_codes table — per-subscriber unique code with credit_amount_cents; foundation of the referral credit system (BRD §US-6.8)

BRD.md §US-6.8: Given I have an active subscription, When I access my portal, Then I see a referral link with my unique code

referral_events table — audit trail of signup + first_charge_succeeded + fraud_detected events per referral code (BRD §US-6.8)

BRD.md §US-6.8: Given a referred user signs up through my link, When their first charge succeeds, Then I earn merchant-configured credit applied to my next charge

referral_credits table — awarded credits linked to a referral event; applied to referrer next renewal charge; reversible on fraud detection (BRD §US-6.8)

BRD.md §US-6.8: Given the referral is fraudulent (self-referral, chargebacks), When detection triggers, Then the credit is reversed and logged

authorizations table — stores the result of adapter.authorize() for the on_ship / on_fulfillment capture-timing split; each row tracks status through open → capturing → captured / void / expired lifecycle

ADR-0038 §P2-E: authorizations table persists pre-authorizations when capture_timing ≠ immediate; webhook handler (handleShipmentCreated) reads this table to find the open auth before calling adapter.capture(). Migration: 0029_authorizations_table.sql + 0031_authorizations_extend_status.sql

bundles table — groups co-scheduled subscription charges from the same store into a single BC order; lifecycle: pending → locked → materialized / partially_failed / cancelled

BRD.md §Epic-16 (order bundling): US-16.1 subscriber opt-in, US-16.4 shipping allocation. Migration: 0042_order_bundling.sql

bundle_charges join table — links charges to bundles with a role (anchor / member) and an included flag; shipping_allocation_cents set by the materializer per US-16.4

BRD.md §Epic-16 US-16.4: shipping cost allocation across bundled charges. Migration: 0042_order_bundling.sql

cs_tool_sessions table — short-lived CS impersonation tokens (TTL 15 min); minted when a CS rep clicks "View as subscriber"; the portal resolves the token and enforces read-only mode, logging every action as actor_kind=cs_impersonation

BRD.md §Epic-22 US-22.3: Given a CS rep clicks "View as subscriber", When they receive the portal URL, Then they can browse the subscription in read-only mode with all actions logged. Migration: 0042_cs_tool_sessions.sql

subscription_import_jobs table — tracks bulk CSV import jobs; CS rep uploads CSV, rows validated and staged (status=staging), rep reviews preview then confirms to create subscriptions (status=completed)

BRD.md §Epic-22 US-22.4: Given a CS rep uploads a subscription CSV, When they confirm the preview, Then all valid rows are created as active subscriptions and the job moves to completed. Migration: 0043_subscription_import_jobs.sql

promotion_settings table — annotates BC-native promotion IDs with a subscription_only flag; prevents non-subscriber shoppers from redeeming subscription-only coupons at checkout. Distinct from the cycle-aware subscription_promotions substrate.

BRD.md §Epic-25 US-25.1: subscription-only coupon gating. migration 0039_promotions_subscription_only.sql

subscription_promotions table — standalone cycle-aware promotion entity evaluated by the subscription scheduler on each renewal; separate from BC /v3/promotions (cart-scoped only) per spike #117 / promo-projection.md §1

BRD.md §Epic-25 US-25.1 (Hive #891). Spike #117 / promo-projection.md §3.1. Migration: 0053_subscription_promotions.sql

subscription_promotion_applications table — one attribution row per promo applied per charge; written by the scheduler success branch after adapter.charge() resolves; supports source=subs (our cycle promos) and source=bc (BC-native coupon ingestion)

BRD.md §Epic-25 US-25.1. promo-projection.md §3.3: relational attribution table preferred over charges.promotion_attributions jsonb for FK integrity and refund-on-cancel joins. Migration: 0054_subscription_promotion_applications.sql

store_credits table — credit balance ledger per customer per store; supports merchant-issued credits applied at renewal against the next charge amount (US-12.2)

BRD.md §Epic-12 US-12.2: store credit applied at renewal. Migration: 0062_store_credits.sql (comment references 0060_store_credits.sql)

store_credit_applications table — records each charge-time application of a store credit; supports reversal (reversed_at / reversed_reason) for refund flows

BRD.md §Epic-12 US-12.2: credit application at renewal; US-12.3: reversal on refund. Migration: 0062_store_credits.sql

manual_charges table — records CS-initiated out-of-cycle charges (US-12.4); each row links to a charges row and carries a reason field for the audit trail

BRD.md §Epic-12 US-12.4: manual charge — Given a CS rep initiates an out-of-cycle charge, When the charge succeeds, Then a manual_charges row records the reason and links to the charge. Migration: 0062_store_credits.sql

subscription_discounts table — per-subscription discount rows applied by the scheduler at charge time; supports percent discounts with optional cycle targeting (applies_to_cycle) and consumed-on-fire semantics (applied_at populated, then row retired)

BRD.md §Epic-5 (plan design): discount configuration. §Epic-18 (lifecycle actions): churn-prevention interventions may apply discounts. Migration: 0006_subscription_discounts.sql

subscription_change_requests table — pending subscription-change requests from B2B buyers requiring company admin or CS approval before application; lifecycle: pending → approved → applied / rejected / expired

BRD.md §Epic-24 US-24.3: B2B approval workflow — Given a B2B buyer submits a change request, When a company admin reviews it, Then it is approved or rejected and the subscriber is notified. ADR-0023 (B2B model). Migration: 0050_subscription_change_requests.sql

exceptions_v2 — transitional table created by migration 0005_exceptions_chargeback.sql using the ADR-0008 table-rebuild pattern; immediately renamed to `exceptions` in the same migration. Not a live table post-migration; catalogued to account for the scanner's CREATE TABLE pickup.

BRD.md §Epic-11 (dunning) / §Epic-13 (reconciliation): exceptions tracking. Migration 0005_exceptions_chargeback.sql: creates exceptions_v2, copies from exceptions, drops exceptions, renames exceptions_v2 → exceptions. Pattern matches ADR-0008 table-rebuild.

webhook_delivery_attempts table — per-attempt delivery log for outbound webhooks; tracks status through pending → succeeded / failed → exhausted with exponential retry via next_retry_at; supports the developer platform webhook reliability contract

BRD.md §Epic-27 (developer platform): webhook delivery with retry. webhook_delivery_attempts links to webhook_subscriptions; the delivery worker reads the pending/next_retry_at index to schedule retries. Migration: 0001_baseline.sql

plan_entitlement_configs table — configures entitlement grants per plan (e.g. BC customer group assignment); provider field selects the entitlement backend; UNIQUE (plan_id, entitlement_key) enforces one config per entitlement type per plan

BRD.md §Epic-5 (plan design): entitlement configuration per plan. The entitlement engine reads this table to determine which customer group or other provider to assign on subscription activation. Migration: 0001_baseline.sql

G4: US-1.1 annual subscription signup → active behaves (P1 Maya happy path) (BRD §US-1.1)

ADR-0067 G4 / scenarios.ts scenario-p1-maya-happy-path / synthesis #1597

G4: US-5.7 commitment / cancel-lock behaves — commitment_cycles persisted + cancel 409 cancel_locked within commitment (BRD §US-5.7)

ADR-0067 G4 / synthesis fa3dc5f3 / Hive task 3d6b44b2 (current RED — real behavioral gap)

G4: US-5.1 multiple offered intervals — plan POST persists every {interval, interval_count} into plan_intervals (listPlanIntervals reads them); empty array / bad unit / interval_count<1 → 422. (Impl enforces count>=1 only; BRD N<=24 cap not enforced — soft UX gap noted.) (BRD §US-5.1)

ADR-0067 G4 / epic-5-plan-design.scenario.ts / climb 2026-06-16

G4: US-6.1 gifting behaves — gift purchase → paused, claim → active, expired claim → 412 (P3 Jordan) (BRD §US-6.1)

ADR-0067 G4 / scenarios.ts scenario-p3-jordan-* / synthesis #1597

G4: US-6.5 subscriber cancel behaves → status=cancelled + subscription.cancelled event (P2 Alex) (BRD §US-6.5)

ADR-0067 G4 / scenarios.ts scenario-p2-alex-cancel / synthesis #1597

G4: US-6.9 AllotmentGrant behaves — create → debits → balance=0 → boundary refresh (P2 Alex / P4 Sam) (BRD §US-6.9)

ADR-0067 G4 / scenarios.ts scenario-p2-alex-allotment-grant + scenario-p4-sam-allotment-quarterly-refresh / synthesis #1597

G4: US-9.2 calendar-anchored next_charge_at behaves (P1 Maya) (BRD §US-9.2)

ADR-0067 G4 / scenarios.ts scenario-p1-maya-happy-path / synthesis #1597

G4: US-9.6 affirmative consent capture behaves — order/created with a consent-bearing intent → active + immutable consent_record + consent_captured; with per-store enforcement on and no consent → paused + consent_missing (backend mechanic; BRD §US-9.6)

ADR-0067 G4 / us-9-6-consent-capture.scenario.ts / ADR-0079

G4: US-10.3 mid-year signup → next_charge_at snaps to calendar anchor (P1 Maya) (BRD §US-10.3)

ADR-0067 G4 / scenarios.ts scenario-p1-maya-calendar-anchor / synthesis #1597

G4: US-10.7 future-start behaves — pending_start stays pending while starts_at is future; → active + subscription.activated when starts_at passes (P3 Jordan future-start tests) (BRD §US-10.7)

ADR-0067 G4 / p3-jordan-gifting.scenario.ts [U-19] future-start scheduler activation / Hive task coverage-matrix G4-drain

G4: US-10.6 schedule visualization — portal upcoming-charges returns ≤5 future pending/processing charges ASC by scheduled_at with {amount_cents,currency,status,scheduled_at,cycle_number}; excludes historical; 401 no token, 404 unknown sub (BRD §US-10.6)

ADR-0067 G4 / epic-10-charge-scheduling.scenario.ts / climb 2026-06-16

G4: US-10.1 nightly schedule scan — findDueCharges selects status='pending' charges with scheduled_at <= cutoff (due window), excludes future-dated, never re-enqueues 'processing' (AC bullet 2), skips soft-deleted, ASC by scheduled_at (BRD §US-10.1)

ADR-0067 G4 / epic-10-charge-scheduling.scenario.ts / climb 2026-06-16

G4: US-10.4 charge jitter — computeJitterOffset deterministic + in [0,900); applyJitter shifts the cycle anchor forward by exactly the offset; offsets spread evenly across the 900s window (±10% per 60s bucket) (BRD §US-10.4)

ADR-0067 G4 / epic-10-charge-scheduling.scenario.ts / climb 2026-06-16

G4: US-10.5 pause/resume schedule math — pause N weeks pushes next_charge_at to now + N×7 days; early resume resets next_charge_at to NOW; weeks out of [1,52] → 400; pause cancelled → 409; resume non-paused → 409 (status/event side gated by US-18.3; this gate owns the date math) (BRD §US-10.5)

ADR-0067 G4 / epic-10-charge-scheduling.scenario.ts / climb 2026-06-16

G4: US-10.9 capture-timing config (Phase 1) — store-settings GET/PUT persists + reads stores.capture_timing for all 3 enum values, rejects invalid (400), 404 unknown store; resolveCaptureTiming reads the value at runtime, defaults to 'immediate', applies the EU override (EU country + immediate → mode='on_ship' + euWarning, AC6). Phase-2 enforcement (adapter.capture on shipment/fulfillment) is future + out of scope (BRD §US-10.9)

ADR-0067 G4 / epic-10-charge-scheduling.scenario.ts / climb 2026-06-16

G4: US-11.1 subscribe-and-save renewal charge behaves (P5 Taylor) (BRD §US-11.1)

ADR-0067 G4 / scenarios.ts scenario-p5-taylor-renewal-charge / synthesis #1597

G4: US-11.2 dunning behaves — retry self-heals + 3-stage exhaustion → cancel (P5 Taylor) (BRD §US-11.2)

ADR-0067 G4 / scenarios.ts scenario-p5-taylor-dunning-* / synthesis #1597

G4: US-14.6 mid-cycle upgrade proration behaves → proration charge + plan_id updated + plan_upgraded event (P2 Alex) (BRD §US-14.6)

ADR-0067 G4 / scenarios.ts scenario-p2-alex-upgrade / synthesis #1597

G4: US-15.1 OOS block at renewal → Exception Queue entry surfaced (P1 Maya) (BRD §US-15.1)

ADR-0067 G4 / scenarios.ts scenario-p1-maya-oos-exception-queue / synthesis #1597

G4: US-18.5 lifecycle cancel behaves → status=cancelled + event (P2 Alex) (BRD §US-18.5)

ADR-0067 G4 / scenarios.ts scenario-p2-alex-cancel / synthesis #1597

G4: US-18.3 pause/resume behaves → pause→status=paused, resume→status=active + subscription.paused/resumed events (BRD §US-18.3)

ADR-0067 G4 / subscription-lifecycle.scenario.ts / Phase-1 G4-drain 2026-06-15

G4: US-18.1 skip next charge behaves → upcoming pending charge abandoned reason=skipped + next_charge_at advanced one interval; cancelled sub → 409 (BRD §US-18.1)

ADR-0067 G4 / epic-12-refunds-credits.scenario.ts (US-12.3 skip, re-tagged) / Phase-1b Batch-1 2026-06-15

G4: US-18.2 swap variant behaves → subscriptions.bc_variant_id updated + subscription.variant_swapped event; malformed variant → 400; cancelled sub → 409 (BRD §US-18.2)

ADR-0067 G4 / epic-18-swap.scenario.ts / Phase-1b Batch-1 2026-06-15

G4: US-18.4 reschedule next charge behaves → next_charge_at set to chosen in-window date + subscription.next_charge_rescheduled event; out-of-window (1-90d) → 400; cancelled sub → 409 (BRD §US-18.4)

ADR-0067 G4 / epic-18-reschedule.scenario.ts / Phase-1b Batch-1 2026-06-15

G4: US-18.6 update quantity behaves → subscriptions.quantity updated + subscription.quantity_updated event; below plan min → 400 qty_below_minimum; above max → 400 qty_above_maximum; cancelled sub → 409 (BRD §US-18.6)

ADR-0067 G4 / epic-18-quantity.scenario.ts / Phase-1b Batch-1 2026-06-15

G4: US-18.7 reactivate behaves → cancelled-within-grace → status=active + cancelled_at cleared + next_charge_at=now + subscription.reactivated event; grace expired (>90d) → 409 grace_expired; plan inactive → 409 plan_inactive (BRD §US-18.7)

ADR-0067 G4 / epic-18-reactivate.scenario.ts / Phase-1b Batch-1 2026-06-15

G4: US-18.8 switch cadence behaves → chosen_interval/_count persisted + next_charge_at recomputed + subscription.interval_changed event; cadence not offered by plan → 409 cadence_not_offered (BRD §US-18.8)

ADR-0067 G4 / epic-20-churn.scenario.ts (US-20.4 cadence, re-tagged) / Phase-1b Batch-1 2026-06-15

G4: US-22.9 CS-rep B2B enrollment behaves → active + subscription.b2b_enrolled event (P4 Sam / ADR-0023) (BRD §US-22.9)

ADR-0067 G4 / scenarios.ts scenario-p4-sam-b2b-enrollment / synthesis #1597

G4: US-22.5 force-charge — "charge now" enqueues a pending charge with charge_origin=force_manual + valid chain_position=subsequent at plan amount (#1658 fix); amount_cents_override respected; missing reason→422, unknown/cross-tenant→404, cancelled/duplicate-pending→409 (BRD §US-22.5)

ADR-0067 G4 / epic-22-cs-tools.scenario.ts / #1658 fix / climb 2026-06-15

G4: US-22.3 impersonate (view-only) — mints read_only cs_tool_session (operator_id + subscription_id + ip) + portal_url embeds session id + active-session list; cancelled→403, cross-tenant→404, missing id→400 (BRD §US-22.3)

ADR-0067 G4 / epic-22-cs-tools.scenario.ts / climb 2026-06-15

G4: US-22.6 merchant note — PUT persists metadata.merchant_note (preserving other metadata) + subscription.note_updated event (actor_kind=merchant_user); clear via null; 400 missing/oversized; cross-tenant→404 (BRD §US-22.6)

ADR-0067 G4 / epic-22-cs-tools.scenario.ts / climb 2026-06-15

G4: US-22.7 allotment grant — detail returns grant + debit_history; revoke → status=revoked + revoked_by/reason + allotment_grant.revoked event; missing reason→422, unknown/cross-tenant→404, already-revoked→409 (BRD §US-22.7)

ADR-0067 G4 / epic-22-cs-tools.scenario.ts / climb 2026-06-15

G4: US-22.8 custom-field admin — GET returns active+archived fields w/ current_value; PATCH persists valid edits + subscription.custom_fields_updated event w/ field_diff; regex/required/archived-edit → 422; cross-tenant → 404 (BRD §US-22.8)

ADR-0067 G4 / epic-22-cs-tools.scenario.ts / climb 2026-06-15

G4: US-22.1 manual subscription create — POST → active sub with metadata.source=manual + created_by_user_id + subscription.created event (actor_kind=merchant_user); trial plan → trialing; unknown customer/plan → 404, plan-not-active/no-PM → 412, malformed start_date → 422 (BRD §US-22.1)

ADR-0067 G4 / epic-22-cs-tools.scenario.ts / climb 2026-06-15

G4: US-22.4 bulk CSV — preview stages job (staging + row counts); confirm resolves PM from payment_methods (#1659 fix) → creates subscriptions + marks completed; double-confirm → 409, unknown job → 404, empty CSV → 400, missing columns → 422 (BRD §US-22.4)

ADR-0067 G4 / epic-22-cs-tools.scenario.ts / #1659 fix / climb 2026-06-15

G4: US-11.3 hard/soft decline classification — isTerminal/classifyDecline maps fraud + hard codes → terminal/non-retryable, soft codes → retryable (pure logic over processor response codes; no integration surface) (BRD §US-11.3)

ADR-0067 amendment / [Spec] #1645 Option C / apps/api/test/terminal-classifier.test.ts

G4: US-10.8 first-cycle proration for mid-year calendar-anchor sign-ups — decideFirstCycleProration computes the prorated first charge (pure function over signup date + anchor + price; no integration surface) (BRD §US-10.8)

ADR-0067 amendment / [Spec] #1645 Option C / apps/api/src/services/__tests__/first-cycle-proration.test.ts

G4: US-6.3 build-a-box composition — validateComposition enforces box-size + eligible-variant rules (pure function over items + plan config; no integration surface) (BRD §US-6.3)

ADR-0067 amendment / [Spec] #1645 Option C / apps/api/src/extensions/__tests__/build-a-box.test.ts

G4: US-6.11 plan custom-field config — validateFieldValue enforces per-field type / required / constraints (pure function over field def + value; no integration surface) (BRD §US-6.11)

ADR-0067 amendment / [Spec] #1645 Option C / apps/api/src/extensions/__tests__/custom-fields.test.ts

G4: US-14.1 successful charge → BC /v2/orders POST + charges.bc_order_id persisted; failure → throws (BRD §US-14.1)

ADR-0067 G4 / epic-14-bc-orders.scenario.ts / Hive task a6fc9fc0

G4: US-14.2 order tagged with subscription metadata — staff_notes [SUB] + external_source (BRD §US-14.2)

ADR-0067 G4 / epic-14-bc-orders.scenario.ts / Hive task a6fc9fc0

G4: US-14.3 first-order linkage — cycle-0 charge.bc_order_id + subscription.created_from_order_id preserved (BRD §US-14.3)

ADR-0067 G4 / epic-14-bc-orders.scenario.ts / Hive task a6fc9fc0

G4: US-14.4 order status_id = merchant default_sub_status_id (orders.ts:324, fallback 11); scenario asserts custom status_id is used instead of hardcoded 11 (BRD §US-14.4)

ADR-0067 G4 / epic-14-bc-orders.scenario.ts / Hive task a6fc9fc0

G4: US-14.7 NTI verification before stale-NTI renewal — isNTIStale classifies never-refreshed/aged as stale, fresh-within-window as not stale, and opt-out (nti_freshness_days=0) as not stale (AC5, fixed gap); fireMuseVerificationCharge stub-success persists last_nti_refreshed_at (AC2), no-PM → failure no_payment_method (AC3) (BRD §US-14.7)

ADR-0067 G4 / epic-14-nti-verification.scenario.ts / climb 2026-06-16

G4: US-14.5 order edit sync — store/order/updated runs the Hive #924 3-tier matrix: Tier-2 advisory (subscription.address_edited always; charge.order_total_changed on total mismatch); Tier-1 terminal status (4→refunded, 5/6→failed) CAS transition + charge.external_status_change (idempotent on replay); Tier-3 gated address propagation (sync_order_edits_to_subscription=1) → shipping_address_changed; noop without a matched charge or store token (BRD §US-14.5)

ADR-0067 G4 / epic-14-order-sync.scenario.ts / climb 2026-06-16 (completes Epic-14)

G4: U-19 future start date → pending_start → scheduler activation behaves (P3 Jordan / synthesis fa3dc5f3)

ADR-0067 G4 / scenarios.ts scenario-u19-future-start-date / DoD-4 @ac tag pending

G4: U-20 calendar billing anchor (billing_anchor_month/day → fiscal-year anchor) behaves (P4 Sam / synthesis fa3dc5f3)

ADR-0067 G4 / scenarios.ts scenario-u20-calendar-billing-anchor / DoD-4 @ac tag pending

G4: US-2.1 BC Payments auto-detect — detected→row created+event; not-detected→no row; already active→alreadyActive=true (BRD §US-2.1)

ADR-0067 G4 / epic-2-processor-onboarding.scenario.ts / Hive task 454cbe50

G4: US-2.2 Stripe processor connect — happy-path 201+row, 409 on duplicate, 400 on bad keys, tenant isolation (BRD §US-2.2)

ADR-0067 G4 / epic-2-processor-onboarding.scenario.ts / Hive task 454cbe50

G4: US-2.3 gateway compatibility matrix — shape + bc_payments/stripe=supported, BNPL=not-supported, braintree/authnet=phase-2 (BRD §US-2.3)

ADR-0067 G4 / epic-2-processor-onboarding.scenario.ts / Hive task 454cbe50

G4: US-2.5 processor health check — active→error on failed ping; error→active on recovery; idempotent repeat-error (BRD §US-2.5)

ADR-0067 G4 / epic-2-processor-onboarding.scenario.ts / Hive task 454cbe50

G4: US-2.7 capture timing advisory — stores.capture_timing default immediate + explicit on_fulfillment/on_ship readable (BRD §US-2.7)

ADR-0067 G4 / epic-2-processor-onboarding.scenario.ts / Hive task 454cbe50

G4: US-2.4 sandbox/test mode — materializeBcOrderForCharge prefixes BC order staff_notes with [TEST] for test_mode=1 subs (filterable) and omits it for live subs (AC2); createIncompleteOrderForGift short-circuits to synthetic bc_order_id with zero BC calls when testMode=true (AC1, no real order). AC3 archive-prompt + adapter sandbox-debit routing are G5/live (BRD §US-2.4)

ADR-0067 G4 / epic-2-test-mode.scenario.ts / climb 2026-06-16

G4: US-2.6 multi-processor routing — PATCH sets is_default (single-default constraint enforced); PATCH sets routing_channel_ids; resolveProcessorByChannel picks channel-assigned over default (result differs from default connection); null/unmatched channel falls back to default. Live cross-processor charge execution is G5 (BRD §US-2.6)

ADR-0067 G4 / epic-2-processor-onboarding.scenario.ts / migration 0037 / climb 2026-06-23

G4: US-19.1 per-sub PM update → new payment_method_id + audit event (AC-1); AC-2 dunning reset implemented (resetDunningOnPmUpdate) — status → active + retry_attempt reset (BRD §US-19.1)

ADR-0067 G4 / epic-19-payment-method.scenario.ts / Hive task a06e8a1a

G4: US-19.2 per-sub PM update affects only the target subscription, not siblings (BRD §US-19.2)

ADR-0067 G4 / epic-19-payment-method.scenario.ts / Hive task a06e8a1a

G4: US-19.3 shipping address persisted + audit event (AC-1); AC-2 plan country_codes allowlist blocks disallowed country → 412 (shipping-address.ts:66, US-7.3) (BRD §US-19.3)

ADR-0067 G4 / epic-19-payment-method.scenario.ts / Hive task a06e8a1a

G4: US-19.6 cross-all-subs PM update — all N subs atomic + demotion + audit trail + no-subs 409 (BRD §US-19.6 AC-1/AC-3/AC-4)

ADR-0067 G4 / epic-19-payment-method.scenario.ts / Hive task a06e8a1a

G4: US-17.1 magic-link auth — valid token → session minted + cookie (AC-2 COMPLIANT); expired → 410; consumed → 410 single-use (AC-3 COMPLIANT); session verifier error paths (BRD §US-17.1)

ADR-0067 G4 / epic-17-portal-auth.scenario.ts / Hive task 18ded305

G4: US-17.2 BC storefront SSO — valid handoff → session minted; magic-link customer bc_customer_id backfilled; SSO_HANDOFF_SECRET unset → 503 (BRD §US-17.2)

ADR-0067 G4 / epic-17-portal-auth.scenario.ts / Hive task 18ded305

G4: US-25.1 valid coupon attaches to active_promotion_ids + increments current_redemptions; unknown code → attach_failed event, sub still created (BRD §US-25.1)

ADR-0067 G4 / epic-25-promotions.scenario.ts / Hive task 3c89a5db

G4: US-25.3 cycle-discount snapshot at creation (first_cycle_only→cycle_max=1); lock-at-creation immutable; resolveDiscountStack exclusive+stackable+cap (BRD §US-25.3)

ADR-0067 G4 / epic-25-promotions.scenario.ts / Hive task 3c89a5db

G4: US-25.4 findActiveTier resolves correct tier per cycle; detectTenureTierCrossing detects boundary; first-cycle entry reported (BRD §US-25.4)

ADR-0067 G4 / epic-25-promotions.scenario.ts / Hive task 3c89a5db

G4: US-25.5 evaluateSubscriptionPromotions exclusive picks highest-computed-cents; stackable sums+caps; empty list=zero (BRD §US-25.5)

ADR-0067 G4 / epic-25-promotions.scenario.ts / Hive task 3c89a5db

G4: US-25.6 evaluateFreeShippingEligibility gates (unconditional/cycle-floor/threshold/AND); evaluateFreeShippingPromos match or null (BRD §US-25.6)

ADR-0067 G4 / epic-25-promotions.scenario.ts / Hive task 3c89a5db

G4: US-25.7 gift every N cycles — evaluateGiftItemEligibility cycle_modulo fires on correct cycles; evaluateGiftItemPromos DB pass (BRD §US-25.7)

ADR-0067 G4 / epic-25-promotions.scenario.ts / Hive task 3c89a5db

G4: US-25.8 gift-with-subscription — evaluateGiftItemEligibility first_cycle_only fires on cycle 0 only; evaluateGiftItemPromos DB pass (BRD §US-25.8)

ADR-0067 G4 / epic-25-promotions.scenario.ts / Hive task 3c89a5db

G4: US-25.9 promotion report — handleSubscriptionPromotionReport period aggregation (redemptions/charges/total + source_breakdown subs vs bc, out-of-window excluded), active-subscription attributed-MRR snapshot, retention insufficient-data guard (<30 cancellations → null lift); unknown/cross-tenant promo → 404, missing/bad/reversed period → 400. (US-25.2 sibling is a Svelte storefront badge — G5, not an API gate.) (BRD §US-25.9)

ADR-0067 G4 / epic-25-promotion-report.scenario.ts / climb 2026-06-16

G4: US-25.10 3-tier cycle-discount ladder (ADR-0080) — resolveCycleDiscount boundary resolution across tiers (lower/upper bounds, open-ended last tier, pre-ladder gap→0, backward-compat null/empty→fallbackPct); ladder plan write-path is a disjoint-path guard (snapshotPlanCycleDiscount writes no row when a ladder is present) (BRD §US-25.10)

ADR-0067 G4 / ADR-0080 / epic-25-promotions.scenario.ts / synthesis #1836

G4: US-21.1 dashboard KPI summary — 4 tiles (active_subs/mrr/total_subs/active_plans), sparkline[30], delta_direction ∈ enum, tenant-isolated (BRD §US-21.1)

ADR-0067 G4 / epic-21-merchant-dashboard.scenario.ts / Hive task 8c23a478

G4: US-21.2 upcoming charges panel — 7d/30d window contiguous daily_buckets + total_cents + HTTP overlay path (BRD §US-21.2)

ADR-0067 G4 / epic-21-merchant-dashboard.scenario.ts / Hive task 8c23a478

G4: US-21.3 exception queue — list by impact/age, filter by type, mark-resolved → exception.resolved event + 409 on duplicate + 422 on missing note (BRD §US-21.3)

ADR-0067 G4 / epic-21-merchant-dashboard.scenario.ts / Hive task 8c23a478

G4: US-21.4 subscription list — paginated rows with customer/plan/status/MRR/next_charge/cycles_completed columns + status filter + tenant isolation (BRD §US-21.4)

ADR-0067 G4 / epic-21-merchant-dashboard.scenario.ts / Hive task 8c23a478

G4: US-21.6 subscription detail exception strip — dashboard exceptions summary: open_count/high_count/top_three by impact + severity thresholds (BRD §US-21.6)

ADR-0067 G4 / epic-21-merchant-dashboard.scenario.ts / Hive task 8c23a478

G4: US-26.1 category allowlist — no-allowlist passes all; isAnyCategoryIncluded matches; mocked storefront excluded_by=category_allowlist when product categories not in allowlist (BRD §US-26.1)

ADR-0067 G4 / Epic-26 / Hive task 210219a7

G4: US-26.2 product exclusion — excluded product returns plans=[]+excluded:true; exclusion wins over category allowlist; handlePlanPost on excluded product → 412; tenant isolation (BRD §US-26.2)

ADR-0067 G4 / Epic-26 / Hive task 210219a7

G4: US-26.3 variant-level eligibility — plan.bc_variant_id set for allowed variant; unlisted variant not served the variant-scoped plan (BRD §US-26.3)

ADR-0067 G4 / Epic-26 / Hive task 210219a7

G4: US-26.5 customer_group scope — non-member shopper excluded_by=customer_group; guest (group=0) excluded from group-restricted plan; member sees plan; null-means-all visible to guest (BRD §US-26.5)

ADR-0067 G4 / Epic-26 / Hive task 210219a7

G4: US-26.6 geo restriction — out-of-region shopper excluded_by=geo_restriction; in-region sees plan; case-insensitive country_code; tenant isolation (BRD §US-26.6)

ADR-0067 G4 / Epic-26 / Hive task 210219a7

G4: US-26.7 qty bounds — below min → allowed:false qty_below_minimum; above max → allowed:false qty_above_maximum; within [min,max] → allowed:true; boundary values; tenant isolation (BRD §US-26.7)

ADR-0067 G4 / Epic-26 / Hive task 210219a7

G4: US-26.8 mutex rules — active sub to product A blocks B with blocking_subscription_id; symmetric; clean customer allowed; tenant isolation (BRD §US-26.8)

ADR-0067 G4 / Epic-26 / Hive task 210219a7

G4: US-26.10 eligibility audit — trace with rule_type+outcome per step; detail includes input values; product_exclusion fail in trace; missing params → 422 (BRD §US-26.10)

ADR-0067 G4 / Epic-26 / Hive task 210219a7

G4: US-4.1 panel data — handlePlansList returns plan for subscribable product + empty for no-plan product; handlePlanGet returns correct shape; tenant-isolated (BRD §US-4.1)

ADR-0067 G4 / epic-4-enable-subscription.scenario.ts / Hive task ecceb305

G4: US-4.2 plan activate → 201 + status=active + plan persisted; draft → status=draft not activated; invalid body → 422 (BRD §US-4.2)

ADR-0067 G4 / epic-4-enable-subscription.scenario.ts / Hive task ecceb305

G4: US-4.3 variant eligibility — eligible_variant_ids subset persisted in plan_variant_eligibility; null → all variants eligible (no join rows) (BRD §US-4.3)

ADR-0067 G4 / epic-4-enable-subscription.scenario.ts / Hive task ecceb305

G4: US-4.4 stop new signups — accepting=false → accepting_new_subscribers=0; re-enable → 1; existing subs untouched; idempotent; unknown plan → 404 (BRD §US-4.4)

ADR-0067 G4 / epic-4-enable-subscription.scenario.ts / Hive task ecceb305

G4: US-4.5 copy plan between products — handleAdminPlanCopy multi-target copy carries source settings forward + per-target succeeded/failed summary; conflict (target already has a plan, incl. self-copy) → already_has_plan; duplicate targets de-duped; empty/negative/non-array → 422, malformed JSON → 400, unknown source → 404 (BRD §US-4.5)

ADR-0067 G4 / epic-4-enable-subscription.scenario.ts / climb 2026-06-16 (completes Epic-4)

G4: US-16.1 portal bundle_opt_in toggle → persists to subscription; 409 conflict when sub is in a non-terminal (locked/pending) bundle (BRD §US-16.1)

ADR-0067 G4 / Epic-16 / Hive task a48dff96

G4: US-16.2 single BC order per bundle — combined line items tagged w/ all sub+charge ids; partial-failure excludes failed sub from order + staff_notes; bundle status partially_failed (BRD §US-16.2)

ADR-0067 G4 / Epic-16 / Hive task a48dff96

G4: US-16.3 merchant view — staff_notes contains [BUNDLE] + contributing sub IDs; handleAdminBundleDetail returns line-item→subscription attribution; partially_failed surfaces excluded members (BRD §US-16.3)

ADR-0067 G4 / Epic-16 / Hive task a48dff96

G4: US-16.4 proportional shipping allocation — shipping_allocation_cents per charge proportional to amount_cents/total; ratio within 1% (BRD §US-16.4)

ADR-0067 G4 / Epic-16 / Hive task a48dff96

G4: US-12.1 refund — full refund → charge.status=refunded + charge.refunded event; partial refund → status=refunded + refund_amount_cents < amount_cents (synthesis #1633); double-refund 409; over-amount 422; processor-fail 502; tenant isolation (BRD §US-12.1)

ADR-0067 G4 / epic-12-refunds-credits.scenario.ts / Hive task 691fd9e0

G4: US-12.3 portal skip — pending charge abandoned reason=skipped + next_charge_at advanced; cancelled sub → 409 conflict (BRD §US-12.3)

ADR-0067 G4 / epic-12-refunds-credits.scenario.ts / Hive task 691fd9e0

G4: US-12.2 store credit issuance → store_credits row active + credit.issued event + balance query reflects issued amount (BRD §US-12.2)

ADR-0067 G4 / epic-12-refunds-credits.scenario.ts / Hive task 691fd9e0

G4: US-12.4 manual charge — ad-hoc charge executed via mock processor → succeeded + charge.manual_succeeded event; cancelled sub → 409 conflict (BRD §US-12.4)

ADR-0067 G4 / epic-12-refunds-credits.scenario.ts / Hive task 691fd9e0

G4: US-12.6 tax-on-refund — partial refund of a taxed charge prorates tax (refund_tax_cents = round(tax_cents * refund/amount)); processor refunds the GROSS (pre-tax + prorated tax); charge records refund_amount_cents (pre-tax) + refund_tax_cents. Untaxed charges → 0 (unchanged). bc_payments order-side tax reflection is G5. (BRD §US-12.6)

ADR-0067 G4 / epic-12-refunds-credits.scenario.ts / migration 0026 / climb 2026-06-16

G4: US-23.16 Resend webhook ingestion — valid signature → email_sends row updated; hard-bounce → suppression entry; soft-bounce → no suppression; complaint → suppression; idempotent replay → noop (BRD §US-23.16)

ADR-0067 G4 / Epic-23 / Hive task 713b1dcb

G4: US-23.11 suppression — suppressed recipient → handleEmailQueue drops the send (no email_sends row); unsubscribed+transactional → bypassed (send proceeds); unsubscribed+marketing → dropped; bounced+transactional → dropped; re-opt-in removes entry + subscriber.resubscribed (BRD §US-23.11)

ADR-0067 G4 / Epic-23 / Hive task 713b1dcb

G4: US-23.13 decline translation — each issuer code → friendly copy (no raw codes); requires_action → SCA CTA + cta_kind=complete_sca; hard-fraud → send_email=false; unknown → generic-soft fallback (BRD §US-23.13)

ADR-0067 G4 / Epic-23 / Hive task 713b1dcb

G4: US-23.8 outbound webhooks — register endpoint → enqueue → HMAC-signed POST with X-Subs-Signature; 5xx → retry/backoff; 4xx non-429 → exhausted immediately; max-attempts → dead-lettered (BRD §US-23.8)

ADR-0067 G4 / Epic-23 / Hive task 713b1dcb

G4: US-23.12 magic-link token mechanics — issue → hash persisted, plaintext not stored; verify once → success; replay → rejected (single-use); expired → rejected; nonexistent → rejected (BRD §US-23.12)

ADR-0067 G4 / Epic-23 / Hive task 713b1dcb

G4: US-23.3 template editor — save persists template; next render uses it; preview renders with sample data; invalid body → typed error shape (BRD §US-23.3)

ADR-0067 G4 / Epic-23 / Hive task ad0ac41d

G4: US-23.14 failed-render fallback — MJML/compile fail → system fallback body produced + render_failed_event set; unallowed variable → safe placeholder substituted + event fired; clean template → no event (BRD §US-23.14)

ADR-0067 G4 / Epic-23 / Hive task ad0ac41d

G4: US-23.15 idempotent send — same idempotency key returns cached response without re-invoking handler; different body with same key → 409 conflict (BRD §US-23.15)

ADR-0067 G4 / Epic-23 / Hive task ad0ac41d

G4: US-23.17 localization MVP — locale=fr-FR returns en-US template body (no translation produced); store-scoped template is the locale resolution anchor (BRD §US-23.17)

ADR-0067 G4 / Epic-23 / Hive task ad0ac41d

G4: US-28.1 DSAR export — buildDsrExport collects subscriber-scoped customer/subscriptions/charges/payment_methods/events from one store; cross-store tenant isolation (bundle for storeA excludes storeB rows); admin handleAdminDsarExport returns 200 JSON with all table sections + operation_id (BRD §US-28.1)

ADR-0067 G4 / Epic-28 / Hive task 00237ffe

G4: US-28.2 erasure — PII scrubbed (email hashed/name='Erased User'/addresses null), sub is_deleted=1+status='cancelled' (tombstoneCustomerData:5288), charges RETAINED PII-stripped (not tombstoned — 7yr financial retention per BRD), immutable audit entry (customer.dsar_erased event), control subscriber untouched (BRD §US-28.2)

ADR-0067 G4 / Epic-28 / Hive task 00237ffe

G4: US-28.3 audit log export — date-range filter returns only in-range events; tenant isolation excludes cross-store rows; actor_user_id/type/payload/created_at/resource_type/resource_id/summary/operation_type fields present; pagination cursor_next advances then nulls on last page; missing `from` returns 400 (BRD §US-28.3)

ADR-0067 G4 / Epic-28 / Hive task 00237ffe

G4: US-24.1 B2B enrollment → subscription.metadata.b2b=true + company_name; portal B2B list returns subscription; tenant isolation (other customer → empty); view_only effective_role + empty allowed_actions (BRD §US-24.1)

ADR-0067 G4 / Epic-24 / Hive task 7039428a

G4: US-24.3 B2B approval workflow — submit→pending (sub unchanged); approve→status=approved+reviewer set; reject→status=rejected+reason (sub UNCHANGED); approve-already-approved→412; view_only submit→403 (BRD §US-24.3)

ADR-0067 G4 / Epic-24 / Hive task 7039428a

G4: US-24.4 PO payment enrollment → metadata.payment_method_type=po + po_number + net_terms_days; payment_method_id=null (no card required); missing po_number → 422 (BRD §US-24.4)

ADR-0067 G4 / Epic-24 / Hive task 7039428a

G4: US-24.9 admin CS-rep enrollment annotation → metadata.source=cs_impersonation + enrolled_by_user_id persisted on created subscription (BRD §US-24.9)

ADR-0067 G4 / Epic-24 / Hive task 7039428a

G4: US-24.5 company hierarchy MRR rollup — enrollment stores company_id + parent_company_id; GET /admin/b2b/company-mrr?company_id=X rolls up direct + child subs by parent_company_id; empty result for unknown company; monthly normalisation correct for month/year/week intervals (BRD §US-24.5)

ADR-0067 G4 / Epic-24 / Hive task 7039428a north-star

G4: US-24.6 volume-tier renewal pricing — PUT plan/:id/b2b-volume-tiers stores tiers; GET reads them back; resolveVolumeTier() returns correct pct for qty in range + open-ended tier + no-match=0; scheduler leg (live BC charge) is G5-terminal (BRD §US-24.6)

ADR-0067 G4 / Epic-24 / Hive task 7039428a north-star

G4: US-24.8 multi-location shipping — PUT b2b/subscriptions/:id/locations stores delivery_locations; GET returns expandDeliveryLocations() intents with per-location line_total_cents; sum = total_charge_cents; non-B2B sub → 412; BC order-per-location creation is G5-terminal (BRD §US-24.8)

ADR-0067 G4 / Epic-24 / Hive task 7039428a north-star

G4: US-24.10 org_admin portal — org_admin sees subs where they are org_admin actor; non-actor gets 403 on payer/cancel; PATCH payer updates subscription.payment_method_id + audit attributes actor_role=org_admin; POST cancel flips status=cancelled + audit actor_id=org_admin_customer_id + beneficiary_customer_id in extras (BRD §US-24.10)

ADR-0067 G4 / Epic-24 / Hive task 7039428a north-star

G4: US-13.1 event timeline — handleAdminSubscriptionEvents returns events with type+actor_kind+actor_user_id+payload+created_at, ordered desc; DB-level type filter narrows; tenant isolation (wrong store → empty) [Spec-Reconciliation: ?type= query param not yet forwarded by route handler] (BRD §US-13.1)

ADR-0067 G4 / Epic-13 / Hive task 29cb0d53

G4: US-13.2 reconciliation sweep — drift (succeeded+no-bc_order_id+>24h) → reconciliation_drifts row with drift_type=missing_bc_order+charge_id+detail; clean charge (bc_order_id set) → NO drift; run row status=succeeded+drift_count; tenant isolation (per-store); handleAdminReconciliationLatest returns {run,drifts} post-sweep; unswept store → {run:null,drifts:[]} (BRD §US-13.2)

ADR-0067 G4 / Epic-13 / Hive task 29cb0d53

G4: US-13.3 replay materialization — already-materialized → 200 noop=true (no re-call); wrong status (failed) → 409 conflict; cross-tenant → 404; succeeded+missing bc_order_id → materializeBcOrderForCharge called (mocked) → bc_order_id set; idempotency: second call on now-materialized → noop (BRD §US-13.3)

ADR-0067 G4 / Epic-13 / Hive task 29cb0d53

G4: US-20.1 cancel reason captured — handlePortalCancelSubscription persists cancel_reason on subscription + subscription.cancelled event with extras.reason; already-cancelled → 409 conflict; tenant isolation (cross-store JWT → 404/403) (BRD §US-20.1)

ADR-0067 G4 / Epic-20 / Hive task 34a1cf78

G4: US-20.2 pause intervention — handlePortalPauseSubscription → status=paused (NOT cancelled) + subscription.paused event; paused sub stays not-cancelled; churn.intervention_* events absent (grep-proven gap noted) (BRD §US-20.2)

ADR-0067 G4 / Epic-20 / Hive task 34a1cf78

G4: US-20.3 discount intervention — handlePortalApplyDiscount → subscription_discounts row (percent, reason=cancel_flow_save, applied_at=null) + subscription.discount_applied event; frequency cap HONEST-RED: second apply within cap window → 409 REQUIRED by BRD but NOT guarded by impl (BRD §US-20.3)

ADR-0067 G4 / Epic-20 / Hive task 34a1cf78

G4: US-20.4 cadence-change intervention — handlePortalSwitchInterval → chosen_interval/chosen_interval_count persisted + next_charge_at recomputed + subscription.interval_changed event; cadence_not_offered → 409; tenant isolation (BRD §US-20.4)

ADR-0067 G4 / Epic-20 / Hive task 34a1cf78

G4: US-20.5 product-issue cancel → merchant-configured support handoff — handlePortalCancelSubscription with reason "Product issue" + an active helpdesk connection files a helpdesk ticket (provider gorgias, status created); a non-product-issue cancel files none; both subs end cancelled. (Cancel.ts wiring shipped with US-23.6, which owns the Gorgias/Zendesk delivery + idempotency.) (BRD §US-20.5)

ADR-0067 G4 / epic-20-churn.scenario.ts / climb 2026-06-16

G4: US-8.1 subscription-options — sales_mode variants (subscribe_only/one_time_only/subscribe_and_one_time) + no-plans→one-time fallback (plans=[] no excluded flag) + eligibility-gated excluded:true + B2B-gated excluded_by=b2b_only + inactive plans filtered + invalid params 422 (BRD §US-8.1)

ADR-0067 G4 / Epic-8 / Hive task 7644d87d

G4: US-27.1 public API key auth — valid key+scope→200; wrong scope→403; revoked/invalid/missing→401; tenant isolation (BRD §US-27.1)

ADR-0067 G4 / ADR-0068 / Epic-27 / Hive task 9e198384

G4: US-27.2 API key mgmt — create returns plaintext once + scoped; list omits secret; revoke→401 (BRD §US-27.2)

ADR-0067 G4 / ADR-0068 / Epic-27 / Hive task 9e198384

G4: US-7.1 plan channel scope — out-of-channel shopper excluded (plan absent); in-channel included (BRD §US-7.1)

ADR-0067 G4 / Epic-7

G4: US-7.2 customer group scope — non-member + guest excluded (excluded_by=customer_group); member included (BRD §US-7.2)

ADR-0067 G4 / Epic-7

G4: US-7.3 geo / country scope — out-of-region excluded (excluded_by=geo_restriction); in-region included; case-insensitive (BRD §US-7.3)

ADR-0067 G4 / Epic-7

G4: US-7.4 price-list scope — non-matching price_list_id excluded (plan absent); matching included; no price_list_id param = null-means-all (BRD §US-7.4)

ADR-0067 G4 / Epic-7

G4: US-7.5 plan coverage matrix — handlePlanCoverage returns channels/customer_groups/countries/price_lists; null = all; wrong store → 404 (BRD §US-7.5)

ADR-0067 G4 / Epic-7

G4: US-1.2 /api/load verifies signed_payload_jwt — bad token 401 (no cookie), valid token 302 (BRD §US-1.2)

ADR-0067 G4 / epic-1-onboarding-identity.scenario.ts / climb 2026-06-16

G4: US-1.5 uninstall clears credential + emits idempotent audit events, missing token 401 (BRD §US-1.5)

ADR-0067 G4 / epic-1-onboarding-identity.scenario.ts / climb 2026-06-16

G4: US-1.6 first load upserts users row, re-load advances last_seen_at + keeps first_seen_at (BRD §US-1.6)

ADR-0067 G4 / epic-1-onboarding-identity.scenario.ts / climb 2026-06-16

G4: US-1.7 mutating events stamped actor_user_id + actor_kind, system events NULL/system (BRD §US-1.7)

ADR-0067 G4 / epic-1-onboarding-identity.scenario.ts / climb 2026-06-16

G4: US-5.3 price-list renewal re-reads variant price from BC Price List (BRD §US-5.3)

ADR-0067 G4 / epic-5-plan-design.scenario.ts / climb 2026-06-16

G4: US-5.4 fixed-price renewal carries prior amount forward, ignores catalog (BRD §US-5.4)

ADR-0067 G4 / epic-5-plan-design.scenario.ts / climb 2026-06-16

G4: US-5.5 free trial yields status=trialing + next_charge_at deferred by trial_days (BRD §US-5.5)

ADR-0067 G4 / epic-5-plan-design.scenario.ts / climb 2026-06-16

G4: US-5.6 locked_price_cents snapshotted at creation + wins over catalog/price-list at renewal (BRD §US-5.6)

ADR-0067 G4 / epic-5-plan-design.scenario.ts / climb 2026-06-16

G4: US-5.9 calendar anchor returns nearest future occurrence + renewal snaps to anchor (BRD §US-5.9)

ADR-0067 G4 / epic-5-plan-design.scenario.ts / climb 2026-06-16

G4: US-6.2 prepaid upfront-total preflight + cycle decrement + prepaid.depleted renewal prompt at depletion (BRD §US-6.2)

ADR-0067 G4 / epic-6-subscription-extensions.scenario.ts / climb 2026-06-16

G4: US-6.4 bundle plan all-SKUs-ready renewal + OOS exception flag (no silent downgrade) (BRD §US-6.4)

ADR-0067 G4 / epic-6-subscription-extensions.scenario.ts / climb 2026-06-16

G4: US-6.6 usage-based per-cycle accumulation + idempotency + charge = sum*price + base (BRD §US-6.6)

ADR-0067 G4 / epic-6-subscription-extensions.scenario.ts / climb 2026-06-16

G4: US-6.7 curation sequential SKU rotation pick per cycle + no-rules plan-default path (BRD §US-6.7)

ADR-0067 G4 / epic-6-subscription-extensions.scenario.ts / climb 2026-06-16

G4: US-6.8 referral unique idempotent code + credit on referred first charge + self-referral fraud + reversal (BRD §US-6.8)

ADR-0067 G4 / epic-6-subscription-extensions.scenario.ts / climb 2026-06-16

G4: US-6.10 multi-actor owner/payer/beneficiary rows + payer-unique validate + partial-index DB enforcement + dedup (BRD §US-6.10)

ADR-0067 G4 / epic-6-subscription-extensions.scenario.ts / climb 2026-06-16

G4: US-9.1 line-item custom fields carry subscription intent — fetchOrderLineCustomFieldIntents extracts {sub_plan_id, sub_interval_key, sub_quantity}, drops non-sub lines, coerces bad qty to 1, resolveCustomFieldIntent resolves active plan (BRD §US-9.1)

ADR-0067 G4 / epic-9-checkout-capture.scenario.ts / climb 2026-06-16

G4: US-9.3 post-purchase fallback capture — handleAttachSubscription creates active subscription linked via created_from_order_id with cycle-0 succeeded + cycle-1 pending charges, idempotent on replay (BRD §US-9.3)

ADR-0067 G4 / epic-9-checkout-capture.scenario.ts / climb 2026-06-16

G4: US-9.4 mixed-cart checkout — a cart with one subscription line and multiple one-time lines yields exactly one subscription-creation candidate (BRD §US-9.4)

ADR-0067 G4 / epic-9-checkout-capture.scenario.ts / climb 2026-06-16

G4: US-9.5 third-party checkout declaration — store-capabilities reads stores.checkout_supports_custom_fields (declared via settings PUT): undeclared/NULL → supported, no banner (degrade-safe); =false → incompatible checkout + named fallbacks [header_script, thank_you_fallback, manual_admin_reconciliation]; re-declaring true clears it. (Auto-detecting the checkout provider from a live probe is future = G5.) (BRD §US-9.5)

ADR-0067 G4 / epic-9-checkout-capture.scenario.ts / migration 0027 / climb 2026-06-16

G4: US-10.2 charge executor idempotency — createCharge UNIQUE-index dedup rejects same-cycle replay (no double-charge), different cycle succeeds, processing charge never re-enqueued (BRD §US-10.2)

ADR-0067 G4 / epic-10-charge-scheduling.scenario.ts / climb 2026-06-16

G4: US-11.5 subscriber PM update on a past_due sub resets dunning + re-arms retry (BRD §US-11.5)

ADR-0067 G4 / epic-11-dunning.scenario.ts / climb 2026-06-16

G4: US-11.6 failed-charge retry enqueues subscriber email notification with next-retry + amount (BRD §US-11.6)

ADR-0067 G4 / epic-11-dunning.scenario.ts / climb 2026-06-16

G4: US-12.5 chargeback dispute webhook routes to exception queue (BRD §US-12.5)

ADR-0067 G4 / epic-12-refunds-credits.scenario.ts / climb 2026-06-16

G4: US-15.2 renewal carries locked_price_cents not plan amount, non-locked carries charge amount forward (BRD §US-15.2)

ADR-0067 G4 / epic-15-renewal-recalc.scenario.ts / climb 2026-06-16

G4: US-15.6 pre-renewal OOS check applies pause/skip_cycle/notify_and_wait policy and escalates notify_and_wait to Exception Queue (BRD §US-15.6)

ADR-0067 G4 / epic-15-renewal-recalc.scenario.ts / climb 2026-06-16

G4: US-17.5 headless portal SDK — getSubscriptions returns typed list + performAction(pause) applies server-side (BRD §US-17.5)

ADR-0067 G4 / epic-17-portal-auth.scenario.ts / climb 2026-06-16

G4: US-18.9 term-end re-up confirm advances term_end_at one term, clears pending_renewal_decision, emits subscription.term_renewed (BRD §US-18.9)

ADR-0067 G4 / epic-18-term-cancel-lock.scenario.ts / climb 2026-06-16

G4: US-18.10 cancel-lock guard — locked sub → 409 cancel_locked + lock_expires_at, unlocked → standard cancel (BRD §US-18.10)

ADR-0067 G4 / epic-18-term-cancel-lock.scenario.ts / climb 2026-06-16

G4: US-19.4 billing address update stored with the PM (BRD §US-19.4)

ADR-0067 G4 / epic-19-payment-method.scenario.ts / climb 2026-06-16

G4: US-21.5 bulk pause/cancel/skip — per-id succeeded/failed split, skip abandons same-day charge + advances next_charge_at, cancel sets cancel_reason/cancelled_at, tenant not_found, already_cancelled, 422 validation (BRD §US-21.5)

ADR-0067 G4 / epic-21-merchant-dashboard.scenario.ts / climb 2026-06-16

G4: US-21.7 subscription CSV export — synchronous streaming text/csv attachment, header order, mrr_cents=2999 active/0 cancelled, status filter, ?format=json→422, tenant-isolated header-only (BRD §US-21.7)

ADR-0067 G4 / epic-21-merchant-dashboard.scenario.ts / climb 2026-06-16

G4: US-21.8 analytics — cohort retention matrix (cohort_size, retention_by_cycle, max_cycle=12) + LTV 12m/24m monotonic geometric projections + tenant isolation (BRD §US-21.8)

ADR-0067 G4 / epic-21-merchant-dashboard.scenario.ts / climb 2026-06-16

G4: US-23.10 deliverability monitoring throttles on bounce>5% / pauses on complaint>0.3% / auto-resumes on recovery (BRD §US-23.10)

ADR-0067 G4 / epic-23-delivery.scenario.ts / climb 2026-06-16

G4: US-24.2 role-based portal permissions — view_only allowed_actions=[] + 403 on submit; buyer 5 actions + 201 (BRD §US-24.2)

ADR-0067 G4 / epic-24-b2b.scenario.ts / climb 2026-06-16

G4: US-26.4 require_custom_field eligibility — BC custom-field mismatch blocks, match allows, no-rule fast-path (BRD §US-26.4)

ADR-0067 G4 / epic-26-eligibility.scenario.ts / climb 2026-06-16

G4: US-27.3 outbound webhook subscriptions — register endpoint → HMAC-signed POST on matching event; non-2xx → exponential backoff retry → dead-letter (BRD §US-27.3)

ADR-0067 G4 / epic-27-api-keys.scenario.ts / climb 2026-06-16

G4: US-1.3 App Extension panels registered on install — handleOAuthCallback fires registerInstallAppExtensions → ORDERS/PRODUCTS/CUSTOMERS panels created via BC GraphQL mutation (BRD §US-1.3)

ADR-0067 G4 / epic-1-install-registration.scenario.ts / climb 2026-06-17

G4: US-1.4 webhook subscriptions registered on install — handleOAuthCallback fires registerWebhooksForStore → hook POST per scope to <origin>/webhooks/bc; idempotency: list-first, no dups (BRD §US-1.4)

ADR-0067 G4 / epic-1-install-registration.scenario.ts / climb 2026-06-17

G4: US-5.8 minimum term policy — lock_expires_at computed at creation (cycles: +N months; days: +N days); early cancel within term → 409 cancel_locked + lock_expires_at; fee plan charges early_cancel_fee_cents at cancel (BRD §US-5.8)

ADR-0067 G4 / epic-5-minimum-term-policy.scenario.ts / climb 2026-06-17

G4: US-11.4 network account updater VAU/ABU — payment_method.automatically_updated → card row updated active + past_due sub re-armed (dunning suppressed); idempotent on replay; no-match PM → 200 noop (BRD §US-11.4)

ADR-0067 G4 / epic-11-network-updater.scenario.ts / climb 2026-06-17

G4: US-11.7 in-dunning subscriber digest — buildDunningDigest returns past_due subs MRR-desc; active control excluded; retry_attempt per row; days-in-dunning anchored on earliest failure event (not charges.attempted_at) (BRD §US-11.7)

ADR-0067 G4 / epic-11-dunning-digest.scenario.ts / climb 2026-06-17

G4: US-13.4 charge-scoped correlation logger — every structured log line from processCharge carries charge_id + subscription_id; charge.started + charge.completed bookends present (BRD §US-13.4)

ADR-0067 G4 / epic-13-us134-correlation.scenario.ts / climb 2026-06-17

G4: US-15.3 tax recalculation at renewal — BC consignment probe applies jurisdiction tax (tax_cents + tax_source=bc_estimate); BC error fallback → charge succeeds, tax_cents=0, tax_source=fallback_zero (BRD §US-15.3)

ADR-0067 G4 / epic-15-renewal-recalc.scenario.ts / climb 2026-06-17

G4: US-15.4 shipping recalculation at renewal — AC1 quote rate applied; AC2 discontinued method → sub paused + open shipping_quote_failed exception; idempotency (one open); conservative: flaky probe does NOT pause (BRD §US-15.4)

ADR-0067 G4 / epic-15-renewal-recalc.scenario.ts / climb 2026-06-17

G4: US-23.2 SMS notifications (Twilio) — consent gate blocks without opt-in; opted-in sends via Twilio Messages endpoint Basic-auth; portal PUT /sms-preferences opts in + TCPA audit row; Twilio 400 → failed + error_code (BRD §US-23.2)

ADR-0067 G4 / epic-23-sms.scenario.ts / climb 2026-06-17

G4: US-23.4 Slack merchant alerts — no-destination no-op; below threshold no alert; cross-threshold one alert enqueued; idempotent within window; delivery POSTs JSON; 5xx → retry; no_service → exhausted (BRD §US-23.4)

ADR-0067 G4 / epic-23-slack.scenario.ts / climb 2026-06-17

G4: US-23.5 Klaviyo integration — envelope/mapping JSON:API shape; enqueue maps event→metric; delivery POSTs with Klaviyo-API-Key auth + revision header; 5xx → retry; unmapped/no-connection → no-op (BRD §US-23.5)

ADR-0067 G4 / epic-23-klaviyo.scenario.ts / climb 2026-06-17

G4: US-5.2 subscribe-and-save — discount_pct applied at renewal off the configured discount_base (effective|list; store→product→plan hierarchy, most-specific-wins); catalog/sale-aware; null variant-price falls back to list (BRD §US-5.2)

ADR-0067 G4 / epic-5-plan-design.scenario.ts / scenario-results-lag close 2026-06-22

G4: US-19.5 subscriber preferences persist (customer-scoped portal PUT/GET, invalid rejected) + curation removes preference-excluded variants; no-schema + filter-empties fallbacks never block a pick (BRD §US-19.5)

ADR-0067 G4 / epic-19-subscriber-preferences.scenario.ts / scenario-results-lag close 2026-06-22

G4: US-23.6 product-issue cancel auto-files a helpdesk ticket (Gorgias/Zendesk) with idempotency + retry semantics (BRD §US-23.6)

ADR-0067 G4 / epic-23-helpdesk.scenario.ts / scenario-results-lag close 2026-06-22

G4: US-23.7 accounting export behaves — subscription revenue events map to the accounting-integration payload (BRD §US-23.7)

ADR-0067 G4 / epic-23-accounting.scenario.ts / scenario-results-lag close 2026-06-22

G4: US-23.9 sending-domain verification behaves — domain auth (SPF/DKIM) status gates sends (BRD §US-23.9)

ADR-0067 G4 / epic-23-sending-domain.scenario.ts / scenario-results-lag close 2026-06-22

G4: US-24.7 B2B contract-term cancel guard — inside notice window → 409 contract_notice_period + term_end_at; mode=route → 409 cancel_routed_to_legal + pending delivery enqueued; outside window/disabled/no-term → cancel proceeds (BRD §US-24.7)

ADR-0067 G4 / epic-24-contract-cancel-guard.scenario.ts / climb 2026-06-17

G4: US-26.9 dependency rules (product ladders) — Y requires prior purchase of X; blocked without; allowed with active or cancelled X; fast-path (no rule) passes; tenant isolation; audit trace includes dependency_fail step (BRD §US-26.9)

ADR-0067 G4 / epic-26-eligibility.scenario.ts / climb 2026-06-17

G4: US-28.4 PCI SAQ-A scope — materialized schema (sqlite_master DDL) has NO PAN/CVV/track column on any table; payment_methods persists only opaque token ref + PCI-permitted truncated metadata (card_last4/brand/exp); residual G5/attestation: SAQ-A self-assessment (BRD §US-28.4)

ADR-0067 G4 / epic-28-compliance.scenario.ts / climb 2026-06-17

G4: US-15.5 free shipping on subscription — plan.free_shipping_eligible=1 zeros shipping_cost_ex_tax+inc_tax on BC /v2/orders POST body at renewal; zero-regression: flag absent → fields unset (BRD §US-15.5)

ADR-0067 G4 / epic-15-renewal-recalc.scenario.ts / climb 2026-06-17

G4: US-27.4 Headless SDK TypeScript — createClient({token}) returns typed subscriptions/plans/products/cart methods; Auth header set; onDeprecation callback fires on Deprecation response header; SDKError thrown on 4xx with correct type/status (BRD §US-27.4)

ADR-0067 G4 / packages/subscriber-sdk client.test.ts + methods/subscriptions.test.ts / climb 2026-06-17

G4: US-23.1 lifecycle transactional email — pause/resume/cancel handlers emit events (ADR-0010 outbox); email-consumer maps each lifecycle type → template and sends via Resend with {{subscription_id}} interpolated; unmapped type skipped (BRD §US-23.1)

ADR-0067 G4 / epic-23-transactional-emails.scenario.ts / DoD wave 2026-06-22 (closes #1505 lifecycle-send deferral)

G4: US-13.5 platform health metrics — computePlatformMetrics rolls charge outcomes (per-status + success rate), latency p50/p95/max, undrained-outbox queue depth, and dunning recovery rate, aggregate + per-store; handleAdminMetrics returns the store-scoped slice without tenant leakage (BRD §US-13.5)

ADR-0067 G4 / epic-13-platform-metrics.scenario.ts / DoD wave 2026-06-22

G4: US-17.3 portal custom domain — register → pending_dns with CNAME target; verify resolves the live CNAME (injected resolver) → verified on match, stays pending with diagnostic on mismatch; invalid hostname rejected; cross-store conflict; tenant isolation. TLS provisioning + serving remain G5-live (BRD §US-17.3)

ADR-0067 G4 / epic-17-custom-domain.scenario.ts / DoD wave 2026-06-22

G4: US-8.5 A/B widget copy — deterministic FNV-1a 50/50 split across 600 sessions (distribution asserted), sticky per session + payload delivery, per-variant conversion rate and two-proportion-z confidence (BRD §US-8.5)

ADR-0067 G4 / epic-8-widget-ab.scenario.ts / DoD wave 2026-06-22

G4: US-20.6 intervention A/B — subscribers randomized across offer-framing variants, EXACT per-variant save-rate attribution, confidence-vs-control for review (BRD §US-20.6)

ADR-0067 G4 / epic-20-intervention-ab.scenario.ts / DoD wave 2026-06-22

G4: US-3.1 Recharge CSV import — RechargeAdapter.write() persists external_ref + imported_from=recharge + next_charge_at; idempotent re-write returns skipped=true with exactly 1 DB row; batch import per-row isolation + dry-run confirmed (BRD §US-3.1)

ADR-0067 G4 / epic-3-migration.scenario.ts / migration wave 2026-06-23

G4: US-3.2 cross-gateway PM flag — Recharge write() emits import.edge_case_flagged audit event with our_decision=pm_revault_required for every Recharge subscription (BRD §US-3.2)

ADR-0067 G4 / epic-3-migration.scenario.ts / migration wave 2026-06-23

G4: US-3.3 cycle-date preservation — imported next_charge_at persisted exactly, status=active post-import, no charge scheduled earlier than imported date (BRD §US-3.3)

ADR-0067 G4 / epic-3-migration.scenario.ts / migration wave 2026-06-23

G4: US-3.4 PayWhirl CSV import (plan-centric) — fieldMap defaults match the documented PayWhirl plan-based model (plan_id; billing_interval=count, billing_frequency=unit); extract() yields rows from ctx.metadata.csv_records; expired status → cancelled + expired_collapsed edge flag; missing plan mapping → edge_case_flagged audit event; every write emits pm_revault_required; active subscription creates DB row with external_ref + imported_from=paywhirl (BRD §US-3.4)

ADR-0067 G4 / epic-3-migration.scenario.ts / regrounded vs api.paywhirl.com 2026-06-25

G4: US-3.5 Bold v1 import — six-state machine: active→active, pending_review→cancelled+audit, paused_indefinitely(no resume_date)→cancelled+audit; bc_customer_id-based customer resolution (BRD §US-3.5)

ADR-0067 G4 / epic-3-migration.scenario.ts / migration wave 2026-06-23

G4: US-3.6 dry-run migration — dry_run=true returns per-row status=succeeded reason=dry_run with no DB writes; live import creates subscription row (BRD §US-3.6)

ADR-0067 G4 / epic-3-migration.scenario.ts / migration wave 2026-06-23

G4: US-3.7 PayWhirl API import — dual-mode adapter: authenticate({apiKey}) selects API mode; extract() paginates GET /customers (cursor after_id) → per-customer GET /subscriptions/{id} (plan embedded) → authoritative PayWhirlSubscription → fieldMap; 429 backoff honors x-ratelimit-reset; pm_revault_required still emitted. G4-mocked against the verified api.paywhirl.com contract (G5/live needs a real key) (BRD §US-3.7, Spec #1699)

ADR-0067 G4 / epic-3-migration.scenario.ts / api.paywhirl.com verified 2026-06-25

G4: US-27.5 GraphQL read surface — POST /graphql parses nested selection sets, projects ONLY requested fields, resolves subscription→charges→order over D1, every resolver tenant-scoped (cross-tenant read → null), unknown field/scalar-subfields/mutation → errors[] (BRD §US-27.5)

ADR-0074 / epic-27-graphql.scenario.ts / Epic-16/27 wave 2026-06-22

G4: US-27.6 extension marketplace — install enforces a sandboxed permission model (out-of-allowlist scope rejected; webhook gated by granted scope; admin panel gated), grants register real webhook_subscriptions rows, uninstall deactivates them; tenant-isolated. Third-party code execution + partner approval are G5 (BRD §US-27.6)

epic-27-extensions.scenario.ts / Epic-16/27 wave 2026-06-22

G4: US-27.7 sandbox provisioning — yields an isolated test-mode store (test_mode_enabled=1) + scoped API key + N test subscriptions (test_mode=1), without polluting the owner production tenant; owner lists its sandboxes. A real BigCommerce store is BC product surface (G5); sandbox = isolated platform test tenant (BRD §US-27.7)

epic-27-sandbox.scenario.ts / Epic-16/27 wave 2026-06-22

G4: US-16.5 decoupled billing/shipping cadence — fulfillment sweep (2nd independent cron) turns N due delivery_instances into fulfillment-only BC orders (payment_method:'manual', NO payment_status per ADR-0075 BC probe) backed by ONE billing charge, creating NO new charge; charge_id+bc_order_id linkage recorded; delivery with no covering charge → failed not free order. Live BC POST is G5 (BRD §US-16.5)

ADR-0075 / epic-16-decoupled-cadence.scenario.ts / Epic-16/27 wave 2026-06-22

ADR-0007: GDPR-driven uninstall retention sweep (30-day tombstone before hard delete)

ADR-0007 / PR #557 (sweep) + PR #558 (runbook)

ADR-0009: tenant data isolation via store_hash scope guards on every owned-entity read

ADR-0009 / db.ts scope-guarded helpers

ADR-0011: failed_permanently terminal state — scheduler ratchets stuck charges

ADR-0011 / PR #163 (scheduler poison-row ratchet)

ADR-0014: typed-error wire format (couples with BigEng convention #4)

ADR-0014 / Slice B PR #542

ADR-0024: per-delivery-instance override mutation API (skip / swap_product / reschedule_to)

ADR-0024 / PRs #556 #559 #560

ADR-0028: eligibility-engine architecture pattern (Epic 26 inclusion + exclusion rules)

ADR-0028 / PRs #482 #483 #484 #485 #486 #487 + #475 #476 #478 #479 #480

ADR-0029: marketplace-first, native-ready posture

ADR-0029 / PRs #539 #540

ADR-0030: BigEng pattern alignment — ratify the 12-convention catalog

ADR-0030 / PR #555

ADR-0031: operations.max_attempts column for per-row retry budget

ADR-0031

ADR-0031: operations.locked_until column + reaper cron

ADR-0031

ADR-0031: job_configuration sidecar table for per-cron per-store config

ADR-0031

DeprecationRegistry + middleware wired at app boot (ADR-0032)

ADR-0032

All API routes mounted under /api/v1/ prefix (ADR-0032)

ADR-0032

Deprecation, Sunset, Link headers emit on deprecated route calls (ADR-0032)

ADR-0032

ADR-0033: polymorphic subscription_extensions substrate for Epic 6 extension types

ADR-0033

ADR-0033: scheduler invokes extension lifecycle hooks before each renewal

ADR-0033

ADR-0035: BC Payments standard-rail adapter — production branch implemented (PAT mint + method lookup + payments.bigcommerce.com charge; throw at bc-payments.ts:70 replaced)

ADR-0035 / task cbb818e4 / synthesis 7f0691f9

ADR-0035: BC Payments stored-instrument extraction at order.created webhook — real BigPay token persisted via GET /v3/customers/{id}/stored-instruments

ADR-0035 / task cbb818e4 / synthesis 7f0691f9

ADR-0025: Stripe secondary-rail adapter — production branch implemented (PaymentIntent.create with off_session MIT; no pre-existing BC order required)

ADR-0025 / task daf2aa64 / synthesis 7f0691f9

Stripe adapter classifies hard vs soft declines via HARD_DECLINE_CODES set; StripeChargeError exposes isHardDecline for scheduler dunning logic

task daf2aa64 / synthesis 7f0691f9

ADR-0037: stored-instruments vault ratified as the canonical charge rail — ADR file exists and bc-vault-client.ts service ships

ADR-0037 / P-comp 2026-05-15

Adapter discovery registry (adapter-registry.ts) exists and scheduler routes charges through getAdapter() rather than hardcoded createBcPaymentsAdapter()

synthesis 9457c80c / task 12ef8d88

Stripe adapter end-to-end sandbox scenario exists — validates charge + off-session renewal + idempotency against Stripe test-mode API (Payments P-1)

ADR-0025 / proposal 632c6a55 / GH #771

ADR-0038 P2-A: Stripe adapter implements authorize() via PaymentIntent.create with capture_method=manual, returns AuthorizeResult with processorTransactionId. authWindowDays=7 per Stripe documented card auth window.

ADR-0038 / Hive #796 track A

ADR-0038 P2-A: Stripe adapter implements capture() via PaymentIntent capture endpoint with amount_to_capture and Idempotency-Key (ADR-0011). voidAuth() implemented via PaymentIntent cancel.

ADR-0038 / Hive #796 track A / ADR-0011

ADR-0038 P2-A: BC Payments authorize() stub — documents that payments.bigcommerce.com is atomic and does not support per-request auth-only mode. Throws not_implemented_phase_2_requires_bc_partner_track. Verified 2026-05-15 against BC payments overview + transactions-api docs.

ADR-0038 / Hive #796 track A

ADR-0038 P2-A: BC Payments capture() and voidAuth() stubs — documents that BC Transactions API capture/void endpoints are "planned for future phases" as of 2026-05-15. authWindowDays=5 (TBC, conservative default).

ADR-0038 / Hive #796 track A

ADR-0038 Phase 1: stores.capture_timing column exists — migration 0026 (schema/D1) + capture_timing field on StoreRow in db.ts + CaptureTiming type in @bc-subscriptions/types. Advisory only in Phase 1; Phase 2 wires enforcement.

ADR-0038 / proposal #789 / synthesis #840 / Hive task 9f812cc8 / 2026-05-15

ADR-0038 Phase 2-D: capture-timing-resolver service ships — resolveCaptureTiming() exported, EU_COUNTRY_CODES constant present, migration 0028 adds stores.country_code column

ADR-0038 / Hive #822 / synthesis #840 (b87f5678)

P1 Maya: annual subscription signup → active → calendar-anchored next_charge_at (BRD §US-1.1 / US-9.2 / US-10.3)

PR #690 / BRD §US-1.1 US-9.2 US-10.3 / Hive task fe8d3bd5

P1 Maya: OOS block at renewal → Exception Queue entry surfaced (BRD §US-15.1)

PR #690 / BRD §US-15.1 / Hive task fe8d3bd5

P1 Maya: mid-year signup → next_charge_at snaps to Jan 1, not signup+1yr (BRD §US-10.3)

PR #690 / BRD §US-10.3 / Hive task fe8d3bd5

P2 Alex: AllotmentGrant create → 4 debits → balance=0 → month-boundary refresh → balance=4 (BRD §US-6.9)

PR #691 / BRD §US-6.9 / Hive task 8834674a

P2 Alex: subscriber cancel → status=cancelled + subscription.cancelled event (BRD §US-18.5 / US-6.5)

PR #691 / BRD §US-18.5 US-6.5 / Hive task 8834674a

P2 Alex: mid-cycle Standard→Premium upgrade → proration charge + plan_id updated + plan_upgraded event (BRD §US-14.6)

PR #691 / BRD §US-14.6 / Hive task 8834674a

P3 Jordan: Gift purchase → status=paused + gift extension + subscription.gift_purchased event (BRD §US-6.1)

PR #692 / BRD §US-6.1 / Hive task e9d7f5dc

P3 Jordan: Gift claim → recipient subscription status=active, gift marked claimed (BRD §US-6.1)

PR #692 / BRD §US-6.1 / Hive task e9d7f5dc

P3 Jordan: Expired gift claim window → 412 precondition_failed (BRD §US-6.1)

PR #692 / BRD §US-6.1 / Hive task e9d7f5dc

P4 Sam: CS-rep B2B enrollment with PO reference → status=active + subscription.b2b_enrolled event (BRD §US-22.9 / ADR-0023)

PR #693 / BRD §US-22.9 / ADR-0023 / Hive task 63e46415

P4 Sam: commitment_cycles=12 persisted on plan — data-model foundation for U-17 cancel lock (BRD §US-5.7)

PR #693 / BRD §US-5.7 / Hive task 63e46415

P4 Sam: Buyer-org AllotmentGrant 50 wellness_credits/quarter → balance drained → quarterly refresh → balance=50 (BRD §US-6.9)

PR #693 / BRD §US-6.9 / Hive task 63e46415

P5 Taylor: Subscribe-and-save 3-cycle commitment + successful renewal charge (BRD §US-5.7 / US-11.1)

PR #694 / BRD §US-5.7 US-11.1 / Hive task b980c6b7

P5 Taylor: Dunning retry scheduled on failure → charge succeeds on retry → subscription stays active (BRD §US-11.2)

PR #694 / BRD §US-11.2 / Hive task b980c6b7

P5 Taylor: Dunning all 3 stages exhaust → subscription.status=cancelled + charge.failed_permanently (BRD §US-11.2)

PR #694 / BRD §US-11.2 / Hive task b980c6b7

U-17 P4 Sam: cancel lock 409 enforcement + CS-rep override with audit trail (BRD §US-5.7 + synthesis fa3dc5f3)

synthesis fa3dc5f3 / BRD §US-5.7

U-17 P5 Taylor: cancel lock 409 for 3-cycle commitment (BRD §US-5.7 + synthesis fa3dc5f3)

synthesis fa3dc5f3 / BRD §US-5.7

U-19 P3 Jordan: future start date → pending_start → scheduler activation (BRD §US-N.M + synthesis fa3dc5f3)

synthesis fa3dc5f3 / BRD §US-N.M

U-20 P4 Sam: calendar billing anchor billing_anchor_month/day → April 1 fiscal-year anchor (BRD §US-N.M + synthesis fa3dc5f3)

synthesis fa3dc5f3 / BRD §US-N.M

snake_case wire fields — JSON request/response keys are snake_case on the wire

ADR-0030 / BigEng audit §Convention 1

store_hash present as payload field, not header-only

ADR-0030 / BigEng audit §Convention 2

Offset + cursor pagination, mutually exclusive — bigeng convention #3

ADR-0030 / BigEng audit §Convention 3

Typed domain ADTs for errors (vs ad-hoc { error: string } shapes)

ADR-0030 / Slice B PR #542

Auth principal envelope {id, type} on requests

ADR-0030 / BigEng audit §Convention 5

UUID for owned entities; integer for legacy BC FKs

ADR-0030 / BigEng audit §Convention 6

Soft-delete via is_deleted INTEGER (vs hard-delete + cascade)

ADR-0030 / Slice C PR #543

TIMESTAMP DEFAULT CURRENT_TIMESTAMP on created_at / updated_at columns

ADR-0030 / BigEng audit §Convention 8

Operations-table saga ledger (replaces inline cron-driven orchestration)

ADR-0030 / Slice C PR #543

Scope / resource entitlements (per-subscriber, not just store-wide)

ADR-0030 / BigEng audit §Convention 10

Audit emission via decorator wrapping (vs inline INSERT INTO events)

ADR-0030 / Slice D PR #545

Audit payload shape — target/resource/summary/operation_type + request-scoped MDC

ADR-0030 / Slice D PR #545

P99 charge execution latency < 3s from scheduler pickup to processor call initiated

BRD.md §7.1: P99 charge execution latency < 3s from scheduler pickup → processor call initiated

P99 webhook ingestion < 250ms to 2xx response (processing is async)

BRD.md §7.1: P99 webhook ingestion < 250ms to 2xx response (processing is async)

99.95% platform uptime SLA; at-least-once delivery on external webhook deliveries; at-most-once charge execution enforced via idempotency key = charge.id

BRD.md §7.2: 99.95% platform uptime; at-least-once webhook delivery; at-most-once charge execution (idempotency key = charge.id)

No PAN, CVV, or full card data ever stored or transmitted through our servers; processor adapters hold tokens only; TLS 1.3 in transit; AES-256-GCM for secrets at rest

BRD.md §7.3: PCI scope: zero — we never hold PAN, CVV, or full card data; processor adapters hold tokens only; TLS 1.3; AES-256-GCM for secrets

Single-tenant resource isolation via Postgres row-level security (RLS) partitioned by store_hash

BRD.md §7.4: Single-tenant resource isolation via Postgres RLS by store_hash

Every state transition emits an Event row (append-only, per-store partitioned); every external call logged with latency, status, correlation ID

BRD.md §7.5: Every state transition emits an Event row; every external call logged with latency, status, correlation ID

WCAG 2.2 AA for merchant admin and subscriber portal; keyboard-navigable; screen-reader tested

BRD.md §7.6: WCAG 2.2 AA for both merchant admin and subscriber portal; keyboard-navigable; screen-reader tested

GDPR data subject access + erasure within 30 days; CCPA with "do not sell"; PCI DSS SAQ-A maintained; EU data residency by Phase 2

BRD.md §7.8: GDPR erasure 30-day fulfillment; CCPA "do not sell"; PCI DSS SAQ-A; EU data residency Phase 2

BC Payments adapter: HACKATHON_FIXTURE fixture guard fully removed from charge() — standard-rail (PAT/charge calls) is the only path per Payments P-2

ADR-0035 / task cbb818e4 / synthesis 7f0691f9 / proposal b1374e5a

Stripe adapter: HACKATHON_FIXTURE fixture guard fully removed from charge() — PaymentIntent.create is the only path per ADR-0025 / Payments P-2

ADR-0025 / task daf2aa64 / synthesis 7f0691f9 / proposal b1374e5a

ensureFixturePaymentMethod removed from all production route handlers — subscriptions.ts + webhooks.ts use real instrument resolution; db.ts export retained for tests

task 743c215e / synthesis 7f0691f9 / proposal b1374e5a

HACKATHON_FIXTURE is absent from all production route handlers and adapter charge() bodies — fixture mode is test-only (db.ts export and types.ts optional field remain)

proposal b1374e5a (Payments P-2) / decision 4e872518 (D-17 sweep)

Tier α T1S: processor_connections.config stripe_secret_key is encrypted at write (encryptForStore in processor-connections.ts create handler) and decrypted at read (adapter-registry.ts getAdapter Stripe case).

Tier α decision e21ea786 / Hive proposal e7e81fb0

Tier α T1S: per-store AES-256 keys derived via HKDF from deploy-time master (CREDENTIAL_ENCRYPTION_KEY) using store_hash as HKDF info. deriveStoreKey + encryptForStore + decryptForStore in crypto.ts.

Tier α decision e21ea786 / Hive proposal e7e81fb0

Migration 0036 adds external_ref + imported_from on subscriptions; external_ref on charges and customers

BRD.md §Epic-3: imported_from provenance, external_ref dedup key

Demo "connect your store" connect form — store_hash + Storefront API token, validated client-side, session stored in sessionStorage only (spec #1254 AC-2)

Hive #1143 AC-5a, gating spec #1254. Dossier: docs/handoffs/hive-1143-ac5a-demo-connect-form.md