How to use this checklist
Each section below covers one surface area of a Layers theme integration. Every row has a Who column showing whether the work is handled by the App embed (the Layers theme app extension) or by Dev (your theme code), along with notes pointing at the relevant docs. When a row is marked App embed, the behavior is automatic the moment the embed is toggled on in Online Store → Themes → Customize → App embeds — there is no theme code to write for that item. See What the app embed and SDK handle for you for the full inventory. Work the sections in order. Each one assumes the previous section is complete.If you adopt the
@commerce-blocks/sdk, every Dev row in this checklist has a Liquid + SDK variant that wraps the network call, the caching, and the state management — but the work itself is the same. Use the Liquid + Fetch or Liquid + SDK guides depending on which path you’re on.1. App embed
| Item | Who | Notes |
|---|---|---|
| Install the Layers Shopify app and enable the theme app extension | Dev | Online Store → Themes → Customize → App embeds → Layers. See Storefront Pixel. |
Storefront token loaded from shop.metafields.layers.embed_settings | App embed | Automatic. Read the same metafield in Liquid when you need it for direct fetch calls. See Liquid integration. |
| Device and session IDs | App embed | Persisted via cookies / sessionStorage. Cookie fallbacks configured via sessionCookieFallbacks. |
| Cart and customer context attached to every Layers request | App embed | productsInCart, customer ID, segment, and tag context all forwarded. |
| Shopify Markets context (currency, country, language) | App embed | Forwarded when Shopify Markets is configured. |
collection_view, product_view, product_click, add_to_cart, block_view tracking events | App embed | Captured by the storefront pixel and shipped to the Tracking API. |
_layers_attribution line item property on add-to-cart | App embed | Appended when the shopper clicked from a Search/Browse response. |
| Order attribute writing for attribution | App embed | Reads _em_* and _layers_session_id on orders. Edgemesh attributes take priority when present. |
| Semantic redirect interception | App embed | Handled automatically when the app embed is installed. See Semantic Redirects. |
?utm_products= dynamic linking | App embed | Inbound links expand to matching products. See Dynamic linking. |
| Third-party forwarding (Clarity, Blotout, Rivo, Abra, FoxSell, Edgemesh) | App embed | Toggle in dashboard. See Third-Party Integrations. |
Search Inspector (?_layers_debug_menu=true) | App embed | Available on every page. See Search Inspector. |
2. Currency selector
| Item | Who | Notes |
|---|---|---|
| Market detection on Layers requests | App embed | Active market forwarded with every request. |
| Currency switcher UI in the theme | Dev | Standard Shopify currency picker. Layers reads market from the storefront context — no Layers-specific wiring needed. |
| Price formatting on rendered cards | Dev | Format priceRange.formatted (SDK) or price_range.min_variant_price (Fetch) using the active currency. |
3. Search
Search results page
| Item | Who | Notes |
|---|---|---|
Route handler for /search | Dev | Wire the search query from the URL to a Layers Search request. See Implementing search in Liquid or with the SDK. |
| Authentication and identity on the search request | App embed | Storefront token, device ID, session ID, cart, customer all forwarded. |
| Render the results grid | Dev | Use the same product tile component you use on collection pages. |
| Render facets and sort | Dev | See Rendering facets in Liquid and Rendering sort orders in Liquid. |
| Banners on the search results page | Dev | Same top-level banners array as browse. See Rendering banners in Liquid. |
| Empty-state and no-results UI | Dev | Hide facets / sort when results.length === 0. |
| Auto redirect for matching queries | App embed | Handled automatically when the app embed is installed. |
Autocomplete
| Item | Who | Notes |
|---|---|---|
| Wire the autocomplete input to the Layers Autocomplete API | Dev | Debounce 100–200ms. See Implementing search in Liquid → autocomplete. |
| Render suggested terms, products, and collections | Dev | The response contains all three sections. |
| Autocomplete tracking events | App embed | autocomplete events captured automatically. |
| Curated autocomplete entries | Platform | Configure under Autocomplete curation. |
4. Collection pages
Sort
| Item | Who | Notes |
|---|---|---|
Sort-order dropdown populated from app--278936322049--sort_order metaobjects | Dev | See Rendering sort orders in Liquid. |
Default sort from collection.metafields.layers.default_sort_order | Dev | See Liquid integration → Collection default sort. |
| Pass the selected sort code into Browse | Dev | Re-execute the request on change. |
Facets
| Item | Who | Notes |
|---|---|---|
Facet sidebar populated from app--278936322049--facet metaobjects | Dev | Names and codes come from Liquid; values and counts come from the Browse API. See Rendering facets in Liquid. |
| Active filter state in URL | Dev | Reflect selected filters in query string so back/forward works. |
| Re-execute Browse on filter change | Dev | Send the filter group on every request. See Filtering. |
| Numeric ranges (price, etc.) | Dev | Read from top-level data.priceRange (SDK) or facets.variants.price (Fetch). |
Grid
| Item | Who | Notes |
|---|---|---|
| Product grid driven by Browse results | Dev | Standard tile component. |
| Pagination | Dev | pagination: { page, limit }. Re-execute on page change. |
| Banners — hero rows above the grid | Dev | See Rendering banners in Liquid. |
Banners — inline overtake and inject tiles by position | Dev | Same render guide. |
| Pin / sort / variant breakout consequences | Platform | Configured in merchandising rules. The grid order Layers returns is the order you render. |
| Cart / customer context on browse | App embed | Forwarded automatically. |
5. Recommendation blocks
| Item | Who | Notes |
|---|---|---|
Block-picker section setting populated from app--278936322049--block metaobjects | Dev | See Rendering blocks in Liquid and the SDK twin. |
Anchor wiring (product.id, collection.handle, none) | Dev | Per-template data-anchor-id. |
| Fetch / hydrate the block | Dev | See the rendering guides. |
| Cart context for cart-anchored blocks | App embed | productsInCart injected automatically. |
| Cross-block product deduplication | App embed | Products rendered earlier on the page are excluded from later blocks. |
| Click attribution and feedback | App embed | The embed listens for clicks on rendered cards and submits feedback. |
| Fallback chain (when a block has no results) | Platform | Configured under Fallback chains. Hide the section when results are empty. |
6. Visual search
| Item | Who | Notes |
|---|---|---|
| Visual Search widget loaded | App embed | Provided by the embed once enabled in the dashboard. |
| Placement on PDPs and collection pages | Dev | Choose where the entry point appears. |
| Clarity / Blotout forwarding of visual-search events | App embed | Automatic when the integration is enabled. |
7. Similar Products (PDP)
| Item | Who | Notes |
|---|---|---|
| Similar Products section on PDPs | Dev | Anchor a block on product.id with a similar-products strategy. See Rendering blocks in Liquid. |
| ”Shop similar” entry point on tiles | Dev | Optional UX affordance — opens the Visual Search flow keyed on the tile’s product. |
| Identity, cart, attribution on the request | App embed | Automatic. |
8. QA and go-live
| Item | Who | Notes |
|---|---|---|
| Open the Search Inspector on representative pages | Dev | ?_layers_debug_menu=true. Verify request, response, attribution, and pixel events on a collection page, a search page, a PDP, and the cart. See Search Inspector. |
Confirm collection_view, product_view, product_click, add_to_cart, block_view are firing | Dev | Inspector shows the events as they go out. |
Confirm _layers_attribution appears on add-to-cart line items | Dev | Click from a Layers-surfaced tile, add to cart, then inspect the line item properties. |
| Confirm market context on requests when running with Shopify Markets | Dev | Inspector shows the market the embed sent. |
| Test a banner-bearing rule on the storefront | Dev | Hero placement above the grid, inline placement at the right position, both web and mobile breakpoints. |
| Test auto-redirect for a configured semantic redirect | Dev | Search the matching query and confirm the redirect fires. |
Test a ?utm_products= link | Dev | Confirm the inbound link surfaces the expected products. |
| Confirm third-party forwarding (if enabled) | Dev | Spot-check the relevant tool — Clarity replay, Blotout dashboard, Edgemesh attribute on a test order. |
| Pre-launch search quality pass | Platform | Run through Test text search to confirm ranking is shaped how you want. |
| Final pixel + tracking sign-off | Dev | One full purchase flow with the inspector open to confirm _em_* / _layers_session_id are written to the order. |
See also
- What the app embed and SDK handle for you — full reference for everything marked App embed above.
- Liquid integration — reading Layers metaobjects and metafields from Liquid.
- SDK overview — the optional client library that wraps every Dev row’s network call.
- Storefront Pixel — Search Inspector and tracking reference.