Rules & safeguards

Block rules

Rules let you change block behavior based on the anchor product or request context. Layers evaluates rules on every block request, in order, and applies every matching rule. It stops evaluating only after a matching action hides the block. Rules never change which block is served. Layers always selects the highest-priority block for the anchor, then matching rules adjust that block’s effective configuration. A block whose rule conditions don’t match keeps its base configuration.

Rule shape

Each rule contains one set of conditions and one action. The conditions.combinator joins the condition rules with and or or. Each condition names a field, an operator, and a value. The action is an object with a type and optional action-specific fields. Its type is one of apply_filter, promote, demote, hide_block, change_strategy, or override_safeguards.

{
  "conditions": {
    "combinator": "and",
    "rules": [
      {
        "field": "anchor_product.vendor",
        "operator": "=",
        "value": "Acme"
      }
    ]
  },
  "action": {
    "type": "apply_filter",
    "filter_group": {}
  }
}

apply_filter, promote, and demote accept a filter_group. change_strategy accepts strategy_type and strategy_key. override_safeguards accepts safeguards. hide_block has no additional fields. The filter_group uses the storefront filter expression vocabulary. See the filter group reference for its shape. The conditions object uses the field vocabulary below.

Field vocabulary

The supported filter operators are eq, neq, in, notIn, gt, gte, lt, lte, contains, doesNotContain, beginsWith, endsWith, doesNotBeginWith, doesNotEndWith, null, notNull, between, notBetween, inLast, after, before, geoRadius, geoPolygon, and geoBoundingBox. In block conditions, the editor also supports the symbolic aliases = and != for equality and inequality, plus in and notIn for shopping channel values.

Field	Label	Type	Operators	Values
`anchor_product.product_type`	Anchor Product: Type	string	All filter operators
`anchor_product.vendor`	Anchor Product: Vendor	string	All filter operators
`anchor_product.tags`	Anchor Product: Tags	array	All filter operators
`anchor_product.price`	Anchor Product: Price	integer	All filter operators
`anchor_product.collections`	Anchor Product: Collections	array	All filter operators
`context.shoppingChannel`	Shopping Channel	string	`=`, `!=`, `in`, `notIn`	`web`, `app`
`context.marketing.source`	Marketing Source	string	All filter operators
`context.marketing.medium`	Marketing Medium	string	All filter operators
`context.marketing.campaign`	Marketing Campaign	string	All filter operators
`context.marketing.term`	Marketing Term	string	All filter operators
`context.marketing.content`	Marketing Content	string	All filter operators
`context.marketing.clickSource`	Marketing Click Source	string	All filter operators
`context.customer.signedIn`	Customer Signed In	boolean	All filter operators
`context.customer.returning`	Returning Customer	boolean	All filter operators
`context.customer.numberOfOrders`	Customer Order Count	integer	All filter operators
`context.customer.tags`	Customer Tags	array	All filter operators
`context.customer.averageOrderValue`	Customer Average Order Value	integer	All filter operators
`context.customer.daysBetweenOrders`	Average Days Between Orders	integer	All filter operators
`context.customer.daysSinceLastOrder`	Days Since Last Order	integer	All filter operators
`context.customer.daysSinceOldestOrder`	Days Since Oldest Order	integer	All filter operators
`context.customer.totalSpent`	Customer Total Spent	integer	All filter operators
`context.geo.city`	City	string	All filter operators
`context.geo.province`	Province	string	All filter operators
`context.geo.country`	Country	string	All filter operators
`context.market.id`	Market	string	All filter operators
`context.market.countries`	Market Countries	array	All filter operators
`context.catalog.isB2b`	B2B Catalog	boolean	All filter operators
`context.catalog.id`	Catalog	string	All filter operators
`context.custom.rivo.status`	Rivo Status	string	All filter operators
`context.custom.rivo.pointsBalance`	Rivo Points Balance	integer	All filter operators
`context.custom.rivo.creditsBalance`	Rivo Credits Balance	integer	All filter operators
`context.custom.rivo.vipTier`	Rivo VIP Tier	string	All filter operators

