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. Select the collection and the sort order you want to enhance.
  3. Add Pins to place specific products at the top.
  4. Add Expressions (optional) to group similar products (e.g., by brand or type).
  5. Configure Options (optional):
    • Group Related Products Sequentially - Enable to display related products next to each other (requires sequences enabled on the sort order).
    • Disable Variant Breakouts - Enable to prevent variant breakouts from being applied when this rule is active (only shown if the collection has variant breakouts configured).
  6. Configure Scheduling (optional) to automatically enable/disable the rule based on time windows.
  7. Add Contextual Conditions (optional) to target specific audiences based on location, customer data, or UTM parameters.
  8. Save, then Publish when you’re ready.

​
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
  • begins with / does not begin with - Prefix matching
  • ends with / does not end with - Suffix matching
  • 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. The system evaluates conditions using JSON Logic 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, the system uses first-match-wins evaluation. Rules are evaluated in creation order, and the first rule whose contextual conditions match is applied. 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

The system validates that contextual conditions don’t overlap to prevent multiple rules from matching the same visitor. When creating or updating a rule, the system checks if the conditions could match the same visitor as an existing rule. 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]
If your conditions overlap with an existing rule, you’ll see an error message identifying the conflicting rule by name. Update your conditions to be mutually exclusive or 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. A preview of the matching variant’s price and image is shown in the modal.
  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 a product is synced from Shopify, the platform 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. They are marked 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. Pins on draft products are protected 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.
  • Drag-and-drop is disabled while a filter is active to prevent accidental reordering.
  • Press Escape or click the clear button 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. Click Preview in the page header.
  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.
Preview requires a collection and sort order to be selected. The Preview button is disabled until both are set.
See Previewing rules for more details on how preview works and its limitations.

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