Skip to content

API reference

The bc-subscriptions API is a versioned REST API served by the apps/api Cloudflare Worker. The machine-readable contract is the OpenAPI 3.0 spec — treat it as authoritative; this page is the orientation around it.

Interactive spec (Swagger UI)

Use the spec to verify field shapes before writing client code, generate mock handlers (e.g. with MSW) for tests, and validate webhook payloads.

Base URL and versioning

https://subs-api.bigcommerce-testing-7727.workers.dev/api/v1

All routes are namespaced under /api/v1. The version is part of the path; a breaking change ships under a new prefix. Clients may also send an Accept-Version header — see the SDK reference apiVersion option. Deprecations are signalled with a Deprecation response header (plus Sunset / successor Link).

Authentication

Subscriber-facing routes take a short-lived portal session JWT:

Authorization: Bearer <portal-session-jwt>

Obtain the token via the magic-link flow (POST /api/v1/portal/auth/request-link → POST /api/v1/portal/auth/verify). Store it in sessionStorage, never localStorage. Plan and product reads are public; subscription reads/writes are scoped to the authenticated subscriber by the token (there is no customer_id parameter). Full flow: SDK reference → Authentication.

Storefront plan discovery used by the widgets is unauthenticated:

GET /api/v1/storefront/plans?store_hash=…&bc_product_id=…

Don't hand-roll the client

For most integrations use the typed clients instead of raw fetch: