Building a storefront on Crystallize

The API pages under APIs tell you how each API behaves. This section tells you which API to call for a task and in what order. It follows a storefront from the first catalogue read to a confirmed order, and then covers what makes the store good to use: fast pages, an accessible interface, structured data for search engines, and tools for AI agents.

The examples come from working storefronts on Crystallize demo tenants (see "Reference implementations and inspiration" below). They use Next.js (App Router) where a framework is needed, but the API calls are the same in any stack.

A Crystallize storefront talks to two APIs at runtime:

• Discovery API for every catalogue read: pages by path, category listings, search, typeahead, facets, variants, prices, stock and translated paths. It is read-only, served from a distributed index, and open by default. See Discovery API.
• Shop API for everything about a shopper: the cart, the price for this customer and market, promotions, placing the cart, creating the order, payments, pipeline stages, order history, customers and bookings. It needs a JWT that only your server holds. See Shop API.

Two more APIs exist, and a storefront rarely needs them:

• The Catalogue API is a fallback for one task: displaying per-customer (contract) prices.
• The Core API is never in the storefront's request path. It is for imports, seeding, scheduled jobs, webhooks and back-office tools behind a staff login. It is rate limited and not built for shopper traffic.

Check four things on the tenant before writing the first page:

1. The tenant is ignited. The Discovery API serves nothing until the tenant's index exists. A tenant without one answers HTTP 404 with "There is no ignited Tenant".
2. Every component you render is discoverable. A component with discoverable: false is left out of the Discovery schema, and so is a shape with no discoverable components left.
3. You have an access token pair for the Shop API. Your server exchanges it for a Shop API JWT. A token restricted to a single tenant can't mint one. See Access tokens.
4. Secrets stay on the server. The access token pair and the Shop API JWT are never sent to the browser. The browser holds only the cart id, in an httpOnly cookie.

1. The storefront API contract: which API serves which task, with tokens and scopes.
2. Request path: the calls behind a catalogue page, a product page, the cart and checkout.
3. Languages, markets and routing: language and market in the path, translated paths and hreflang.
4. Cart, checkout and orders: the Shop API flow from cart to order, B2B prices, quotes and bookings.
5. Caching and revalidation: cached Discovery reads, refreshing them on publish, and the consistency a storefront has to live with.
6. Preview with custom views: draft preview inside the Crystallize App, with a preview route, draft reads, noindex and framing.
7. Next.js App Router: Cache Components, streaming and the pitfalls specific to Next.js.

1. Performance: Core Web Vitals, images, the LCP element and prefetching.
2. Accessibility: the accessibility tree that screen readers and AI browsers both read.
3. Security headers: companion headers, CSP, framing and cookies.

1. SEO and GEO: structured data, llms.txt and Markdown, crawlers and sitemaps.
2. Agentic commerce: a shopper MCP server, MCP Apps cards, WebMCP and an on-site assistant.

superfast.shop is a set of live demo stores, one per industry. Each runs on its own Crystallize tenant with a storefront on the Discovery and Shop APIs, and each was built agentically with the Crystallize MCP server. Use them to see how a storefront can be built, and as a starting point for your own:

• superfast.shop lists the stores and filters them by capability or audience, for example subscriptions or B2B.
• Every store has its own page, such as superfast.shop/demos/tools-universe, with a build prompt you can hand to a coding agent: prompt.md.
• start.md is an interview that writes a build prompt for your own business.
• For agents and scripts: llms.txt and demos.json.

The pages in this section link to the store that shows each topic best.