Collections & faceted search
Two discovery surfaces on the public catalog: faceted
search and collections. Both are read over the same public,
unauthenticated catalog surface as GET /v1/tenants/:tenant/catalog/products —
no operator token, no tenant credential — and both are gated on the store being
live (an unknown/non-live tenant 404s identically, no slug enumeration) and
on products being status='active'. A failed read is always a 503, never an
empty/absent 2xx (absence-claim rule).
Faceted search
Search supports ranking and partial-token matching. An empty/whitespace q is
a valid request meaning “no query” — it returns an empty result set with a
200; a read failure is a real 503.
| Method | Path | Purpose |
|---|---|---|
GET | /v1/tenants/:tenant/catalog/search | Full-text product search with facets. |
Query parameters:
| Param | Meaning |
|---|---|
q | The search query. Blank/whitespace = “no query” (empty 200). |
limit / offset | Pagination, clamped to safe bounds. |
min_price_cents / max_price_cents | Faceted price filter (integer cents). A non-integer or negative value is treated as unset, never a silently-scoped 0. |
collection | Filter results to a collection slug. |
The response carries query, result_count, limit, offset, the echoed
filters, a facets object (price_buckets + collections), and the
matched products (each with its variants).
Collections — public
A collection has no status of its own; the store-live gate + the
status='active' product filter are its visibility contract.
| Method | Path | Purpose |
|---|---|---|
GET | /v1/tenants/:tenant/catalog/collections | List a store’s collections (slug, title, description). |
GET | /v1/tenants/:tenant/catalog/collections/:slug | Fetch one collection + its active products (with variants). |
Collections — management
Collections are operator/console-managed; you read them through the public routes above.
Manifest gates
behavior.search.enabled— the store search gate. Default true (search exists unless a store opts out); when disabled the header box renders as a plain form.behavior.search.typeahead— default true.
Collections have no dedicated manifest toggle — they render as part of the catalog surface when a store has any.
Notes
- Collection visibility is derived (store-live + active-product), not a per-collection publish/draft flag — there is no collection status.