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 block uses the current collection as context. Common use cases:
  • 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.

​
Similar Products Strategy

Use vector similarity to find products that are visually and semantically similar to the anchor product. Supported anchors: Product 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. Use cases:
  • “Similar Products” on product pages
  • “You May Also Like” recommendations
  • Visual discovery and exploration

​
Manual Strategy

Curate a specific collection with optional custom sorting. This strategy gives you complete control over which products appear in the block. Supported anchors: Collection, None Configuration:
  • Select a collection to pull products from
  • 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)
  • 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✓✗✗✗
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 number of products returned by the block. Behavior:
  • Applied after all filtering and sorting
  • Truncates results to the specified maximum
  • Applied per page (not across all pages)
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

​
Configuring Fallback Chains

Fallback chains are configured as an ordered list of block IDs. 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

​
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)
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