Headless Integration — Pre-work & Task List
Headless storefront integration status, blockers, and task checklist. Linked from the site footer only — not indexed.
Target kickoff: Monday, June 15, 2026
Session report (June 13): june13-summary.md
Cart/checkout wiring (June 15): Option A (hosted BC checkout) implemented — blocked on new API token (Carts scope still 403). Payments not yet tested on the Next.js → BC checkout path.
Promo flags (June 15): Decision + code shipped — ON SALE! and FREE SHIPPING! stay visible; rules in src/lib/promo-flags.ts (see Promo flags section).
Performance roadmap (remaining): performance-roadmap.md
What this document is
DeBrovy's is moving from a BigCommerce Stencil theme (the live site at debrovys.com) to a headless storefront built with Next.js in this repo. BigCommerce remains the system of record for products, inventory, carts, checkout, payments, and orders — but customers browse on Vercel-hosted React pages instead of BC-rendered HTML.
This document is the single integration playbook: what is done, what is blocked, how each subsystem fits together, and where to look in code or in official vendor docs. It is written for developers and stakeholders who need context, not just a task checklist.
Headless commerce in one sentence: your frontend owns UX and analytics; BigCommerce owns commerce logic, PCI, and order creation.
Goal: Replace the live BigCommerce Stencil storefront (debrovys.com) with the Next.js frontend in this repo (debrovys-web), while keeping BigCommerce as the commerce backend (catalog, cart, checkout, orders, payments).
Repos involved:
| Repo | Path | Role |
|---|---|---|
| debrovys-web (this repo) | E:\debrovys-web |
Next.js headless storefront — target production frontend |
| debrovys (theme / audit) | E:\debrovys |
Stencil theme, QA docs, API probes, Klaviyo/payment audit findings |
How to read the sections below: Each major topic starts with a short explanation of why it matters and how it connects to the rest of the stack. Checklists and tables follow for execution. Official vendor documentation links are collected in External reference library near the end of this doc.
Browse by topic
Same structure as the integration task list — pick a section from the sidebar or below.
BigCommerce, Klaviyo, GA4, Next.js, tRPC, Stripe, and Vercel links with context for when to use each.
Open reference library