Skip to main content

​
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, in the cart, or globally
  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
  5. Fallback chains - Automatically use alternative blocks when primary blocks don’t return enough products

​
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

​
None Anchor

Global blocks that can appear anywhere on your storefront. These blocks don’t require any anchor context. Common use cases:
  • “Best Sellers” on homepage
  • “New Arrivals” on homepage
  • “Featured Products” on static pages
  • “Trending Now” global widget

​
Strategy Types

Strategies define how products are selected for a block. Each anchor type supports different strategies.

​
Interaction Strategies

Use behavioral data to find products that customers frequently interact with together. Interaction data is computed periodically based on historical events.
Products that are frequently purchased together in the same order.Supported anchors: Product, CartUse cases:
  • Product page: “Customers who bought this also bought…”
  • Cart: “Complete your purchase with these items”
Products that are frequently viewed together in the same browsing session.Supported anchors: ProductUse cases:
  • Product page: “Customers also viewed these products”
  • Browse abandonment recovery
Products that are frequently added to cart together in the same session.Supported anchors: ProductUse cases:
  • Product page: “Often added together”
  • Cart optimization
Interaction strategies require sufficient historical data to generate meaningful recommendations. While strategy data is being computed, blocks using interaction strategies automatically return empty results and defer to their fallback chain. The API response includes a _training flag during this period.

​
Collection Interaction Strategies

Use behavioral data to find products related to a collection based on how shoppers who browse that collection interact with products. Unlike product interaction strategies (which find product-to-product relationships), collection interaction strategies compute collection-to-product relationships.
Products frequently purchased by shoppers who browsed the collection.Supported anchors: CollectionUse cases:
  • Collection page: “Popular purchases from this collection”
  • Cross-sell products based on collection browsing behavior
Products frequently viewed by shoppers who browsed the collection.Supported anchors: CollectionUse cases:
  • Collection page: “Shoppers also viewed these products”
  • Discover products related to a collection through browsing patterns
Collection interaction strategies require sufficient historical browsing and interaction data. Data is computed periodically based on configured time windows (7d, 30d, 90d).

​
Similar Products Strategy

Use vector similarity to find products that are visually and semantically similar to the anchor product. Supported anchors: Product, Collection How it works: The system generates embeddings for each product based on product images, titles, descriptions, and attributes. When a customer views a product, the block finds products with the most similar embeddings using vector similarity search. For collection anchors, the system automatically selects a representative product from the collection to use as the similarity source. Use cases:
  • “Similar Products” on product pages
  • “You May Also Like” recommendations
  • Visual discovery and exploration
  • Collection-based similarity recommendations

​
Manual Strategy

Curate products using a collection or hand-picked product IDs, with optional custom sorting. This strategy gives you complete control over which products appear in the block. Supported anchors: Collection, None Configuration:
  • Hand-picked products: Select specific products by ID in the dashboard. The display order matches the order you define. When hand-picked product IDs are configured, they take priority over collection-based selection.
  • Collection anchor blocks: The collection is determined dynamically from the API request’s anchor_id parameter (no collection selection needed in dashboard)
  • None anchor blocks: Select a collection to pull products from in the dashboard
  • Optionally apply a sort order for custom sorting
Use cases:
  • “Best Sellers” block (collection of top products, sorted by sales)
  • “New Arrivals” block (collection of recent products, sorted by date)
  • “Editor’s Picks” (curated collection with custom order)
  • “Staff Picks” (hand-picked products in a specific order)
  • Seasonal promotions (collection of seasonal products)

​
Strategy Availability by Anchor Type

Not all strategies are available for all anchor types. Here’s the compatibility matrix:
StrategyProductCollectionCartNone
Frequently Bought Together✓✗✓✗
Customers Also Viewed✓✗✗✗
Customers Also Added to Cart✓✗✗✗
Browsed Then Bought✗✓✗✗
Browsed Then Viewed✗✓✗✗
Trending in Collection✗✓✗✗
Similar Products✓✓✗✗
Manual✗✓✗✓

​
Block Rules

Rules allow you to modify block behavior based on contextual conditions and product attributes. Rules are evaluated in order, and the first matching rule’s actions are applied.

​
Targeting Conditions

Targeting conditions evaluate context and product attributes. Available fields include: Anchor product attributes:
  • Product type
  • Vendor
  • Tags
  • Price
  • Any other product attribute
Contextual data:
  • Geographic location (country, state, city)
  • Customer tags
  • Device type
  • Marketing source, medium, and campaign

​
Rule Actions

Add additional filtering to the block’s product results.Use cases:
  • Show only products from the same vendor as the anchor product
  • Filter by price range based on anchor product price
  • Show only products with specific tags
  • Apply geographic filtering (e.g., show winter products to cold climates)
Hide the block entirely when conditions are met. The fallback chain will be used instead.Use cases:
  • Hide “Frequently Bought Together” if anchor product is out of stock
  • Hide blocks for specific customer segments
  • Hide blocks on mobile devices
  • Hide blocks for specific geographic regions
Switch to a different strategy when conditions are met.Use cases:
  • Use “Similar Products” for mobile users instead of “Frequently Bought Together”
  • Switch to different interaction strategies based on customer segment
  • Use different strategies for different product types
Modify the block’s safeguards (min/max products, hide out of stock) based on conditions.Use cases:
  • Show more products for VIP customers
  • Adjust minimum products based on device type
  • Enable/disable out-of-stock filtering based on inventory levels

