Storefront
A headless catalog publishing model. Admin product data is never exposed; a service user publishes a sanitized public copy under /content/public/commerce/.
Catalog projection
| Public file | Contents |
|---|---|
/content/public/commerce/catalog/index.json |
product cards for list/search |
/content/public/commerce/catalog/products/{id}.json |
product detail |
/content/public/commerce/catalog/inventory.json |
itemId → available stock |
/content/public/commerce/catalog/store.json |
store metadata (name / shopDomain / currency / lowStock) |
- only products with
commerce:source_status == activeare published - the catalog runs on the
commerce-catalog-publishtimer (every 5 minutes by default, pruning removed products) - inventory is updated near-real-time from the
inventory_levels/updateroute
Storefront SPA (ichigo.js)
/content/public/commerce/storefront/index.html — a hash-routed SPA.
| Route | Features |
|---|---|
#/ |
card grid, client-side search (title/vendor/type/tags), sort, availability badges |
#/product/{handle} |
gallery, variant selector, price, availability badge, add to cart |
#/cart |
line items (persisted in localStorage), quantity edit, total, checkout |
Checkout redirects to Shopify's hosted checkout (the cart permalink https://{shopDomain}/cart/{variantId}:{qty},...). No Storefront API token is required.
Stock is polled from inventory.json every 30 seconds and badges (Sold out / Only N left / in stock) update live (the lowStock threshold comes from store.json).
Landing pages
Block-based editable pages. They render at /content/public/commerce/landing/index.html?slug={slug}, while the admin authors them at /content/commerce/pages/{slug}.json (versioned, ACL-governed).
Block types: hero / heading / markdown / html / products (a product grid by productIds or tag). products blocks resolve against the published catalog cards, carry live inventory, and link into the storefront.
Config & operating it
Config: /etc/commerce/config/storefront.yml (enabled / storeName / currency / lowStock).
The Webtop Commerce Publishing app shows publish status, lets you rebuild, and provides a block editor for landing pages (pages.groovy).