Configure template: Catalog filters

Catalog filters narrow the item pool your recommendation draws from by filtering on multi-value product attributes—tags, promotional labels, regional availability, certifications, and more. Filters are set after you select your catalog and apply to every result the engine returns.

📘

Note

Catalog filters apply the same conditions to every customer. To filter results per customer or per reference item at request time, use dynamic filters instead.

To add catalog filters, go to Campaigns > Recommendations, open your recommendation, and navigate to the Design tab > Catalog.

How catalog filters work

The engine checks each item in the catalog against your filter conditions. Only items that pass enter the recommendation pool.

Use catalog filters to:

• Surface items from several active promotions simultaneously.
• Build tag-based collections using Shopify tags or custom taxonomies.
• Show only items available in specific markets.
• Restrict results to items that meet certification or regulatory standards.

Prerequisites

Before adding catalog filters:

• Your catalog must use the schema-based infrastructure, created from Data hub item collections.
• The attributes you want to filter on must be configured as searchable fields in your catalog settings.
• Your product data must include list attributes formatted as arrays—for example, ["Summer_Sale", "Clearance"]. If your attributes are stored as comma-separated strings, they need to be reformatted before catalog filters will work.

Add a filter

1. Go to Campaigns > Recommendations and open your recommendation.
2. In the Configure tab, scroll to Catalog and select your catalog.
3. Click + Add another item filter.
4. Configure the filter:
   • First dropdown—select the list attribute, for example, tags_list, promo_list, or genres_list.
   • Second dropdown—choose an operator: any item or contains all.
   • Third dropdown—choose a condition: equals or in.
   • Input field—enter the values to filter on.
5. Click Save.

Use the Preview tab to verify the filter returns the expected results before deploying.

Any item

Matches items where at least one value in the list meets your condition.

Use any item for multi-promotional campaigns, tag-based collections, genre groupings, regional targeting, and brand portfolios.

Example: promo_list any item in ["Summer_Sale", "Clearance", "New_Arrivals"]—returns all items tagged with at least one of those labels.

Contains all

Matches items only when the list contains every value you specify.

Use contains all for compliance requirements, multi-certification standards, or items that must carry a full set of specific attributes.

Example: certifications_list contains all ["ISO_9001", "CE_certified"]—returns only items with both certifications. Items with just one are excluded.

Key difference: Any item requires at least one match. Contains all requires every value you specify.

Combine conditions

You can add multiple filters to the same recommendation:

• Conditions between different attributes combine with AND—both must be true.
• Values within a single attribute combine based on the operator—any item uses OR logic, contains all uses AND logic.

Nested conditions, for example, (A AND B) OR (C AND D), aren't supported. See Limitations.

Performance and limits

These are soft limits—exceeding them won't cause errors but may increase response times, particularly during high-traffic periods.

After adding filters, check response times in the Preview tab.

Limitations

• Schema-based catalogs only: catalog filters aren't available for legacy catalogs.
• Whole-list replacement: you can't append individual items to a list attribute during ingestion. You must replace the entire list.
• Searchable fields only: only attributes configured as searchable in your catalog settings can be used as filter attributes.
• Nested conditions not supported: filter expressions don't support nested conditions like (A AND B) OR (C AND D).

Templates that support catalog filters

All templates support catalog filters except Personalized for you (Matrix-factorization model) and Personalized for you (Matrix-factorization model) (Neural). For the Combined template, filters apply to all engines in the combination.