Search for a Headless Commerce Stack: API-First Retrieval
Search is a service, not a plugin
In a headless commerce stack, the frontend is decoupled from the commerce platform, and search is one of the APIs it calls. There is no bundled search widget to configure — the storefront, the app, and any kiosk or in-store screen all hit a retrieval endpoint and render the results themselves. Headless commerce search is API design as much as it is relevance.
The retrieval service is already headless
A custom retrieval service — query in, ranked product IDs and metadata out — is naturally API-first. The service in our semantic search project is exactly this shape: a FastAPI endpoint doing query embedding, vector search, and reranking, with the frontend a separate concern. Headless is the default for that design, not an adaptation.
A stable contract matters more
When multiple frontends depend on one search API, the response schema becomes a contract. Field names, pagination, facet structure, and error shapes have to be versioned and changed carefully, because a breaking change hits every client at once. This is more discipline than a monolithic storefront's internal search needs.
Presentation stays with the client
The API returns data — products, scores, facets, suggestions — and each frontend decides how to show it. The compiled search component in the reference architecture exists so one lightweight, framework-agnostic widget can drop into any stack, but a fully custom frontend can just consume the JSON directly.
Edge caching of common queries
A large share of searches are the same popular terms. Caching those responses at the edge, with a short TTL and invalidation on catalogue changes, cuts latency and load without weakening freshness for the queries that matter. This pairs well with the price-and-stock-aware indexing the retrieval service already does.
Analytics from the client
Because the frontend owns rendering, it also owns the events — what was searched, what was clicked, what converted. Those events have to flow back to a place where the merchandising team can see them, or the relevance-tuning loop breaks.
A worked example
A retailer runs a web storefront, a native app, and in-store kiosks, all on different frontends. Each calls the same search API: query in, ranked products with scores and facets out. The web team renders results as a grid, the app as an infinite scroll, the kiosk as a large-tile layout — same data, three presentations. When the merchandising team adds a boost rule in the console, it takes effect across all three at once, because the ranking lives in the service, not the clients.
| Frontend | How it renders results | Where ranking comes from |
|---|---|---|
| Web storefront | Result grid | The search service |
| Native app | Infinite scroll | The search service |
| In-store kiosk | Large-tile layout | The search service |
Same query, same ranked results — only the presentation differs, and one boost rule in the console applies to all three at once.
Owning the contract
One team has to own the search API's response schema and its versioning. When a field changes, that team coordinates the rollout: additive changes ship freely, breaking changes get a new version with an overlap period. Without that ownership, three frontends drift apart and every improvement becomes a three-way negotiation. A published schema, a changelog, and a deprecation policy are cheap to maintain and save weeks of coordination later, especially when a fourth frontend — a partner site, a new channel — is added and expects the contract to already be documented.
| Change to the response schema | How it ships |
|---|---|
| Additive — a new optional field | Ships freely, no version bump |
| Breaking — rename, remove, restructure | New API version, with an overlap period |
| Deprecation | Announced in the changelog, removed after the overlap window |
One team owns this policy and publishes it, so the fourth frontend knows the contract before it integrates.
Where this stops being right
- A single storefront on a monolithic platform may get more from that platform's built-in search than from standing up a separate service.
- Very tight coupling to one frontend framework removes the main benefit of headless search — reuse across clients.
- If no team owns the API contract, multiple frontends drift and every change becomes a coordination problem.
FAQ
What makes search "headless"? The retrieval logic is exposed as an API that any frontend calls, with presentation left entirely to the client. There is no bundled, platform-coupled search UI.
Why does the response schema need versioning? Because several frontends depend on it as a contract. A breaking change to fields, pagination, or facets affects every client simultaneously.
How is latency managed across multiple frontends? By edge-caching responses for common queries with a short TTL and invalidation on catalogue changes, on top of a retrieval service that already reflects current price and stock.
ISTRALLEN builds API-first search for headless stacks with a versioned contract and edge caching — see AI for Retail.