Skip to main content

​
Before you start

  • You can create multiple rules for the same collection + sort order combination using contextual conditions.
  • Rules can’t target the “all” collection.

​
Steps

  1. Go to Merchandise and click Create.
  2. Enter a name for the rule in the page header — click the title text to edit it inline.
  3. In the right sidebar, use the Settings tab to select the collection and sort order you want to enhance.
  4. Add Pins to place specific products at the top by dragging them in the product grid.
  5. Use the sidebar tabs to configure additional options:
    • Settings — Select collection, sort order, and toggle options like Group Related Products Sequentially or Disable Variant Breakouts. When you select a sort order that has sequences enabled, Group Related Products Sequentially turns on automatically.
    • Expressions — Add rules to automatically group similar products (e.g., by brand or type).
    • Scheduling — Set start and end dates to automatically enable or disable the rule.
    • Conditions — Target specific audiences based on location, customer data, or UTM parameters.
  6. Click Save Changes to save your work as a draft.
  7. Click Publish when you’re ready to make the rule live.

​
Expression operators

When building expressions, you can use various operators depending on the attribute type: Text operators:
  • equals / does not equal - Exact match
  • contains / does not contain - Partial text matching (case-insensitive)
  • begins with / does not begin with - Prefix matching (case-insensitive)
  • ends with / does not end with - Suffix matching (case-insensitive)
  • in / not in - Match any value in a list (enables multi-select)
  • is null / is not null - Check if attribute has a value (hides value field)
Numeric operators:
  • equals / does not equal - Exact numeric match
  • greater than / greater than or equal - Value comparisons
  • less than / less than or equal - Value comparisons
  • between / not between - Range matching (requires two values)
  • in / not in - Match any value in a list (enables multi-select)
  • is null / is not null - Check if attribute has a value (hides value field)
Date operators:
  • equals / does not equal - Exact date match
  • after / before - Date comparisons
  • between / not between - Date range matching (requires two values)
  • is null / is not null - Check if attribute has a value (hides value field)
Tag operators:
  • contains / does not contain - Check if tag exists
  • in / not in - Match any tag in a list (enables multi-select)

​
Using null operators

The is null and is not null operators check whether an attribute has been set. When you select these operators, the value field is automatically hidden since no comparison value is needed. Example use cases:
  • vendor is not null - Only show products with a vendor assigned
  • compare_at_price is null - Show products not on sale
  • tags is null - Show untagged products

​
Using multi-select operators

When you select in or not in operators, the UI automatically enables multi-select, allowing you to match products against multiple values in a single expression. Example:
  • vendor in [Nike, Adidas, Puma] - Show products from any of these brands
  • tags in [featured, bestseller, new-arrival] - Show products with any of these tags

​
Scheduling

Set a start date and time to automatically enable the rule at a specific moment. Optionally set an end date and time to automatically disable it. A background job runs every minute to evaluate schedules and update rule status. Use cases:
  • Flash sales that start and end at specific times
  • Seasonal campaigns scheduled weeks in advance
  • Product launch merchandising that goes live at release time

​
Contextual conditions

Define conditions based on visitor context to control when the rule applies. Layers evaluates conditions using JSON Logic (a rule format for expressing conditions) against session data including:
  • Geographic data (country, state, city)
  • Customer attributes (tags, account status)
  • UTM parameters (source, medium, campaign)
  • Device information (device type, OS)
Use cases:
  • Show different merchandising to US vs. UK visitors
  • Target mobile users with mobile-optimized product ordering
  • Display campaign-specific merchandising for visitors from specific marketing channels

​
Multiple rules for the same collection

When you create multiple rules for the same collection/sort combination, Layers uses first-match-wins evaluation. Layers evaluates rules in creation order and applies the first rule whose contextual conditions match. Example: 
Rule 1: US visitors → US-specific merchandising
Rule 2: UK visitors → UK-specific merchandising
Rule 3: No conditions → Default merchandising
Create rules in priority order. Rules without contextual conditions always match and should be created last as fallback rules.

​
Overlap detection

Layers validates that contextual conditions don’t overlap to prevent multiple rules from matching the same visitor. Real-time warnings — As you edit conditions in the sidebar, Layers checks for overlaps automatically. If Layers finds a conflict, a warning toast appears with the name of the conflicting rule and a View rule link to navigate to it. This lets you resolve conflicts before saving. Save-time validation — When you save, Layers performs a final overlap check and blocks the save if conditions still overlap. Allowed (non-overlapping):
  • country == US and country == CA
  • source == klaviyo and source == google
  • country in [US, CA] and country in [UK, DE]
Blocked (overlapping):
  • country == US and country == US
  • country in [US, CA] and country in [CA, UK]
  • country == US and country in [US, CA]
  • country == United States and country contains United
Update your conditions to be mutually exclusive or click View rule to edit the existing rule.

​
Disable variant breakouts

If your collection has variant breakouts configured, you’ll see a Disable Variant Breakouts toggle in the Options tab. When enabled, this prevents variant breakouts from being applied to the collection while this rule is active. When to use this:
  • You want to show products as single tiles during a promotional campaign for cleaner presentation
  • You’re targeting specific audiences who should see products instead of individual variants
  • You want to temporarily disable variant breakouts during scheduled events without changing your global configuration
The option only appears when the target collection has variant breakouts configured. See Variant Breakouts for more information.

​
Default variant for pins