Custom context parameters your storefront sends in context.custom also join the vocabulary as context.custom.<path> fields once Layers discovers them in traffic. If a discovered parameter shares a name with a shipped field listed above, the shipped field wins. See Custom context fields for discovery requirements. For list fields such as anchor_product.tags and anchor_product.collections, the = operator matches when the list contains the value. anchor_product.tags = sale matches any anchor product tagged sale. anchor_product.collections contains both collection IDs and collection handles, so a condition can reference either.

Examples

Apply a vendor filter when the anchor product comes from Acme:

{
  "conditions": {
    "combinator": "and",
    "rules": [
      {
        "field": "anchor_product.vendor",
        "operator": "=",
        "value": "Acme"
      }
    ]
  },
  "action": {
    "type": "apply_filter",
    "filter_group": {
      "conditional": "AND",
      "expressions": [
        {
          "property": "vendor",
          "operator": "eq",
          "values": [
            "Acme"
          ]
        }
      ]
    }
  }
}

Apply the on_sale catalog filter when the anchor product is a Catalog product:

{
  "conditions": {
    "combinator": "and",
    "rules": [
      {
        "field": "anchor_product.product_type",
        "operator": "=",
        "value": "Catalog"
      }
    ]
  },
  "action": {
    "type": "apply_filter",
    "filter_group": {
      "conditional": "AND",
      "expressions": [
        {
          "property": "on_sale",
          "operator": "eq",
          "values": [
            true
          ]
        }
      ]
    }
  }
}

Rank on-sale products first when the anchor product is tagged sale:

{
  "conditions": {
    "combinator": "and",
    "rules": [
      {
        "field": "anchor_product.tags",
        "operator": "=",
        "value": "sale"
      }
    ]
  },
  "action": {
    "type": "promote",
    "filter_group": {
      "conditional": "AND",
      "expressions": [
        {
          "property": "on_sale",
          "operator": "eq",
          "values": [
            true
          ]
        }
      ]
    }
  }
}

Hide the block for app requests:

{
  "conditions": {
    "combinator": "and",
    "rules": [
      {
        "field": "context.shoppingChannel",
        "operator": "=",
        "value": "app"
      }
    ]
  },
  "action": {
    "type": "hide_block"
  }
}

Allow up to 12 products for VIP customers:

{
  "conditions": {
    "combinator": "and",
    "rules": [
      {
        "field": "context.customer.tags",
        "operator": "in",
        "value": [
          "vip"
        ]
      }
    ]
  },
  "action": {
    "type": "override_safeguards",
    "safeguards": {
      "maximum_products": 12
    }
  }
}

Rule actions

Apply Filter

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)

Promote / Demote matching products

Re-rank the block’s results without changing which products are returned. Each matching promote or demote rule adds a ranking tier defined by its filter_group. Products matching a promote tier rank first. Products matching a demote tier rank last. Everything else keeps its normal order in between.Tiers are ranking-only. They never filter products out, and pagination stays stable across pages. Diversity caps, spacing, and sequential sorting still apply within each tier.Use cases:

Rank same-vendor products first on a “You may also like” block
Push clearance items to the end of a recommendation rail
Surface on-sale products first during a promotion

Hide Block

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 for app requests
Hide blocks for specific geographic regions

Change Strategy

Switch to a different strategy when conditions are met. The new strategy must return the same result type as the block: a rule can’t switch a product block to the related content strategy, or a content block to a product strategy.Use cases:

Use “Similar Products” for app requests instead of “Frequently Bought Together”
Switch to different interaction strategies based on customer segment
Use different strategies for different product types

Override Safeguards

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 for returning customers
Enable or disable out-of-stock filtering for specific customer segments

Multiple rules

You can configure multiple rules for a single block. Layers evaluates them in order and applies each matching action until a hide action stops evaluation. Put broad conditions after more specific conditions.

Safeguards

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

Product safeguards don’t apply to content blocks. A block using the related content strategy can’t configure hide out of stock or the diversity cap.

Hide out of stock

Automatically filter out products that are not available for purchase. Behavior:

Products with no available variants are excluded from results
If your store’s inventory location scope is narrowed, blocks apply the same location rules as search. A variant counts as available if it meets any of these conditions:
- It has stock at a location in the scope
- Shopify is set to keep selling it when out of stock
- Its inventory is untracked
A product is hidden only when none of its variants meet any of these conditions
Applies after strategy execution but before pagination
Can be overridden by rules

Disable variant breakouts

