SmartListings: Tips, Ranking Health and Troubleshooting

This page is part of the SmartListings guide. Start there for what the extension does, installation and the frequently asked questions.

#Tips & best practices

• Set the Magento default product listing sort to Position at Stores > Configuration > Moogento > SmartListings > Availability Sorting > [Magento] Default: Product Listing Sort By. SmartListings only controls ranking when the sort is Position.
• Run the Category Sort Readiness diagnostic (visible in the Availability Sorting config section) to spot categories that have a category-level sort override preventing SmartListings from taking effect.
• On Growth plan, enable behaviour tracking as soon as possible - the data accumulates over time. When you upgrade to Pro, the existing data is immediately available for ranking.
• Use time-limited boosts with expiry dates rather than indefinite boosts. Expired boosts are cleaned automatically and keep the boosts grid tidy.
• Changing the Low Stock Threshold clears the score cache and marks the catalogue search index stale on save, and rankings pick the new threshold up on the next scan. Run php bin/magento smartlistings:score:refresh AND php bin/magento indexer:reindex catalogsearch_fulltext only when you want the change to land immediately.
• Use the debug overlay (?sl_debug=1 on any category URL, Pro plan) to verify a boost is taking effect before a campaign goes live. Your admin role needs the SmartListings score-view permission or the overlay stays hidden.
• On stores with large catalogues, the score cache refreshes every 4 hours automatically. If you make a manual stock change that needs to take effect immediately, run php bin/magento smartlistings:score:refresh --category=<id>.
• When using the Related Products (PDP cascade) widget source, the cascade stages are tried in the order you configure them. Put the source with the broadest fallback coverage (usually Category siblings) last so other stages take priority when products exist.
• Widget attribution uses the same UTM campaign as category-page attribution. Check the Analytics / Attribution config group if you want to distinguish widget-driven sales from category-driven sales in ProfitEasy.

#Monitoring category ranking health

SmartListings updates category rankings in the background through Magento cron. If those updates stop, it tells you in the admin instead of leaving you to find it in the logs.

#Ranking Status on the settings page

Open Stores > Configuration > Moogento > SmartListings. The Ranking Status section at the top shows, for each store view in the scope you are viewing:

• A status: Live, Getting ready, Waiting for cron, Needs attention, Setup step needed or Off
• How many categories are ranked so far, for example "Ranking is live in 212 of 331 categories"
• When the last update ran and, while ranking is getting ready, roughly how long is left
• The last problem and where to find its details, if updates keep failing
• How many categories are paused after repeated problems, if any

This section only shows information; it has no settings to save.

#Admin alerts

Admins with access to SmartListings settings see a system message when ranking updates stall. Each alert is shown once per new problem: if you dismiss it and a different problem appears later, a new message shows.

Alerts clear on their own a few minutes after the next successful ranking run.

#Checking progress from the command line

bin/magento smartlistings:category:status <category-id> --store=<store-id>

Besides the category details, the output shows:

• Ranking scan: Off, Setup step needed, Waiting for cron, Needs attention, Getting ready or Live
• Categories ready: how many categories in the store are ranked so far
• Last run: when the ranking job last ran
• Estimated finish: roughly how long until every category is ranked, once there is enough history to tell
• Last failure: the most recent error, if any
• Ranking on storefront: whether this category is ranked yet, and if not, why (for example waiting for the scan, queued, or sorted by something other than Position)

#Troubleshooting

#Products are not sorted by stock status

Products appear in the original Magento order rather than in-stock first.

• Cause: SmartListings may be disabled, or Magento's default sort is set to something other than Position.
• Check: Verify moogento_smartlistings/general/enabled = 1. Then go to Stores > Configuration > Moogento > SmartListings > Availability Sorting and confirm the [Magento] Default: Product Listing Sort By is set to Position. Check the Category Sort Readiness report in the same section for per-category overrides.
• Resolution: Enable the module, set sort to Position, and run php bin/magento smartlistings:score:refresh followed by php bin/magento cache:clean.

