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.

Fallback chains ensure customers always see recommendations, even when the primary block doesn’t return enough products. You can configure either a simple chain (a single ordered list) or a fallback tree that selects a different chain based on visitor context.

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

A fallback tree lets a single block deliver different fallback chains to different visitors. Instead of one ordered list, you define multiple branches, each with its own set of conditions and its own fallback chain. At request time, the platform evaluates each branch in order and uses the chain from the first branch whose conditions match the visitor’s context. This is useful when you want fallbacks to vary by audience without creating multiple parallel blocks. For example, you might fall back to a “Best Sellers — US” block for shoppers in the United States and a “Best Sellers — EU” block for shoppers in Europe.

​
How tree evaluation works

  1. Branches are evaluated in the order they appear in the Fallback tree builder
  2. The first branch with matching conditions wins — later branches are not evaluated
  3. A branch with no conditions matches everyone, so it acts as the default. Place it last
  4. The chain inside the matched branch is then evaluated like a normal fallback chain (in order, respecting Replace and Fill modes)
  5. If no branch matches and there is no default branch, the block returns no fallback results

​
Branch conditions

Each branch can target visitors by the same contextual fields used elsewhere on a block — geographic location, customer tags, device type, marketing source, and product attributes when the block has an anchor product. Conditions are combined with AND or OR combinators inside the branch. Conditions are evaluated against the same context object the request was made with, so calls to the Blocks API must pass context and identity fields for branch matching to work. Without context, only the default branch (if any) will match.

​
Configuring a fallback tree

In the block editor, switch the fallback configuration to Tree mode and add branches. For each branch:
  1. Define the conditions that select this branch (or leave empty to make it the default branch)
  2. Build the fallback chain for that branch as an ordered list of blocks, each set to Replace or Fill mode
  3. Drag branches to reorder them — the first matching branch wins
Existing blocks that use a flat fallback chain are migrated automatically to a tree with a single default branch. No action is required, and the runtime behavior is unchanged.

​
Example: geographic fallback tree

Branch 1 — Conditions: geo.country IS "US"
  Fallback 1 (replace): "Best Sellers — US"
  Fallback 2 (replace): "Trending in US"

Branch 2 — Conditions: geo.country IN ["GB", "DE", "FR"]
  Fallback 1 (replace): "Best Sellers — EU"

Branch 3 — Conditions: (none, default)
  Fallback 1 (replace): "Global Best Sellers"
A US shopper falls back to US-specific blocks, EU shoppers fall back to a regional block, and everyone else gets the global default.

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

​
See also