Stop variant breakouts from expanding this block’s results into variant tiles, even when a breakout otherwise targets blocks. Behavior:

When on, the block always returns standard product tiles and skips variant breakout expansion for its results
Applies to all block strategies
Has no effect if no variant breakout is targeting blocks for the products in scope

Configuration:

Toggle Disable Variant Breakouts on in the block’s Safeguards section
Disabled by default. Blocks receive variant tiles when a variant breakout has Target blocks enabled

Use cases:

Keep a “Frequently bought together” block at the product level while variant tiles appear elsewhere on the storefront
Prevent duplicate-looking recommendations when a block anchor already represents a specific variant
Preserve a fixed number of distinct products in a compact recommendation slot

Exclude family members

Hide other products that belong to the same product family as the block’s anchor product. This prevents a block from surfacing near-duplicates of the product a shopper is already looking at. Behavior:

Applies to all block strategies with a resolvable anchor product, including product-anchored blocks and collection-anchored similar-products blocks, where the collection resolves to a representative product
Products sharing the anchor’s canonical family are removed from results before pagination
Has no effect on products that aren’t assigned to a family

Use cases:

Hide other color variations of the anchor on a “You may also like” block
Prevent a “Similar products” block from returning the same style in a different fabric
Keep cross-sell recommendations distinct from the current product

Family exclusion requires configured product families. Products with no family assignment are unaffected by this safeguard.

Exclude purchased products

Hide products the shopper has already purchased. This keeps recommendation rails focused on products the shopper doesn’t own yet. Behavior:

Every product in the shopper’s purchase history is added to the block’s exclusion set, alongside any family exclusions
Purchase history comes from the productsPurchased array in the request’s contextual information
Applies before pagination, so page counts reflect the excluded products
Has no effect when the request includes no purchase history

Configuration:

Toggle Hide products this shopper has already purchased on in the block’s Safeguards section
Disabled by default

Use cases:

Keep “You may also like” rails free of products the shopper already owns
Avoid recommending one-time purchases the shopper has completed
Focus cross-sell blocks on net-new products for returning customers

This safeguard requires purchase history in the API request’s context. Without it, results are unchanged. For replenishable products, use the Replenish strategy instead, which intentionally resurfaces past purchases.

Diversity cap

Limit how many products from the same family appear near the top of the block so the first results stay varied. When enabled, the block applies a per-family cap to its top window, similar to diversity expressions in sort orders. Behavior:

Available on all block strategies: interaction, similar products, manual (ids and collection), trending, and contextual
Enforces the cap only within the top window of the block’s results; beyond the window, natural ordering resumes
Layers on top of the block’s base ranking and never overrides a merchant-configured diversity rule already present in the underlying sort order
Has no effect on products that aren’t assigned to a family

Configuration:

Toggle Diversity Cap on in the block’s Safeguards section
The cap is opt-in and disabled by default

Use cases:

Prevent an interaction block from returning six variants of the same best-selling style at the top
Keep a “Trending now” block visually varied when a single family dominates recent activity
Ensure a collection-anchored similar-products block surfaces multiple distinct styles

Diversity requires configured product families. See Diversity expressions for a deeper explanation of how the top-window cap works.

Minimum products

If the block returns fewer than the minimum number of products, the fallback chain is used instead. The fallback mode decides whether the fallback replaces the primary results or tops them up. See Fallback Chains. 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

Overview

Core Concepts

Merchandising

Search & Discovery

Catalog & Data

LayersQL

Shopify Integration

Legal

Rules & safeguards

Block rules

Rule shape

Field vocabulary

Examples

Rule actions

Multiple rules

Safeguards

Hide out of stock

Disable variant breakouts

Exclude family members

Exclude purchased products

Diversity cap

Minimum products

Maximum products

See also

​Block rules

​Rule shape

​Field vocabulary

​Examples

​Rule actions

​Multiple rules

​Safeguards

​Hide out of stock

​Disable variant breakouts

​Exclude family members

​Exclude purchased products

​Diversity cap

​Minimum products

​Maximum products

​See also

Block rules

Rule shape

Field vocabulary

Examples

Rule actions

Multiple rules

Safeguards

Hide out of stock

Disable variant breakouts

Exclude family members

Exclude purchased products

Diversity cap

Minimum products

Maximum products

See also