Headless Commerce, Without the Headaches

Composable commerce promises speed and freedom, then punishes the teams who skip the catalog model. This guide starts where most tutorials end: at the data layer, because that is where the real decisions live and where the real delays are born.

Model the catalog as content, not as pages

The single most expensive mistake in a replatform is treating products as pages. The moment you do, every channel wants its own copy of the truth, and you are back to the four-inventory problem you were trying to escape. Model products, variants, prices, and availability as structured content with a single source, and let each channel render its own view on top.

• One product graph, many presentation layers.
• Availability and price computed at the edge, cached aggressively.
• Editorial content versioned and previewable, like code.
• A promotion engine that reads the graph, never duplicates it.

The three integration seams that delay launches

Ninety percent of the delays we see come from three places: the checkout handoff, the search index sync, and the order write-back to the legacy system. Design each as an explicit contract with retries and a reconciliation job from day one, and the launch stops being a prayer.

export async function handoff(cart: Cart) {
  const session = await payments.create({ cart, idempotencyKey: cart.id });
  return redirect(session.url); // same cart id, two systems, one truth
}

A headless architecture is only as composable as its worst seam. Find the seams first; the rest is rendering.