​
Multiple Rules

You can configure multiple rules for a single block. Rules are evaluated in order, and the first matching rule’s actions are applied.

​
Safeguards

Safeguards ensure blocks display appropriately and provide a good customer experience.

​
Hide Out of Stock

Automatically filter out products that are not available for purchase. Behavior:
  • Products with unavailable status are excluded from results
  • Applies after strategy execution but before pagination
  • Can be overridden by rules

​
Minimum Products

If the block returns fewer than the minimum number of products, the fallback chain is used instead. Behavior:
  • Evaluated after filtering and safeguards are applied
  • If results are below minimum, the system tries the first fallback block
  • If no fallback blocks are configured, the block returns the available products
  • Prevents displaying blocks with too few recommendations
Use cases:
  • Ensure “Frequently Bought Together” always shows at least 4 products
  • Maintain consistent block appearance across pages
  • Automatically fall back to curated collections when behavioral data is insufficient

​
Maximum Products

Limits the total number of products returned by the block across all pages. Behavior:
  • Applied after all filtering and sorting
  • Caps the total result set to the specified maximum across all pages
  • totalResults and totalPages reflect the capped total, ensuring consistent pagination metadata
  • Pages beyond the cap return empty results
Use cases:
  • Limit recommendations to fit specific UI layouts
  • Control page load performance
  • Maintain consistent block sizes

​
Fallback Chains

Fallback chains ensure customers always see recommendations, even when the primary block doesn’t return enough products.

​
How Fallback Chains Work

When a block doesn’t meet its minimum products safeguard, the system automatically tries fallback blocks in order:
  1. Primary block is evaluated first
  2. If results are below minimum, try Fallback 1
  3. If Fallback 1 also doesn’t meet minimum, try Fallback 2
  4. Continue until a block meets the minimum or all fallbacks are exhausted

​
Fallback Modes

Each entry in the fallback chain can be configured with one of two modes:
  • Replace (default): The fallback block’s results replace the primary block’s results entirely if the fallback meets the minimum products requirement. This is the original behavior.
  • Fill: The fallback block’s products are appended to the existing results (deduplicated by product ID). This lets you “top up” a partially filled block instead of replacing its results. The system respects the maximum products safeguard when merging, and totalResults in the response accounts for deduplication across all sources.
Fill mode is useful when the primary block returns some relevant results but not enough to meet the minimum. Instead of discarding those results, fill mode supplements them with products from the fallback.

​
Configuring Fallback Chains

Fallback chains are configured as an ordered list of block IDs, each with an optional fallback mode. Important considerations:
  • Fallback blocks must be active
  • Fallback blocks should have the same anchor type as the primary block
  • Avoid circular references
  • Fallback blocks can have their own fallback chains
  • The system prevents infinite loops by tracking visited blocks
  • You can mix replace and fill modes in the same chain

​
Fallback Chain Best Practices

Strategy diversity: Use different strategy types in your fallback chain to maximize coverage. 
Primary: Interaction-based (requires behavioral data)
Fallback 1: Similarity-based (requires embeddings)
Fallback 2: Manual collection (always has products)
Progressive relaxation: Start with highly personalized strategies and fall back to broader recommendations. 
Primary: "Frequently Bought Together" (highly specific)
Fallback 1: "Customers Also Viewed" (broader)
Fallback 2: "Best Sellers in Category" (broadest)
Fill mode for supplementing results: Use fill mode when you want to keep the primary block’s results and top them up with additional products. 
Primary: "Frequently Bought Together" (may return 2-3 products)
Fallback 1 (fill): "Similar Products" — appends products to reach the minimum
Fallback 2 (replace): "Best Sellers" — used entirely if combined results are still insufficient
Anchor type consistency: Ensure fallback blocks use the same anchor type to maintain context. 
Product anchor primary → Product anchor fallbacks
Cart anchor primary → Cart anchor fallbacks
Minimum products alignment: Set appropriate minimums for each block in the chain. 
Primary: minimum_products = 4
Fallback 1: minimum_products = 2
Fallback 2: minimum_products = 1 (always shows something)

​
Block Priority and Ordering

When multiple blocks target the same anchor type, you can control which block is used through priority ordering.

​
Priority System

Blocks have a priority field that determines evaluation order:
  • Lower numbers = higher priority
  • Blocks are evaluated in ascending priority order
  • The first block whose rules match is used

​
Use Cases for Multiple Blocks

Geographic targeting: 
Block 1 (priority 0): US visitors → US-specific recommendations
Block 2 (priority 1): EU visitors → EU-specific recommendations
Block 3 (priority 2): Default → Global recommendations
Customer segmentation: 
Block 1 (priority 0): VIP customers → Premium recommendations
Block 2 (priority 1): Returning customers → Personalized recommendations
Block 3 (priority 2): New visitors → Popular products
Device optimization: 
Block 1 (priority 0): Mobile → Mobile-optimized layout (8 products)
Block 2 (priority 1): Desktop → Desktop layout (16 products)

​
Block Status

Blocks have a status field that controls whether they’re active:
  • Active: Block is live and will be returned by the API
  • Draft: Block is not live and won’t be returned by the API
Only active blocks are evaluated when processing API requests. Draft blocks are useful for:
  • Testing new block configurations before going live
  • Temporarily disabling blocks without deleting them
  • Preparing seasonal blocks in advance

​
See Also