How this was built

Built primarily with Claude Code (Anthropic's agentic coding tool), under direct human direction — the architecture, specification, and review decisions are the operator's; the AI generates code against that spec. The output is conventional TypeScript, Astro, and React — standard, maintainable code, not a proprietary format tied to the tool that helped write it. Quality claims here aren't self-assessed: every one is backed by an automated, regenerating verification ledger, not a status doc — see Verified Throughput. For a structured engineering review, see Code Review.

Bringing a new team up to speed

This is a subscription billing engine built for BigCommerce merchants — recurring charges, dunning (retrying failed payments), and a customer self-service portal, integrated into BigCommerce's own admin and storefront rather than running alongside it as a separate system. If you're picking this up cold, this page is the fastest path from zero to productive.

Before any estimate: what's the actual ask?

This page assumes none of the following are decided yet — confirm which applies before scoping any timeline or team size: (a) full path-to-GA delivery, (b) closing a specific named gap (see Known Limitations below), (c) the B2B Edition extension (approval workflows, purchase orders), or (d) extending the live BC Payments rail (e.g. PPCP confirmation, deferred capture) beyond what ADR-0082 already validated. Each is a different-sized engagement.

What's left to GA — the honest register

Sizing an engagement starts from three derived registers, not prose claims. Each is generated from the repo and re-derives on every deploy:

16 acceptance criteriaacross 10 epics lack a passing automated scenario — the build-completion remainder, grouped by area inCode review.
30 GA-blocking attestations pending — external/human sign-offs (pen-test, legal, accessibility validation) that gate GA regardless of code state. Full pack with per-item status:Security & Complianceand Operations.
The open engineering-decision register — traced, evidence-cited defects and adjudications surfaced by this project's own audit passes (each links the trace that found it):open issues. These are honest sizing input, not concealed debt — several were found by the same knowledge-transfer tracing that produced the per-capability deep dives below.

For the platform-dependency dimension (e.g. PayPal-specific confirmation), see each capability page's "Where intent and reality diverge" section — every divergence is typed and cited.

Requirements by role & tier

Every requirement below is derived from the BRD's own story headers (phase, priority, effort, persona) joined with the automated verification ladder — regenerated on every release, never hand-maintained. Personas bucket into the product's three external roles — Merchant, Subscriber, Support — plus two internal buckets (Developer-facing integration stories; System stories with no human actor, e.g. schedulers and webhooks).

How to read "verified": a story counts as verified only when a tagged automated scenario passes in CI (gate G4 of the five-gate ladder). "Not yet verified" is a test-evidence statement, not a claim the story is unbuilt — several are built and awaiting scenario coverage. Sizing should treat the verified column as the floor of what demonstrably works.

Role	MVP	P1	P2	P3	Verified / total
Merchant	33 / 36	14 / 15	30 / 31	18 / 19	95 / 101
Subscriber	30 / 31	7 / 11	8 / 8	7 / 8	52 / 58
Support / Ops	6 / 7	5 / 5	6 / 6	1 / 1	18 / 19
Developer	6 / 8	0 / 0	4 / 5	1 / 1	11 / 14
System	22 / 22	2 / 2	2 / 2	0 / 0	26 / 26

Cells are verified / total stories. Phase is the BRD's delivery-phase field: MVP and P1 are the shipped-first scope; P2/P3 are the deliberately-later tranches.

Where P0 feedback lands

74 of 218 stories carry an explicit business-priority tier today (53 P0 · 17 P1 · 4 P2); the remaining 144 are untiered — they predate the priority field. Tiering that remainder is the open product-judgment pass this register exists to support: mark P0/P1 against the per-role lists below and the BRD headers get updated from that feedback (this page then re-derives).

Merchant — 101 stories

US	Phase	Priority	Effort	Verified	Story
US-1.1	MVP	P0	M	yes	OAuth install handshake
US-1.2	MVP	P0	S	yes	Signed payload JWT verification on app load
US-1.3	MVP	—	—	yes	App Extensions registered on install
US-1.5	MVP	P0	M	yes	Uninstall hook cleans up credentials and extensions
US-2.1	MVP	P0	M	yes	Auto-detect BC Payments
US-2.2	MVP	P0	L	yes	Stripe Connect onboarding
US-2.3	MVP	P0	M	yes	Processor compatibility detection at install
US-2.4	MVP	—	—	yes	Sandbox/test mode
US-2.6	P2	—	—	yes	Multiple processor connections
US-2.7	P1	P1	XS	yes	Capture timing advisory at processor onboarding
US-3.1	P2	—	—	yes	Recharge export import
US-3.2	P2	P0	XL	yes	Payment method migration via Stripe/Braintree dataset import
US-3.3	P2	—	—	yes	Cycle-date preservation
US-3.4	P2	—	—	yes	PayWhirl export import
US-3.5	P3	—	—	yes	Bold / MINIBC import
US-3.6	P2	P1	M	yes	Dry-run migration with impact report
US-3.7	P2	P2	M	yes	PayWhirl API import (authoritative extraction)
US-4.1	MVP	P0	M	yes	"Subscriptions" panel on a BC product
US-4.2	MVP	P0	L	yes	Subscription-enable wizard
US-4.3	MVP	—	—	yes	Variant-level subscription enablement
US-4.4	MVP	—	—	yes	Deactivate subscription plan
US-4.5	P2	—	—	yes	Copy plan between products
US-5.1	MVP	—	—	yes	Multiple offered intervals
US-5.2	MVP	—	—	yes	Pricing strategy — fixed discount %
US-5.3	MVP	P0	M	yes	Pricing strategy — BC Price List
US-5.4	MVP	—	—	yes	Pricing strategy — fixed price
US-5.5	MVP	P1	M	yes	Free or paid trial
US-5.6	P2	—	—	yes	Lock price at subscription creation
US-5.7	P2	—	—	yes	Commitment (minimum cycles)
US-5.8	P2	—	—	yes	Cancel lock plan policy — minimum term + early-cancellation policy
US-5.9	P2	—	—	yes	Calendar-anchored billing plan anchor
US-6.1	P3	P1	XL	yes	Gift subscriptions
US-6.4	P1	—	—	yes	Bundle subscriptions
US-6.5	P1	—	—	yes	Membership subscriptions (access-based)
US-6.6	P1	—	—	yes	Usage-based subscriptions
US-6.9	P3	—	—	yes	AllotmentGrant — admin-granted recurring quota / wallet (PRD-COMPANION D18)
US-6.10	P1	—	—	yes	Multi-actor subscription — payer / beneficiary / manager distinct from owner (PRD-COMPANION D19)
US-6.11	P3	—	—	yes	Custom-field configuration on a plan (PRD-COMPANION D20)
US-7.1	P2	P0	M	yes	Plan scoped to specific channels
US-7.2	P2	—	—	yes	Plan scoped to customer groups
US-7.3	P2	—	—	yes	Plan scoped to geographic region
US-7.4	P2	—	—	yes	Plan scoped to Price List
US-7.5	P2	—	—	yes	Scope audit view
US-8.4	MVP	—	—	not yet	Widget theming
US-8.5	P3	—	—	yes	A/B widget copy
US-10.9	P1	P1	S	yes	Capture timing configuration per store
US-11.1	MVP	—	—	yes	Configurable dunning policy
US-11.7	P2	—	—	yes	Merchant-side dunning digest
US-14.2	MVP	—	—	yes	Tag order with subscription metadata
US-14.4	MVP	—	—	yes	Order status mapping
US-14.5	P2	—	—	yes	Order edit sync
US-15.5	P2	—	—	yes	Free shipping on subscription
US-15.6	P2	—	—	yes	Pre-renewal OOS check — proactive inventory scan before charge with Exception Queue escalation
US-16.3	P1	—	—	yes	Merchant view of combined shipments
US-16.5	P3	—	—	yes	Decoupled billing and shipping cadence — Phase 3 scaffold
US-17.3	P3	—	—	yes	Portal custom domain
US-17.4	MVP	—	—	not yet	Portal theming
US-20.6	P3	—	—	yes	Intervention A/B testing
US-21.1	MVP	—	—	yes	KPI summary
US-21.2	MVP	—	—	yes	Upcoming charges panel
US-21.4	MVP	—	—	yes	Subscription list with search & filter
US-21.5	P2	—	—	yes	Bulk actions on subscriptions
US-21.6	MVP	P0	L	yes	Subscription detail view
US-21.7	P2	—	—	yes	Export subscription data (CSV)
US-21.8	P1	—	—	yes	Analytics beyond KPIs (cohort, LTV)
US-23.3	MVP	—	—	yes	Template editor
US-23.4	P2	—	—	yes	Merchant alerts & digests
US-23.5	P2	P1	L	yes	Klaviyo integration
US-23.7	P3	—	—	yes	Accounting integrations (NetSuite, QuickBooks, Xero)
US-23.9	MVP	P0	L	yes	Custom sending domain
US-23.10	MVP	P0	M	yes	Deliverability monitoring
US-23.17	P2	—	—	yes	Localization framework
US-24.1	P3	—	—	yes	Company-account subscriptions
US-24.5	P3	—	—	yes	Buyer hierarchy & visibility
US-24.6	P3	—	—	yes	Volume-tier renewal pricing
US-24.7	P3	—	—	yes	Contract-term commitments
US-24.9	P3	—	—	yes	Admin-only B2B subscription enrollment in Phase 1 (ADR-0023)
US-24.10	P3	—	—	yes	`org_admin` actor role and multi-actor management on B2B subscriptions (PRD-COMPANION D19, ADR-0022)
US-25.1	MVP	P0	L	yes	Subscription-only coupon codes
US-25.2	MVP	—	—	not yet	Subscribe-and-save auto-promotion
US-25.3	MVP	—	—	yes	Cycle-scoped discount
US-25.5	P1	—	—	yes	Promotion stacking rules
US-25.6	P2	—	—	yes	Promotional free shipping
US-25.7	P3	—	—	yes	Subscription-exclusive bundles
US-25.9	P2	—	—	yes	Promotion reporting
US-25.10	P2	P2	M	yes	Time-tiered discount ladder
US-25.11	P3	P2	L	not yet	Cycle-discount ladder — admin propagation controls
US-26.1	MVP	P0	M	yes	Product inclusion by category
US-26.2	MVP	—	—	yes	Product exclusion
US-26.3	MVP	—	—	yes	Variant-level eligibility
US-26.4	P1	—	—	yes	Custom-field-based eligibility
US-26.5	P1	P1	M	yes	Customer-segment eligibility
US-26.6	P1	—	—	yes	Geographic & channel restrictions
US-26.7	P1	—	—	yes	Quantity min/max
US-26.8	P3	P2	M	yes	Mutual exclusion rules
US-26.9	P3	—	—	yes	Conditional dependency rules
US-26.10	P1	—	—	yes	Rule evaluation audit
US-27.2	MVP	—	—	yes	API key management in admin
US-28.3	P2	—	—	yes	Audit log export
US-28.6	P2	—	—	not yet	Data residency
US-28.7	P1	P0	M	not yet	Auto-renewal disclosure policy & consent-record retention

Subscriber — 58 stories

US	Phase	Priority	Effort	Verified	Story
US-6.2	P1	P0	L	yes	Prepaid fixed-term subscriptions
US-6.3	P3	P1	XL	yes	Build-a-box subscriptions
US-6.7	P1	—	—	yes	Surprise-me / curation subscriptions
US-6.8	P1	—	—	yes	Referral subscriptions
US-8.1	MVP	P0	L	yes	Widget on Stencil PDP
US-8.2	MVP	—	—	not yet	Widget on cart
US-8.6	P1	—	—	not yet	Pre-purchase education panel
US-9.3	MVP	P0	M	yes	Post-purchase fallback capture
US-9.4	MVP	—	—	yes	Mixed-cart checkout (subscription + one-time)
US-9.6	P1	P0	M	yes	Affirmative consent capture at subscribe (auto-renewal disclosure)
US-10.5	MVP	—	—	yes	Pause/resume respects schedule math
US-10.6	P1	—	—	yes	Schedule visualization
US-10.7	P2	—	—	yes	Future start date — pending_start state and deferred activation
US-10.8	P2	—	—	yes	First-cycle proration for mid-year calendar-anchor sign-ups
US-11.5	MVP	—	—	yes	Subscriber-initiated PM update resets retries
US-11.6	MVP	—	—	yes	Dunning notifications
US-14.6	P2	—	—	yes	Mid-cycle plan upgrade — delta-capture semantics
US-16.1	P1	—	—	yes	Subscriber opts into combined shipments
US-17.1	MVP	P0	M	yes	Magic-link email auth
US-17.2	P2	—	—	yes	BC storefront SSO
US-18.1	MVP	P0	S	yes	Skip next charge
US-18.2	MVP	P0	L	yes	Swap product/variant
US-18.3	MVP	—	—	yes	Pause subscription
US-18.4	MVP	—	—	yes	Reschedule next charge
US-18.5	MVP	P0	L	yes	Cancel (with churn-prevention flow)
US-18.6	MVP	—	—	yes	Update quantity
US-18.7	P2	—	—	yes	Reactivate cancelled subscription
US-18.8	MVP	—	—	yes	Change cadence / interval
US-18.9	P1	—	—	yes	Term-end renewal nudge — registration-style re-up distinct from MIT renewal
US-18.10	P2	—	—	yes	Cancel lock — portal enforcement and CS-rep admin override
US-18.11	P1	P0	M	not yet	Click-to-cancel — same-medium cancellation parity
US-19.1	MVP	P0	L	yes	Update payment method
US-19.2	MVP	—	—	yes	Default vs per-subscription PM
US-19.3	MVP	—	—	yes	Update shipping address
US-19.4	MVP	—	—	yes	Update billing address
US-19.5	P3	—	—	yes	Subscriber preferences
US-19.6	MVP	P1	M	yes	Update payment method across all subscriptions
US-20.1	MVP	—	—	yes	Cancel reason capture
US-20.2	MVP	P0	M	yes	Intervention: pause-instead-of-cancel
US-20.3	MVP	P0	L	yes	Intervention: offer discount
US-20.4	MVP	—	—	yes	Intervention: change cadence
US-20.5	MVP	—	—	yes	Intervention: escalate to support
US-20.7	P1	P0	S	not yet	Churn-flow obstruction guard (save-attempt limit)
US-23.1	MVP	—	—	yes	Transactional emails
US-23.2	P2	—	—	yes	SMS notifications
US-23.11	MVP	P0	M	yes	Suppression list management
US-23.12	MVP	P0	L	yes	Magic-link email pipeline
US-23.13	MVP	P0	M	yes	Decline-reason-translated dunning email
US-23.18	P1	P0	M	not yet	Auto-renewal reminder notifications
US-24.2	P3	—	—	yes	Role-based portal permissions
US-24.3	P3	P1	XL	yes	Approval workflow for subscription changes
US-24.4	P3	—	—	yes	Purchase order as payment method
US-24.8	P3	—	—	yes	Multi-location shipping
US-24.11	P3	—	—	not yet	Catalyst storefront + Buyer Portal + subscription widget composite PDP behaviour
US-25.4	P2	P1	M	yes	Tenure-based loyalty discount
US-25.8	P3	—	—	yes	Gift-with-subscription
US-28.1	MVP	P0	M	yes	GDPR data subject access request (DSAR)
US-28.2	MVP	P0	L	yes	GDPR/CCPA erasure

Support / Ops — 19 stories

US	Phase	Priority	Effort	Verified	Story
US-2.5	MVP	—	—	yes	Processor health check
US-12.1	MVP	P0	M	yes	Refund a charge
US-12.2	P2	P1	L	yes	Store credit as payment for next charge
US-12.3	MVP	—	—	yes	Skip cycle without refund
US-12.4	P2	—	—	yes	Merchant-initiated one-time charge
US-12.5	P2	—	—	yes	Chargeback dispute handling
US-13.1	MVP	—	—	yes	Event log per subscription
US-13.3	MVP	P1	M	yes	Replay a failed workflow
US-21.3	MVP	P0	L	yes	Exception queue
US-22.1	P2	P1	L	yes	Create subscription manually
US-22.2	MVP	—	—	not yet	Customer lookup from BC App Extension
US-22.3	P1	—	—	yes	Impersonate subscriber (view-only)
US-22.4	P1	—	—	yes	Bulk subscription creation via CSV
US-22.5	P1	—	—	yes	Force-charge / force-refund
US-22.6	P2	—	—	yes	Merchant note on subscription
US-22.7	P1	—	—	yes	AllotmentGrant management (issue, refresh-override, suspend, revoke)
US-22.8	P1	—	—	yes	Custom-field admin UI — view, edit, validate
US-22.9	P3	—	—	yes	B2B Edition — admin-only subscription enrollment for buyer-orgs (ADR-0023)
US-23.6	P2	—	—	yes	Gorgias / Zendesk integration

Developer — 14 stories

US	Phase	Priority	Effort	Verified	Story
US-8.3	MVP	P0	L	not yet	Headless SDK
US-9.5	P2	—	—	yes	Third-party checkout support declaration
US-13.4	MVP	—	—	yes	Structured logs with correlation IDs
US-13.5	P2	—	—	yes	Metrics dashboard for platform SRE
US-17.5	MVP	P0	L	yes	Headless portal SDK
US-23.8	MVP	P0	L	yes	Outbound webhooks
US-27.1	MVP	P0	XL	yes	Public REST API
US-27.3	MVP	—	—	yes	Outbound webhook subscriptions
US-27.4	MVP	—	—	not yet	Headless SDK (TypeScript)
US-27.5	P2	—	—	yes	GraphQL API
US-27.6	P3	—	—	yes	App Marketplace for extensions
US-27.7	P2	—	—	yes	Sandbox test stores
US-28.4	MVP	P0	M	yes	PCI DSS scope maintenance
US-28.5	P2	—	—	not yet	SOC 2 Type II readiness

System — 26 stories

US	Phase	Priority	Effort	Verified	Story
US-1.4	MVP	—	—	yes	Webhook subscriptions registered on install
US-1.6	MVP	P1	S	yes	Persist BC staff on first load
US-1.7	MVP	P1	M	yes	Stamp mutating events with `actor_user_id`
US-9.1	MVP	P0	S	yes	Line-item custom fields carry intent
US-9.2	MVP	P0	L	yes	`store/order/created` → Subscription creation
US-10.1	MVP	—	—	yes	Nightly schedule scan
US-10.2	MVP	P0	XL	yes	Charge executor workflow
US-10.3	MVP	P0	M	yes	Charge anchor-date math
US-10.4	MVP	—	—	yes	Charge jitter for rate limiting
US-11.2	MVP	P0	L	yes	Retry execution
US-11.3	MVP	P0	M	yes	Hard vs soft decline classification
US-11.4	P2	—	—	yes	Automatic Card Updater integration
US-12.6	MVP	—	—	yes	Tax handling on refund
US-13.2	MVP	P0	L	yes	Daily reconciliation sweep
US-14.1	MVP	P0	L	yes	Create BC order on successful charge
US-14.3	MVP	—	—	yes	First-order linkage
US-14.7	P2	—	—	yes	NTI verification charge before stale-NTI renewal (PRD-COMPANION D21)
US-15.1	MVP	—	—	yes	Inventory check before charge
US-15.2	MVP	—	—	yes	Price recalculation at renewal
US-15.3	MVP	—	—	yes	Tax recalculation at renewal
US-15.4	MVP	—	—	yes	Shipping cost recalculation
US-16.2	P1	—	—	yes	Single BC order per combined shipment
US-16.4	P1	—	—	yes	Shipping cost allocation
US-23.14	MVP	P0	S	yes	Failed-render fallback
US-23.15	MVP	P0	M	yes	Idempotent send + dedupe
US-23.16	MVP	P1	M	yes	Webhook ingestion (bounce / complaint / open / click)

Derived by tools/brd-sizing-view from BRD.md as of commit 83be22a7. Full per-story acceptance criteria live in the BRD (repo access) or the product spec.

Where to start

Code review

Repo access, orientation map, runnable checks, known limitations

Architecture

Data model, state machine, BC platform integration seams

Live system

Touch the real thing day one — admin + storefront, no install

Per-capability deep dives

The handoff corpus — as-built detail per capability, generated from the same source this page draws on, with as_of_commitfrontmatter so you know how fresh each page is.

Canonical charge rail

Dunning

Gift subscriptions

Subscriber self-service

Trials & intro offers

Full section index: Handoff corpus

Stack map

Surface	Stack	Deployed on
apps/api	Cloudflare Workers + D1 — the charge/subscribe/dunning/cancel money path	Cloudflare Workers
apps/admin	React + BigDesign (BigCommerce's own design system)	Cloudflare Pages
apps/storefront-svelte, apps/storefront-catalyst	Two storefront integrations — Svelte (the live demo) and Catalyst (BC's headless React stack)	Cloudflare Pages
apps/portal	Astro — this site; internal/stakeholder communication, not part of the shipped product	Cloudflare Pages

Full rationale: Architecture

Things that will trip you up

Two storefront implementations exist (Svelte and Catalyst) — confirm which one your scope actually targets before estimating; they aren't interchangeable.
prototype/ is design reference, not production code — it informed the shipped design but isn't part of what runs. Don't sample it for a code-quality read.
The canonical payment rail (BC Payments stored-instruments) is integrated and live-proven — but read the rail split before estimating. New subscriptions charge through BC's gateway-agnostic payments API (live-validated end to end with Stripe as the underlying gateway, ADR-0082); pre-existing demo subscriptions ride a sanctioned direct-Stripe fallback for their remaining life. PayPal-specific (PPCP) same-session confirmation remains an external dependency to size separately.
Canonical spec docs (PRD, BRD, Architecture) cross-reference internal decision records by ID (e.g. "ADR-0037") — each is hyperlinked to its actual content, so click through rather than treating the ID as something you need to already recognize.

Known limitations

16 acceptance criteria across 10 epics don't have a passing automated scenario yet — named, not estimated. Full list, grouped by area: Code Review.

Run the whole thing — day one

No single composed command starts every app — they're loosely coupled and mostly run independently. Below is the documented bootstrap plus the two apps most relevant to a first day (API + admin, wired together). Full detail, including the prototype-only fast path and per-app port list, is indocs/runbooks/local-dev-env.md.

git clone git@github.com:nino-chavez/bc-subscriptions.git
cd bc-subscriptions
git config core.hooksPath .githooks   # one-time per clone
npm install

# Terminal 1 — API (Cloudflare Workers, emulates D1/KV/R2/queues locally)
cd apps/api
npx --yes wrangler@4 d1 migrations apply subs-api-d1 --local --persist-to .wrangler/state
npx --yes wrangler@4 dev              # → http://localhost:8787

# Terminal 2 — admin, pointed at the local API
cd apps/admin
API_URL=http://localhost:8787 npm run dev   # → http://localhost:3000

Fastest cold-start path if you only need the design reference (no cloud access required):cd prototype && npm install && npm run dev→ http://localhost:5174. Operator-only credentials (Cloudflare API token, BC sandbox creds, GH workflow_dispatch) are not needed for any of the above — only for deploys and BC-sandbox integration testing.

Integrate

API reference

REST endpoints, scopes, webhooks, error shapes — the OpenAPI contract

Component library

team access

Storybook — separately credential-gated, own Cloudflare Pages deployment

@bc-subscriptions/reactrepo · team access
Hooks + components for subscription PDPs, cart, and account portal.
@bc-subscriptions/storefront-catalystrepo · team access
BigCommerce Catalyst bindings — server actions, storefront-framework queries, route handlers pre-wired for subscriptions.
@bc-subscriptions/storefront-webcomponentrepo · team access
Framework-agnostic custom element for Stencil and other non-React storefronts.
@bc-subscriptions/design-tokensrepo · team access
OKLCH-based tokens, framework-agnostic CSS variables. Tailwind preset + raw CSS exports.

Decision log: Decisions

Day-one checklist

Get real repo read access (the operator arranges this directly — see Code Review for what "real access" means here).
Touch the live system before reading a line of code — the demo is faster ground truth than any document.
Run the test suite and typecheck yourself (commands at Code Review) — confirm the same pass/fail state this page implies.
Read Architecture for the data model and integration seams before writing any code.
Confirm scope against the four options above before sizing anything.