Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.uselayers.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Blocks provide a flexible system for displaying product recommendations across your storefront. Unlike static product lists, blocks dynamically generate recommendations based on context, customer behavior, and configurable rules. Key capabilities:
  1. Multiple anchor types - Display recommendations on product pages, collection pages, the cart, the home page, search pages, 404 pages, landing pages, and custom surfaces
  2. Flexible strategies - Choose from interaction-based, similarity-based, or manual curation
  3. Conditional rules - Modify block behavior based on customer context and product attributes
  4. Safeguards - Ensure blocks always display appropriately with minimum/maximum constraints and control personalization strength
  5. Fallback chains and trees - Automatically use alternative blocks — or different chains for different audiences — when primary blocks don’t return enough products
  6. Inline performance metrics - See 7-day impressions, clicks, CTR, add-to-carts, and purchases for each block directly in the dashboard list
  7. Live preview - Test a block’s configuration against real catalog data and shopper context before saving

​
Anchor types

Anchor types determine where a block appears on your storefront and what context it uses to generate recommendations.

​
Product anchor

Display recommendations on product pages. The block uses the current product as the anchor to find related products. Common use cases:
  • “Frequently Bought Together” on product pages
  • “Customers Also Viewed” recommendations
  • “Similar Products” suggestions
  • “Complete the Look” cross-sells

​
Collection anchor

Display recommendations on collection pages. The collection is determined dynamically from the anchor_id parameter in the API request, which can be either a collection ID or handle. How it works:
  • The collection is resolved at request time using the anchor_id parameter
  • No collection selection is required in the dashboard
  • Supports both collection IDs (numeric) and handles (string)
Common use cases:
  • “Browsed Then Bought” — products purchased by shoppers who browsed the collection
  • “Trending in Collection” — products trending within the collection
  • Similar products based on the collection’s catalog
  • Featured products within a collection
  • “Editor’s Picks” for specific collections
  • Collection-specific promotions

​
Cart anchor

Display recommendations in the cart. The block uses products currently in the cart to find complementary items. Common use cases:
  • “Complete the Look” in cart
  • “Frequently Bought Together” based on cart contents
  • Cross-sell recommendations before checkout

​
Home anchor

Display recommendations on the storefront home page. The block has no anchor product or collection, but trending strategies can use store-wide activity to populate results. Common use cases:
  • “Best sellers” and “Trending now” rails
  • “Popular in your area” region-aware rails
  • Manually curated “Featured products” hero

​
Search anchor

Display recommendations on search results pages. The current search query is passed in via the API request context and powers query-aware contextual strategies. Common use cases:
  • “Shoppers also viewed” alongside search results
  • “Top picks for this search” conversion rails
  • Recovery rails on zero-result searches

​
Not found anchor

Display recommendations on 404 pages so a missing URL becomes a discovery moment instead of a dead end. Common use cases:
  • “You may also like” fallback on 404s
  • “Best sellers” or “Trending now” to keep shoppers in the funnel
  • Recently viewed re-engagement

​
Landing anchor

Display recommendations on campaign landing pages. The traffic source (UTM parameters, marketing channel) is passed in via the request context and can drive contextual strategies. Common use cases:
  • Channel-aware “Top picks for this campaign” rails
  • Trending rails for launch and promo pages
  • Manually curated hero blocks on paid traffic destinations

​
Other anchor

Display recommendations on custom storefront pages that don’t fit the standard surfaces — about pages, blog posts, custom routes. Common use cases:
  • Trending rails on editorial content
  • Cross-sell blocks on app or custom pages
  • Manually curated placements outside the main funnel

​
None anchor

Global blocks that can appear anywhere on your storefront. These blocks require no anchor context and only support the manual strategy. Common use cases:
  • Hand-picked “Featured products” on static pages
  • Manually curated rails embedded in custom templates

​
Block preview

The block editor includes a Preview panel that runs the block’s current configuration against your live catalog without saving. Use it to:
  • Sanity-check anchor selection by entering a real product or collection ID
  • Simulate visitor context (geography, marketing channel, device, identity) to verify rule branches
  • Compare different strategy and safeguard combinations before publishing
The preview returns the same product results the Blocks API would return for the configured anchor and context, including any active rules and safeguards. Fallback chains and trees are not evaluated in the preview — only the primary block’s configuration is run.

​
Inline performance metrics

The blocks list shows a 7-day rolling performance summary for each block, refreshed every four hours:
  • Impressions — number of times the block was rendered (block requests)
  • Clicks — distinct product views attributed to the block
  • CTR — clicks ÷ impressions
  • Add to cart — distinct add-to-cart events attributed to the block
  • Purchases — distinct purchases attributed to the block
A small sparkline next to each row shows the daily trend across the last seven days. The same metrics are available on merchandising rules — see Metrics for how attribution works.
Metrics rely on the attribution token returned by the Blocks API and forwarded to the Beacon API. Make sure your storefront forwards click, add-to-cart, and purchase events with the block’s attributionToken for these counts to populate.

​
Performance details

Click any row’s performance summary on the Recommendation Blocks list to open the Performance sheet for that block. The sheet provides a deeper view of how a block is converting and which products are driving its results. The sheet has four sections:
  • KPI cards — Impressions, CTR, add-to-cart rate, purchase rate, revenue, and revenue per impression (RPI). Each card shows the absolute value and the percent change versus the prior period of the same length.
  • Trend — A combined line/bar chart showing impressions, clicks, add-to-carts, and purchases across the selected timeframe. Use it to spot day-of-week patterns or campaign spikes.
  • Position — A breakdown of how the block performs by slot position, helping you understand whether top-positioned products carry the conversion or if engagement spreads evenly across the carousel.
  • Top products — The products that drove the most impressions, clicks, and revenue for the block. Each row shows the product title alongside its individual performance metrics.
You can switch the timeframe between 7 days, 14 days, and 30 days using the toggle at the top of the sheet. Results are cached briefly per block and timeframe, then refreshed in the background — when fresh data is ready it streams in automatically without requiring a reload. Click, add-to-cart, and purchase totals on the KPI cards are blended — they combine events forwarded with the block’s attributionToken and modeled events from the same browsing session that happened within ten minutes of the block being shown. The KPI cards expose the deterministic-versus-modeled split so you can see how much of each metric came from each signal. See Metrics: Blended attribution for the full breakdown.
The performance sheet uses the same attribution data as the inline metrics. If your storefront isn’t forwarding the attributionToken to the Beacon API, the sheet will show empty results.

​
Bulk actions

The Recommendation Blocks list supports multi-select for fast cleanup, audits, and seasonal launches:
  1. Click Select in the actions column header to enter selection mode.
  2. Tick the checkbox on each block you want to act on. Hold Shift and click another checkbox to select every row in between.
  3. Open the Actions dropdown and select one of the bulk actions:
    • Publish — Activate every selected draft block at once.
    • Unpublish — Move every selected active block back to draft so it stops returning results, without losing your configuration.
    • Duplicate — Create a draft copy of each selected block named <title> (Copy). Duplicates always start as drafts so they never accidentally go live.
    • Delete — Permanently remove the selected blocks. A confirmation dialog appears before the deletion runs.
Click Actions → Done selecting to exit selection mode.
Use Shift+click on rows when you want to flip a long range of blocks between published and draft for a campaign — for example, unpublishing every clearance block at the end of a sale.

​
See also