Endpoints — overview

One page per resource, rendered from docs/api/openapi.yaml.

That spec is a committed file, regenerated by hand (pnpm --filter backend generate:openapi, which needs a booted backend). Nothing regenerates it on deploy. Two things follow, and both are visible on these pages:

• The reference reflects the last regeneration, not the running backend. A route added since then is live but absent here.
• Several resources are missing from the spec entirely, so their pages render an intro and no operations. See Pages with no operations yet.

What's on each page

Each resource page shows the endpoints the spec carries for that resource with:

• Method + path — exactly what to call
• Authentication — api-key for /v1/*, app-installation for /v1/installations/*, none for public /vc/* and /stores/{storeId}/* reads
• Required scope — for API-key auth
• Query / path / body parameters — type, description, required/optional
• Response schema — full shape with field types
• Code samples — curl, TypeScript (via the brainerce SDK), and Python (requests)
• Interactive playground — paste your API key, hit "Send", see the live response

Not every listed route is /v1/*

These pages are not filtered to the public /v1/* contract, whatever an earlier version of this page said. The spec covers four path prefixes and the resource pages render all of them:

Cart, checkout, orders, customers, inventory, brands, categories, tags, metafields, bundle offers and order bumps all lead with /vc/{connectionId}/… operations; email and coupons lead with /stores/{storeId}/… and bare /coupons. Only the /v1/* rows carry the versioning guarantee — check the path before you build against an operation on these pages.

{connectionId} in those paths is the deprecated spelling of {salesChannelId}; the value is the same vc_* string. The generator emits whatever the backend route declares, so the rename has to happen in the controllers first.

Pages with no operations yet

Eight pages render their intro and nothing else, because the spec contains no paths for them. The endpoints are real and live — only the reference is missing. Use these instead:

Pages

Commerce

• Public API (v1) — the whole /v1/* surface on one page
• Products — catalog CRUD, variants, bulk create
• Orders — orders, fulfillment, refunds, draft orders
• Customers — profiles, addresses, OAuth, authentication
• Cart — server-side cart with coupons
• Checkout — flow, custom fields, completion
• Inventory — stock tracking, reservation, reconciliation

Marketing

• Coupons
• Bundle offers
• Order bumps
• Product Reviews

Taxonomy

• Categories
• Brands
• Tags
• Attributes
• Metafields

Fulfillment

• Shipping
• Tax

Operations

• Media — upload, list, replace, delete
• Sync — metafield-conflict resolution. Note POST /v1/sync itself returns 501 — see Errors

Admin

• Email — settings and template management
• Installations — marketplace-app mappings and secrets

Marketplace apps

Routes that accept app_inst_* installation tokens (under /v1/installations/*) are documented on the Installations page and in App Installation Tokens. The HTTP MCP server has its own reference at MCP server.

How this is generated

backend controllers (with @ApiOperation / @ApiProperty decorators)
   ↓
pnpm --filter backend generate:openapi      (manual; needs DB + Redis + Clerk to boot)
   ↓
docs/api/openapi.yaml                       (committed to the repo)
   ↓
pnpm --filter frontend generate:api-docs    (manual)
   ↓
content/docs/api/endpoints/{resource}.mdx   (generated — do not hand-edit)
   ↓
runtime render: APIPage renders schema + playground from openapi.yaml

Both steps are manual and neither runs in CI, which is why the spec drifts. Every public-API change is supposed to run both — see the "API-First: Change Checklist" table in the root CLAUDE.md.

The .mdx files in this directory are generated output. Editing one is undone by the next regeneration; fix the backend decorators and re-run the generators instead.