Skip to content

bc-subscriptions integration guide

Generated from the canonical integration guide

This page is generated from docs/integration/README.md — the single source of truth shared with the public marketing site. Edit the canonical file, then run npm --prefix tools/integration-docs-derive run derive.

Choose the path that matches your storefront stack. All three tiers share the same backend API (apps/api) and the same subscriber portal experience — only the delivery mechanism differs.

No-code merchant path? If you're a merchant on a BigCommerce-managed Stencil theme, you don't need a developer — the widget is enabled from the admin and no theme code changes are required. Follow the merchant getting-started guide (install → connect processor → create a plan → publish the widget), then return here only if you want manual placement control. The tiers below are for agency / in-house developers integrating Catalyst or a custom headless storefront.

Pick your tier

flowchart TD
    start[I want to integrate bc-subscriptions] --> q1{What storefront do you run?}
    q1 -->|BC Stencil theme managed by BC| stencil["Tier 1: Stencil widget IIFE\n→ docs/integration/stencil.md"]
    q1 -->|Catalyst Next.js| catalyst["Tier 3: React components\n→ docs/integration/catalyst.md"]
    q1 -->|Custom headless / other framework| headless["Tier 2: Web component or SDK\n→ docs/integration/headless.md"]
Tier Stack Package Install complexity
Tier 1 — Stencil BC-managed Stencil theme No npm package — BC Script Manager drop-in Low (operator-configured via admin wizard)
Tier 2 — Headless Any headless framework @bc-subscriptions/storefront-webcomponent Low–medium (CDN tag or npm)
Tier 3 — Catalyst Catalyst (Next.js App Router) @bc-subscriptions/storefront-catalyst Medium (React components + API client)

Per-tier walkthroughs

Testing

  • Testing your integration — validate the full subscribe → charge flow end to end in Stripe test mode (test keys + test cards), exercise decline/dunning + 3DS, then swap to live keys

Reference

  • SDK reference — @bc-subscriptions/subscriber-sdk API surface, type generation, error handling
  • API reference — Swagger UI at https://api.bcsubs.dev/docs (OpenAPI 3.0)
  • ADRs — ADR-0013 (component shape), ADR-0005 (three-surface UI)
  • Three-tier rationale — Hive #1069

Before you start

All tiers require a configured bc-subscriptions installation:

  1. The bc-subscriptions app must be installed on the merchant's BigCommerce store.
  2. At least one subscription plan must be created in the admin.
  3. The API Worker (apps/api) must be deployed and reachable from the storefront.

The admin wizard at apps/admin guides merchants through stack detection and plan creation. Developers building a custom integration should confirm these prerequisites with the merchant before starting.