Storefront Faceted Filtering
Typesense-backed faceted filters on collection pages. Auto-detected from product data with merchant-configurable overrides.
Overview
Faceted filtering is built into every Cartly collection page and powered by Typesense. Filters appear automatically from product data — no theme changes required. Merchants configure overrides from Admin → Settings → Storefront Filters.
Built-in filter types
| Filter | URL param prefix | Notes |
|---|---|---|
| Variant option | filter.v.option.<key> | Case-insensitive. Auto-detected from variant data. |
| Product tag | filter.v.tag | Multi-value AND logic. |
| Vendor | filter.v.vendor | Shown when data exists. |
| Availability | filter.v.availability | true = in-stock only. |
| Price range | filter.v.price.gte / .lte | Values in cents (int64). |
| Product metafield | filter.v.p.metafields.<ns>.<key> | Requires storefront_filterable=true on definition. |
URL parameter scheme
bash
/collections/t-shirts?filter.v.option.color=Red&filter.v.tag=new&filter.v.price.gte=2000&sort_by=price-ascendingAPI Reference
| Method | Path | Description |
|---|---|---|
| GET | /admin/storefront-filters | List overrides |
| GET | /admin/storefront-filters/available-sources | All filter sources (built-ins + options + filterable metafields) |
| POST | /admin/storefront-filters | Create override |
| PUT | /admin/storefront-filters/:id | Update override |
| DELETE | /admin/storefront-filters/:id | Delete override |
| PUT | /admin/storefront-filters/reorder | Bulk reorder (max 200 positions) |
| POST | /admin/storefront-filters/reindex | Trigger full-shop Typesense reindex |
| GET | /admin/storefront-filters/reindex-status | Poll reindex progress |
All endpoints require a valid admin JWT. State-changing endpoints require X-Idempotency-Key header.