#The availability filter doesn't appear in layered navigation

stock_filter_enabled = 1 but no availability filter shows in the sidebar.

• Cause: Theme layout renders filters outside sidebar.main, or on Hyvä the compat module is not enabled.
• Check: Confirm the effective store-view value of moogento_smartlistings/availability/stock_filter_enabled. On Hyvä, verify Hyva_MoogentoSmartlistings is enabled.
• Resolution: On Luma/Porto, verify the theme renders layered navigation in sidebar.main. On Hyvä, enable the compat module - it moves the filter into sidebar.main with Hyvä-native markup.

#OOS message or related collections are not showing

A fully sold-out category shows the standard Magento "no products" state rather than the SmartListings message.

• Cause: The feature is disabled, or at least one product in the category is still in-stock or salable.
• Check: Confirm moogento_smartlistings/availability/oos_message_enabled = 1 and related_collections_enabled = 1. Verify the category is truly fully out of stock - even one salable product suppresses the OOS state.
• Resolution: Enable the features in config, then verify the category has no in-stock, visible, enabled products. For Related Collections, also confirm the category has a parent with at least one active sibling.

#Boosts are not changing product positions

A boost is active but the boosted product does not appear higher in the category.

• Cause: The boost may have expired, the Magento default sort may not be Position, or the score cache has not been refreshed.
• Check: In Moogento > SmartListings > Product Boosts, confirm the boost status shows Active (not Expired or Disabled). Run php bin/magento smartlistings:score:explain <product_id> --category=<category_id> to see the boost's contribution in the score breakdown.
• Resolution: Check the boost dates, set Magento sort to Position, and run php bin/magento smartlistings:score:refresh. Manual boosts never reorder an OOS product above in-stock products when Push OOS to Bottom is enabled.

#Performance scores are not applied (Pro)

Products on a Pro plan are ordered by availability only - no performance differentiation.

• Cause: ProfitEasy is not installed, the store is not on the SmartListings Pro plan, or ProfitEasy data is older than the stale-data threshold.
• Check: Confirm the store is licensed for the SmartListings Pro plan (Stores > Configuration > Moogento > License) and that ProfitEasy is installed and enabled. Query SELECT performance_score FROM moogento_smartlistings_score_cache LIMIT 5 - all-zero values mean ProfitEasy data is not reaching the scorer.
• Resolution: Confirm the SmartListings Pro licence at Stores > Configuration > Moogento > License. Install and license ProfitEasy, run the ProfitEasy velocity cron, then run php bin/magento smartlistings:score:refresh. Increase stale_data_days if ProfitEasy data is valid but older than the threshold.

#Related Products widget shows no products on PDP

The SmartListings Product Block widget in Related Products (PDP cascade) mode renders empty on a product page.

• Cause: All cascade stages returned empty results, or the source product could not be resolved from the page context.
• Check: Confirm the product has at least one Magento related product, upsell, cross-sell, or is assigned to a category with siblings. Add Category siblings as the last cascade stage to provide a broad fallback pool.
• Resolution: Add or broaden the cascade stages in the widget configuration. If the widget is on a CMS page rather than a PDP, set Source Product ID to the product's entity ID explicitly - the widget cannot read the current product from registry outside a PDP layout.

#Malware scanner flags Helper/Moo.php

• Cause: Your host's malware scanner (often Imunify360 on cPanel hosting) heuristically flags the encoded license-check files that ship inside every paid Moogento extension. The files are genuine and unchanged - the encoding protects the license check from tampering.
• Resolution: Add the files to the scanner's ignore list so the warnings stop, and restore any file the scanner already quarantined. Both steps, plus how to verify the files are byte-for-byte what we shipped, are covered in the license file protection guide.

#Other pages in this guide

• SmartListings overview, installation and FAQs
• SmartListings: Category Merchandising Setup Tasks
• SmartListings: Settings and Widgets Reference