Shopify Product Recommendations Not Working: Diagnose Missing, Empty, or Wrong Results

For an Online Store theme, the native JSON endpoint is the cleanest dividing line. Replace YOUR_PRODUCT_ID with the numeric anchor product ID from its Shopify admin URL, open the request on the storefront domain, and preserve any locale prefix used by the storefront.

A successful empty response is useful evidence. It proves that the route, anchor, and intent were accepted, but no candidate survived for that request. A successful response containing products shifts the investigation downstream to section rendering, card projection, or tracking.

Do not use the section’s initial HTML as the same proof. Shopify documents that the recommendations Liquid object is not populated on the initial render. Theme JavaScript retrieves the populated section asynchronously, so an initially empty placeholder can be expected.

Do not begin by adding more manual recommendations. First describe exactly what the shopper sees and where. The symptom narrows the possible owner before you touch configuration.

Use a clean browser session when cart state matters. Shopify excludes products that are already in the visitor’s cart, so the same anchor can produce a different candidate set after an add.

The anchor is the product the recommendation request is about. The candidate is a product that may be returned. An invalid anchor can prevent the request from succeeding. An ineligible candidate can produce a valid but empty result.

Preserve both identities through the test. “The boot page” and “the spray” are not enough when templates, duplicated products, variants, combined listings, or market-specific offers exist. Record the product IDs and the exact storefront context.

The same heading can conceal different systems. A “You may also like” row in an Online Store theme can use the Ajax endpoint, while a headless storefront can query Storefront API and a third-party app can use neither. Identify the surface before applying a fix.

Shopify evaluates product state before a recommendation appears. Check the candidate that you expected, not only the products that survived into the module.

The inventory distinction matters. Shopify currently allows a related product with zero inventory to display when “continue selling when out of stock” is enabled. Complementary products require inventory above zero. A product can therefore appear for one intent and disappear for the other without a theme bug. These and the other candidate gates are listed in Shopify’s recommendation requirements.

A Shopify storefront can contain a native related-products section, a complementary-products block, manual Search & Discovery relationships, Shopify’s automatic related products, an Ajax or section request, and a third-party app at the same time.

Do not infer the source from the heading. Theme copy such as “You may also like” can sit above several different systems. Inspect the template code, request, or app block and record the source explicitly.

Related and complementary are not two labels for the same candidate set. Shopify generates related recommendations automatically and lets a merchant add manual related products. Complementary recommendations require manual configuration in Search & Discovery. A request using the wrong intent can therefore return a technically valid but empty set.

Manual relationships are stored in Shopify-reserved standard metafields. This matters when another app, Flow workflow, bulk editor, or migration changes the same values. The Search & Discovery screen is not a separate source of truth.

For generated related products, Shopify documents three inputs: products bought together, similar product descriptions, and related collections. Purchase history requires prior sales. Description-based recommendations are documented for English storefronts. Related collections are used when purchase-history and description recommendations are unavailable. Imported orders from another store or platform are not used by the theme recommendation algorithm.

Generated output is not a stable snapshot. Shopify says it changes frequently and can differ between Search & Discovery preview and storefront. Stores using Combined Listings also have a setting that controls whether generated recommendations show child products, parent products, or both. Before calling a result wrong, record that setting and judge the relationship, not exact preview parity.

The standard-metafield definitions document the exact keys above. Shopify’s theme recommendation guide documents the generated inputs, imported-order limitation, asynchronous rendering, and request pattern.

For a deeper explanation of candidate generation, cold start, eligibility, ranking, and set quality, use the product recommendations pillar.

Use one anchor, one expected candidate, one intent, and one storefront context through the entire procedure. If you change products halfway through, you can no longer compare the checkpoints.

Shopify’s Ajax API currently accepts a product ID, a related or complementary intent, and an optional limit from one to ten. Use locale-aware URLs. The endpoint can return product JSON or HTML rendered from a section, depending on the path. The two responses answer different questions.

Capture the request and response before reading the page. If the expected candidate is absent from the response, inspect source and eligibility. If it is present in the response and absent or wrong on the page, the failure is in rendering, filtering, caching, or card projection.

In theme code, build the request from routes.product_recommendations_url or window.Shopify.routes.root instead of hard-coding a root path. Shopify requires locale-aware Ajax URLs. The rendered section should check recommendations.performed? before it assumes the object was populated.

Shopify’s returned product URL carries pr_* query parameters used by native recommendation reports. If a custom card rebuilds the URL from the handle, it can display the right product while discarding that recommendation context. Preserve the returned URL unless you have a tested replacement measurement contract.

The same blank rectangle can be caused by a missing section, no request, an empty candidate set, or a failed insertion. These playbooks start with evidence that can distinguish those causes.

A theme repair is complete when the intended module renders on the intended templates. An eligibility repair is complete when the known candidate survives the native rules. A source repair is complete when the expected relationship appears in the response. A rendering repair is complete when response and card agree. A measurement repair is complete when the card preserves the native recommendation URL and the appropriate report can attribute the outcome.

Repeat the test on desktop and mobile, in a clean session and with the candidate in the cart when relevant. Then sample another anchor that uses the same template and intent. One passing product proves the controlled case, not the entire catalog.

Search & Discovery currently exposes recommendation click rate, purchase rate, and products with low engagement. The in-app metrics cover the last 30 days; Shopify directs other ranges to Analytics reports. Do not treat a report as a real-time request debugger. First prove the request and link, then evaluate the documented reporting window. Shopify’s recommendation-report documentation defines the available views.

If candidates are visible and technically correct but still unhelpful, the problem has moved from delivery to recommendation quality. Use the recommendation-system guide to review shopper job, candidate generation, ranking, and set constraints. If the module is in the wrong moment, use the placement guide. If the report is the weak layer, use the recommendation analytics guide.

If the diagnostic proves that the theme is rendering correctly but the native candidate set, placement controls, or evidence are too limited, ParticleSearch is a direct replacement for that recommendation job. It can serve managed recommendation shelves on product and cart surfaces from the same search-ready catalogue used by the storefront search experience.

The merchant chooses the job rather than accepting one unexplained “you may also like” list. Current strategies include similar products, frequently bought together, complete the look, cart cross-sell, trending products, best sellers, and new arrivals. The shelf can have its own title and product limit, and ParticleSearch excludes the anchor or other context products so the module does not recommend the item the shopper is already considering.

Eligibility still follows store policy. Recommendations use the eligible catalogue, respect the configured sold-out and discontinued-product behaviour, and preserve the product or variant context through the shared storefront card. ParticleSearch does not make a draft product public, repair a wrong price, or decide that two products belong together when the catalogue and observed evidence do not support that relationship.