One commerce core.
Every experience.

Set one store ID

Replace only storeId in the starter’s headless-config.json. The bootstrap endpoint returns public runtime values for a store that an operator has already provisioned. Unknown stores fail closed; they never fall back to sample products.

// headless.config.json — the only value you replace
{ "storeId": "YOUR_STORE_ID" }

const runtime = await fetch(
  `https://api.1ecomm.com/v1/headless/stores/${storeId}/config`
).then(r => r.json());

const response = await fetch(
  `${runtime.data.apiUrl}/v1/headless/products?limit=12`,
  { headers: { 'x-publishable-key': runtime.data.publishableKey } }
);

if (!response.ok) throw new Error('Catalog unavailable');
const catalog = await response.json();

Create an isolated shopper cart

Create the cart once and retain the returned hc_… bearer capability in secure shopper-session storage. Send it as x-cart-token on later cart calls.

const created = await fetch('/v1/headless/carts', {
  method: 'POST',
  headers: { 'x-publishable-key': PUBLIC_KEY }
}).then(r => r.json());

// Keep this bearer capability out of URLs, logs and analytics.
sessionStorage.setItem('cart_token', created.cartToken);

Add server-approved products

Use product and variant IDs returned by the catalog. A product with options needs the chosen variantId. Render the cart projection returned by the API—price, promotion and totals are server-calculated. Never automatically retry mutations after an uncertain network result.

Prepare checkout

Save bounded guest contact and addresses with PATCH /v1/headless/carts/current/checkout. Render only returned shipping and checkout-ready payment methods, then persist selections using their returned IDs.

Place only an approved non-hosted order

Resolve every field in missing[], then inspect the selected payment method. Only when it explicitly returns requiresHostedCheckout: false and canPlaceOrder: true, call POST /v1/headless/carts/current/checkout/order with a caller-owned Idempotency-Key of 1–120 characters.

const intent = crypto.randomUUID(); // retain across uncertainty
const placed = await fetch('/v1/headless/carts/current/checkout/order', {
  method: 'POST',
  headers: {
    'x-publishable-key': PUBLIC_KEY,
    'x-cart-token': CART_TOKEN,
    'Idempotency-Key': intent
  }
});

Reconcile uncertainty; never duplicate intent

If the order response is lost or times out, retry with the same cart token and the exact same idempotency key. A successful response returns a pending order confirmation; it does not authorize or capture payment. Hosted card and wallet methods must use a future hosted flow and are rejected by this command.