# SmartListings: Settings and Widgets Reference > Every SmartListings settings group explained, including sale source, boost types, ranking weights and the product block widget. --- This page is part of the [SmartListings guide](/docs/smartlistings). Start there for what the extension does, installation and the frequently asked questions. ## General - **What it does**: Globally enables or disables SmartListings and sets how much detail is written to the log. - **When to use it**: Disable during testing or maintenance. Leave **Logging level** on **Errors only** day to day, which is the setting that keeps `var/log/moogento_smartlistings.log` small. Choose **Info** to record per-product score breakdowns, bearing in mind it also records ranking detail on every category, search and product page view, or **Debug** for a verbose troubleshooting session. Debug adds full internal detail while capping the entries that would otherwise repeat once per product, category or row, so the log stays readable on a large catalogue. Set it back afterwards. - Config paths: `moogento_smartlistings/general/enabled`, `moogento_smartlistings/general/logging` --- ## Availability Sorting Controls how out-of-stock and low-stock products are handled on category pages. - **Show: Availability Filter** - adds an in-stock filter to the layered navigation sidebar so customers can choose to see only available items. - **Choose: Filter Display Style** - single option ("Show in-stock only") or dual options ("In Stock" / "Out of Stock"). - **Enable: Push Out-of-Stock to Bottom** - forces OOS products to score 0 so they rank below all in-stock items. When disabled, OOS products receive a neutral score and can rank normally alongside in-stock products. A product with variants counts as out of stock once every one of its variants is sold out. - **Hide: EOL (+OOS) Products** - hides products that are both end-of-life and out of stock. In-stock discontinued products still appear. - **Attribute: EOL (End-of-Life)** - which boolean product attribute marks a product as discontinued (default: `stockeasy_eol`). - **Threshold: Low Stock** - products at or below this stock level receive the low-stock penalty (default: 5). For a product with variants this is the total left across every variant that can still be sold, so 2 left in one size plus 1 in another counts as 3. - **Score: Low Stock Penalty** - how much to reduce the ranking of low-stock products (default: -10). - **Enable: Hide OOS Categories from Menu** - removes fully out-of-stock leaf categories from navigation. Parent categories with active subcategories remain visible. Config paths: `moogento_smartlistings/availability/push_oos_to_bottom`, `moogento_smartlistings/availability/stock_filter_enabled`, `moogento_smartlistings/availability/hide_oos_from_menu`, `moogento_smartlistings/availability/low_stock_threshold`, `moogento_smartlistings/availability/low_stock_penalty`, `moogento_smartlistings/availability/eol_enabled`, `moogento_smartlistings/availability/eol_attribute` **Note on third-party search engines:** On third-party search engines, the availability filter and end-of-life hiding work through a wider search window: SmartListings asks the engine for the whole category (up to 5,000 products), then applies the filter and its own ranking before building the page. Page sizes stay full, the toolbar shows the correct product count, and ranking continues across pages. Very large categories keep the search engine's own order and full pages while SmartListings prepares their scores. On Magento's built-in Elasticsearch or OpenSearch, if the search index is missing the SmartListings fields after an update, a reindex is requested automatically. You can check the index status by running `php bin/magento smartlistings:category:status --store=`. --- ## Search Results Ranking (all plans) Moves products that are in stock, and that perform better, closer to the top of the search results page. - **What it does**: When a shopper searches and keeps the default Relevance sort, SmartListings reorders the top 50 matches in groups of 10. Within each group, products with a higher SmartListings score come first. When Push Out-of-Stock to Bottom is on, in-stock products move ahead of out-of-stock products across the top 50. Results from position 51 onward keep Magento's order. - **Relevance sort only**: if the shopper picks another sort, such as price or name, the results stay in that order. - **Counts and filters**: the total product count and the filters do not change, and no products are added or removed. - **Popular searches and the page cache**: while this is on, the first page of popular searches is built for each visit instead of being served from Magento's full-page cache, so every page of a search stays consistent. - **Built-in search only**: works with Magento's Elasticsearch or OpenSearch search. - **Waits for scores**: until SmartListings has calculated product scores, search keeps Magento's order. - **How to turn it off**: go to Stores > Configuration > Moogento > SmartListings > Setup: Search Results Ranking, set Enable: Rank Search Results to No, and save. This can be set per store view. - Config path: `moogento_smartlistings/search_rerank/enabled` --- ## Behaviour-Based Merchandising (Growth or Pro; activity inserts Pro) Tracks customer activity and optionally uses it to reorder products per visitor. - **Enable: Behaviour Tracking** - records page views and purchases so SmartListings can identify which products attract the most interest. - **Customer Behaviour Tracking: Data Retention Period** - behaviour data older than this (in days) is deleted automatically (default: 90). - **Enable: Personalized Results** - reorders products per visitor based on their activity (Pro only). - **Mode: Personalization** - AJAX (browser reorder after page load) or Server-side (SQL-level reorder on cache miss). - **Weight: View Signal** - how much page views influence the per-visitor ranking score (default: 1.0). - **Weight: Purchase Signal** - how much purchases influence the per-visitor ranking score (default: 5.0). - **Wait: Re-Suggest After Purchase** - how many days to wait before suggesting a product again to the shopper who bought it (default: 45). Set to 0 to switch the wait off (Pro only). See [Stop re-suggesting a product a shopper just bought](/docs/smartlistings-setup-tasks#stop-re-suggesting-a-product-a-shopper-just-bought). - **Limit: Behaviour Boost Cap** - maximum score contribution from behaviour signals (default: 25). - **Show: Related Products From Customer Activity (Pro)** - inserts products the visitor has viewed or bought in other categories into the current category page. - **Mode: Activity Insert Placement (Pro)** - where activity-based inserts appear: top, bottom, or mixed (default: mixed). - **Density: Boosted Product Density (Pro)** - controls how many inserted products are allowed per page relative to total page size (supported: 6, 8, 10; default: 10 = up to ~3 inserts on a 30-product page). Config paths: `moogento_smartlistings/behaviour/behaviour_tracking`, `moogento_smartlistings/behaviour/behaviour_retention_days`, `moogento_smartlistings/behaviour/personalized_results`, `moogento_smartlistings/behaviour/behaviour_personalization_mode`, `moogento_smartlistings/behaviour/view_signal_weight`, `moogento_smartlistings/behaviour/purchase_signal_weight`, `moogento_smartlistings/behaviour/repurchase_interval_days`, `moogento_smartlistings/behaviour/boost_cap`, `moogento_smartlistings/behaviour/boosted_product_density` --- ## Performance Intelligence (Pro) Blends ProfitEasy sales and profit data into the ranking formula. - **Weight: Sales Velocity** - contribution of orders-per-day to the performance score (default: 0.3). - **Weight: Profit Velocity** - contribution of profit-per-day to the performance score (default: 0.4). - **Weight: Conversion Rate** - contribution of conversion rate to the performance score (default: 0.3). - **Threshold: Stale Data Days** - ProfitEasy data older than this is not used in scoring (default: 7). - **Default: Optimisation Mode** - how to weight the three signal types for new categories: Performance-First, Behaviour-First, or Balanced (default: Balanced). Config paths: `moogento_smartlistings/performance/velocity_weight`, `moogento_smartlistings/performance/profit_velocity_weight`, `moogento_smartlistings/performance/conversion_weight`, `moogento_smartlistings/performance/stale_data_days`, `moogento_smartlistings/performance/default_optimisation_mode` --- ## Analytics / Attribution (Growth+) Customises UTM parameters appended to purchase attribution data sent to ProfitEasy and **AnalyticsEasy Pro**. - **UTM: Source** - identifies SmartListings traffic in your analytics platform (default: `smartlistings`). - **UTM: Medium** - describes how traffic entered your site (default: `website`). - **UTM: Campaign** - campaign name used for all SmartListings attribution (default: `SL`). Attribution covers both category-page interactions and widget-driven purchases. When a shopper adds a product to cart from a SmartListings widget, the sale is credited using the same UTM campaign value; the widget context (carousel label, cascade stage) is stored internally in the order item for detailed analysis. Config paths: `moogento_smartlistings/analytics/utm_source`, `moogento_smartlistings/analytics/utm_medium`, `moogento_smartlistings/analytics/utm_campaign` --- ## Sale source and boost types When SmartListings influenced an order, the **Sale Source** panel on the order view (Sales > Orders > any order) shows a **How SmartListings helped** breakdown. The panel itself requires ProfitEasy on a **Pro** licence; without it, the order view shows an upgrade prompt instead of the breakdown. The **Boost type** tells you *why* each item was surfaced. The wording is plain-language; the underlying signal is one of: - **Hand-picked** - the product was manually boosted in a SmartListings Product Boost rule. You chose to promote it. - **Shopper-matched** - the product was auto-promoted from this shopper's own browsing and purchase signals (Pro personalised ranking). SmartListings matched the item to what this visitor was likely to buy - no manual boost involved. - **Hand-picked & shopper-matched** - both applied: the item sat in a boost rule *and* matched this shopper's behaviour. - **Out-of-stock recovery** - the shopper clicked the product while it was out of stock, then came back and bought it once it returned. SmartListings kept it visible instead of hiding it. - **From a storefront widget** - the item was surfaced by a SmartListings Product Block widget (related products, up-sell, new arrivals, and so on) rather than a category listing. When several items on one order were helped in different ways, the breakdown lists each type with a count. Manual boost rules and widgets are named individually, along with the products they surfaced, so you can see exactly which merchandising decision drove the sale. Each order line SmartListings helped sell also gets its own plain one-line explanation, in a table listing every line on the order with its quantity and line total, so you can see at a glance which specific items were boosted, how much they were worth, and which sold on their own. When the boost was recorded against the order as a whole rather than one specific item, SmartListings still matches the boosted product to its order line and shows it in the same table - the evidence line says it was matched by product, not recorded per line. If only some of the matched products can still be tied to a line (for example, a product was later deleted from the catalog), the table still shows the line or lines that can, and the products that can't are listed underneath as "Also matched (not on this order)" instead of disappearing. The card falls back to the boost type and matching evidence with no table when none of the matched products can be tied to a line on the order, or when more than eight products matched (the evidence list is capped, so a partial table could hide real matches). Boost types are only recorded when **attribution tracking** is enabled (Growth+). `shopper-matched` reflects Pro personalised ranking; on the Growth plan behaviour signals are captured for attribution but not used to rerank. ### What matched Under the boost type, the panel lists the products behind it and why each one qualified. For every product you see its name, its SKU, and one or more short labels naming the shopper signal that matched: - **Viewed recently** - the shopper browsed this product in the run-up to the order. - **Carted recently** - the shopper put this product in their cart in the run-up to the order. Hover or focus either label to read the same explanation in full. Where a hand-picked boost rule covered the product, the rule name appears alongside, so you can tell a manual merchandising decision from an automatic match at a glance. Long orders are summarised rather than truncated. The list shows the first eight products and then how many more there were, and does the same for a product covered by several boost rules, so a count is never quietly hidden. This detail is rebuilt when you open the order, from the order's own product list and the shopper's activity. Two things follow. Orders placed before this feature existed still show it. And once shopping history passes your **Data Retention Period**, older orders fall back to showing the boost type on its own. ### Where the widget sat When a sale came from a SmartListings Product Block widget, the breakdown adds a small label showing where on the page the widget was placed: - **Related products** - shown in the related-products slot. - **Up-sell** - shown in the up-sell slot on the product page. - **Cross-sell** - shown in the cross-sell slot in the cart. - **Category match** - pulled from a matching category when related products ran low. - **Mixed sources** - combined from related, up-sell and category sources. - **Placed widget** - a SmartListings widget placed on a CMS page or block. - **Storefront widget** - shown by a SmartListings storefront widget (used when the placement does not match one of the labels above). ### Which page it was on Manual boost rules and widgets also show which type of page the shopper was on when the boosted product surfaced: **Home page**, **Category**, **Product**, **CMS page**, or **Storefront page** (used when the page type does not match one of the others). ### Chip colours Each **Boost type** chip has its own colour, so a busy order stays easy to scan at a glance. The **Where the widget sat** chips share one colour as a family, since they are all describing the same kind of thing - a page placement - rather than different reasons a product was surfaced. The colour is a shortcut; the label text on every chip already says what it means, so nothing depends on colour alone. If the Sale Source row itself shows an amber chip reading **Swap the campaign tags**, it means the click's `utm_source` and `utm_medium` tracking parameters arrived the wrong way round for that ad. Fix this in your ad platform's tracking or final-URL settings rather than in Moogento - the same reversal also skews your analytics channel grouping, so it is worth correcting at the source. --- ## Overview: Ranking Weights A read-only visual display in config that shows how the current weights combine into the final ranking formula. The chart updates as you change weight settings in the Behaviour and Performance sections, giving you a preview before saving. Config path: `moogento_smartlistings/ranking_summary/ranking_chart` (display only) --- ## CMS Product Block Widget Per-widget controls available when adding the SmartListings Product Block widget to a CMS page or block. Configured at Content > Pages or Content > Blocks > Insert Widget > **SmartListings Product Block**, not in Stores > Configuration. **Source modes:** - **Products on special** - products with an active special price. - **New arrivals (by date added)** - recently created visible products, newest first, optionally scoped to selected categories. - **Products from selected categories** - all products from one or more chosen category IDs (use **Category IDs** to pick categories via the tree chooser). - **Manually selected products** - specific product IDs in the configured order. - **Products with active boosts** - products currently affected by SmartListings boost rules. - **Related Products (PDP cascade, sorted by SmartListings)** - cascades through up to four stages (Magento related products, upsell products, cross-sell products, category siblings) in admin-configured order and returns the first non-empty stage, sorted by composite score. Intended for product detail pages; reads the current PDP product automatically. **Conditions** (optional) - attribute rules that narrow the products from the source modes above, for example only one brand. Ignored in Related Products mode. See [Filter a widget by product attributes](/docs/smartlistings-setup-tasks#filter-a-widget-by-product-attributes). **Related Products (PDP cascade) parameters:** - **Cascade Stages** - choose which stages to include and in what order (Related, Upsell, Cross-sell, Category siblings). Unknown values are ignored; defaults to Related only if left empty. - **First Match Wins** - Yes (default) uses the first non-empty stage. No blends all stages, deduplicates by product, and marks the result as "mixed". - **Show Only When Source Product OOS** - Yes renders the widget only when the source product is not salable. Useful for suggesting alternatives on sold-out PDPs. - **Category Fallback Scope** - for the Category Siblings stage: Primary uses the deepest assigned category; Any includes all shared categories under the store root. **Display options:** - **Title** - heading rendered above the product list on the storefront. Leave empty to hide the heading. - **Subtitle** - optional secondary line displayed below the title. Leave empty to hide. - **Discounted/Special Products** - leave pricing unrestricted, show only currently discounted products, or exclude currently discounted products. Applies to category, selected product, and active-boost sources. Not applied to the Related Products (PDP cascade) source. - **Product Image Preference** - **Use Default** (inherits the system config), **Show Any Products**, **Prefer Products With Images** (with-image first, no-image at the end), or **Only Products With Images**. - **Include Out-of-Stock Products** - **Default** hides out-of-stock products and falls back to including them only when every product in the group is OOS; **Yes** always shows OOS; **No** always hides OOS even if the result is empty. Default applies to new widget instances automatically. - **Enable Personalization** - when enabled, an AJAX call re-ranks the visible products for the current shopper after the widget renders. Re-ranks the existing product set without adding new products. Requires Personalisation features enabled in SmartListings configuration (Pro). - **Allow Behaviour Inserts** - when enabled, products from the shopper's recent cross-category activity are mixed into the widget's product set. Adds new products to the visible set rather than re-ranking existing ones. Requires Cross-Category Behaviour Inserts enabled in SmartListings configuration (Pro). - **Navigation Style** - **None** (static grid), **Previous / Next**, **Carets**, or **Dots** (default for new widgets). The carousel options render a scroll-snap carousel with the selected navigation controls. - **Navigation Position** - **Below Products** (default), **Top Right**, or **Top Left**. Top positions place carousel controls beside the widget heading; on mobile they reflow below the carousel. - **Desktop Products Visible** - number of products visible across a desktop carousel row (1-8). Leave as **Automatic** (0) for responsive width-based sizing. - **Auto-Advance** - when the carousel has more than one page, it advances automatically on a timer. Enabled by default. Pauses when the visitor hovers over or focuses into the carousel, and is suppressed automatically for visitors who have reduced-motion enabled in their OS accessibility settings. - **Auto-Advance Delay (seconds)** - seconds between automatic advances. Default 5. Range 2-30. - **Show Add to Cart Button** - **Use Config** (default, follows `moogento_smartlistings/widget/show_add_to_cart`), **Yes**, or **No**. Products that require options show a "View Product" link instead of the cart button. - **Show Review Summary** - **Use Config** (default, follows `moogento_smartlistings/widget/show_reviews`), **Yes**, or **No**. Renders when Magento Review is active. - **Show Add-to-Wishlist Icon** - **Use Config** (default, follows the store's wishlist setting), **Yes** (always show), or **No** (always hide). The icon appears as a heart on each product card. - **Swap to Secondary Image on Hover** - when enabled (default), hovering a product card cross-fades to the product's secondary image if one exists. Suppressed automatically for visitors with reduced-motion preferences. Cache: widget cache lifetime is governed by Magento's block cache. When a hidden out-of-stock product returns to stock, the cached widget HTML may not refresh until TTL expires or `cache:clean` runs. --- ## Product Block Widget (defaults) Website-scope defaults for the SmartListings Product Block widget. These values are used whenever a widget instance's corresponding setting is set to **Use Config** or **Use Default**. - **Default: Product Image Preference** - image-preference mode for any widget whose per-widget parameter is **Use Default**. Options: No Image Filter (`any`), Prefer Products With Images (`prefer`, default), Only Products With Images (`only`). - **Default: Show Add to Cart on Widget Cards** - whether product cards show an Add to Cart button when the per-widget setting is **Use Config**. Yes (default) shows the button; No hides it. - **Default: Show Review Summary on Widget Cards** - whether product cards show the star rating and review count when the per-widget setting is **Use Config**. Yes (default) shows when Magento Review is active; No hides it. Changing **Default: Product Image Preference** immediately clears the widget base-set cache and invalidates block and full-page cache so all **Use Default** widget instances update without a deploy. Config paths: `moogento_smartlistings/widget/image_preference`, `moogento_smartlistings/widget/show_add_to_cart`, `moogento_smartlistings/widget/show_reviews` --- ## Other pages in this guide - [SmartListings overview, installation and FAQs](/docs/smartlistings) - [SmartListings: Category Merchandising Setup Tasks](/docs/smartlistings-setup-tasks) - [SmartListings: Tips, Ranking Health and Troubleshooting](/docs/smartlistings-tips-and-troubleshooting)