Start
Getting started
Everything on the storefront surface is plain HTTP plus one header. This page takes you from zero to rendered products: create a key, make a request, then let an SDK take over.
1 · Create a publishable key
In the Admin, open Settings → Integrations → Storefront keys and create a key. Publishable keys (pk_…) identify a store and grant read plus cart access — they are safe to ship in browser code, which is exactly what they are for.
# keys are shown ONCE at creation — store the secret, we keep only a hash▸ POST /integrations/storefront-keys (admin session){ "label": "Next.js storefront", "allowedOrigins": ["https://shop.example.com"] }◂ 201 Created{ "id": "5c1f…", "label": "Next.js storefront", "keyPrefix": "pk_live_9f2", "key": "pk_live_9f2…full value, this response only", "allowedOrigins": ["https://shop.example.com"]}
Local development: pnpm seed:demo attaches the fixed key pk_demo_localdev_headless_0000000000000000 to the demo store, with the API at http://localhost:3003.
2 · Make your first request
Send the key in the X-Publishable-Key header (or as a Bearer token). The store endpoint is the simplest smoke test:
▸ GET /storefront/v1/store▸ X-Publishable-Key: pk_live_9f2…◂ 200 OK{ "name": "Aurora Threads", "slug": "demo", "currency": "INR" }
3 · Fetch products from your app
No SDK required — the surface is plain JSON with cursor pagination on every list:
const res = await fetch(`${API_URL}/storefront/v1/products?limit=12`, { headers: { 'X-Publishable-Key': process.env.NEXT_PUBLIC_COMMERCE_PK! },});const { items, nextCursor } = await res.json();
4 · Or let an SDK do the plumbing
The framework SDKs wrap the same contracts with typed clients, hooks, and a safe renderer for merchant-edited content regions:
import { CommerceProvider, Region, useProducts } from '@commerceos/sdk-react'; <CommerceProvider apiUrl={apiUrl} publishableKey={pk}> <Region name="home-hero" fallback={<p>Loading…</p>} /> <ProductGrid /></CommerceProvider> function ProductGrid() { const { data, loading, error } = useProducts({ limit: 12 }); // data.items: [{ id, title, image, priceAmount, currency }]}
Vue, Svelte, Astro, and framework-free bindings are covered in SDKs. When you are ready to accept orders, continue to Cart & checkout.