You can set a default variant for any pinned product to control which variant’s price and image appear on the collection page tile. This is useful when you want to feature a specific color, size, or other option for a promoted product.
  1. After pinning a product, click the variant button on the pinned product card.
  2. In the modal, select the option values you want to feature (for example, “Color: Red”).
  3. The modal shows a preview of the matching variant’s price and image.
  4. Click Save to apply the default variant to the pin.
To remove a default variant, open the modal again and clear the selections.
Default variant options only affect which variant data is displayed on the tile. They do not filter out other variants — customers can still select any variant on the product page. See default variant for pins for more details.
You can override the image shown on a pinned product’s collection tile. This lets you feature a specific photo instead of the product’s default image.
  1. After pinning a product, click the featured media button on the pinned product card.
  2. In the modal, browse all available media for that product — product images, variant images, and metafield images are all shown.
  3. Select the image you want to feature on the collection page.
  4. Click Save to apply the override.
To remove a featured media override, open the modal again and clear the selection. The override applies in storefront search and browse results. When Layers syncs a product from Shopify, it automatically clears any override whose image no longer exists on the product.
Featured media overrides are separate from default variant selection. You can use both on the same pin — the default variant controls pricing and option display, while the featured media override controls which image appears on the tile. See featured media override for pins for more details.

​
Working with draft products

Draft products that belong to the selected collection appear in the merchandising grid alongside published products. Layers marks them with an orange Draft badge. You can pin, swap, and reorder draft products the same way you would any published product. When you search for products in the swap popover, draft products are included in the results. Layers protects pins on draft products from automatic cleanup — they remain in place until the product is published and becomes visible to shoppers.
Draft products are only visible in the merchandising UI. They do not appear in customer-facing search or browse results until they are published in Shopify.

​
Filtering products

Use the search bar in the toolbar to filter the product grid while you work. Type a keyword to narrow results by title, handle, vendor, product type, tags, variant title, SKU, or configured attributes.
  • Pinned products always remain visible regardless of the search term.
  • Layers disables drag-and-drop while a filter is active to prevent accidental reordering.
  • Click the clear button or use the Escape key to reset the filter.
This is especially helpful in large collections where you need to locate a specific product to pin.

​
Previewing before you save

You can preview your merchandising rule on the live storefront before saving.
  1. Set up your collection, sort order, pins, and expressions.
  2. Open the overflow menu (three-dot icon) in the page header and click Preview.
  3. A new browser tab opens showing your storefront collection page with the preview applied.
  4. Review the product order and layout, then return to the dashboard to make adjustments or save.
Preview captures your current unsaved form state. You don’t need to save first, and the preview has no effect on live traffic. Preview links expire after one hour.
You must select a collection and sort order before previewing. The Preview button stays inactive until you set both.
See Previewing rules for more details on how preview works and its limitations.

​
Dashboard layout

The merchandising editor uses a two-panel layout. The product grid occupies the main area on the left, and a persistent sidebar on the right contains all rule settings organized into four tabs:
  • Settings — Collection, sort order, rule name, and option toggles.
  • Expressions — Auto-pin expressions for grouping products by attribute.
  • Scheduling — Start and end date/time for automatic activation.
  • Conditions — Contextual targeting rules based on visitor data.
Switch between tabs using the icon buttons at the top of the sidebar. Each tab’s icon shows a tooltip on hover to identify it. The Expressions and Conditions tabs display a count badge when rules or conditions are configured. This lets you see at a glance whether a tab has active content.

​
Inline metrics and inventory

Product cards in the merchandising grid display metric values and inventory data directly, so you can evaluate product performance while arranging your collection.

​
Viewing metrics on product cards

Each product card shows the metrics you’ve configured in your grid settings. Click the Metrics heading on any card to expand or collapse the metric values. Click the Inventory heading to toggle stock level details. Metric values update based on the loaded data for each metric. If a metric has no data for a particular product, that metric row is omitted from the card.

​
Configuring which metrics appear

  1. Click Customize UI in the merchandising toolbar.
  2. In the settings panel, scroll to the metrics section.
  3. Select the metrics you want to display on product cards.
  4. Drag and drop metrics to reorder how they appear on each card.
  5. Close the panel — your selections save automatically and persist across sessions.
Only metrics that produce per-product values appear in the selection list. This includes all imported (ShopifyQL) metrics and LayersQL metrics that target the products dataset with a single aggregated value grouped by product. See Metrics in merchandising rules for full eligibility details.

​
When to use inline metrics

  • Pinning decisions — Check sales velocity or conversion data before pinning a product to the top of a collection.
  • Comparing products — Scan metric values across the grid to identify underperformers that should be moved down.
  • Validating expressions — After setting up auto-pin expressions, review metric values to confirm the grouping surfaces your best products.

​
Customizing the grid

Click Customize UI in the toolbar to open a settings panel where you can adjust:
  • Grid columns — Number of columns in the product grid (1–8).
  • Image ratio — Aspect ratio for product images, including a custom option.
  • Card settings — Toggle product title and price visibility, and configure which attributes and metrics appear on product cards.
Drag and drop attributes or metrics in the panel to reorder them on the cards.

​
Tips

  • Use Pins for must-see items; use Expressions to organize the rest.
  • Combine scheduling with contextual conditions for powerful targeting (e.g., Black Friday rule only for US visitors).
  • Create a fallback rule without conditions to ensure all visitors see merchandising.
  • Use the Disable Variant Breakouts option to temporarily override variant breakout behavior for specific campaigns or contexts.
  • Pin draft products before launch day so your merchandising is ready the moment a product goes live.
  • Use the product filter to quickly find items by name, SKU, or vendor in large collections.