You selected add-ons in Shopify Search & Discovery, opened the product page, and found an empty space—or no recommendation block at all. That usually does not mean Shopify’s recommendation system is broken. It means one condition between the product data, assigned template, theme block, or storefront request is preventing the products from rendering.

This checklist follows that path from the simplest merchant checks to the theme code. It focuses on complementary products: the add-ons merchants often call upsells or cross-sells.

The short answer

Check the problem in this order:

  1. Confirm that you configured complementary products, not related products.
  2. Confirm that the live product uses the template containing the complementary products block.
  3. Check that at least one selected recommendation is eligible to appear.
  4. Identify whether Shopify’s native block or an app block owns the storefront section.
  5. If the theme is custom, inspect the asynchronous recommendations request and its parameters.
  6. Test the live product on mobile and desktop with a clean cart.

This order matters. Rewriting theme JavaScript will not fix an unpublished product, and editing Search & Discovery will not fix a block added to the wrong template.

First, identify the recommendation type

Shopify distinguishes between two recommendation intents:

  • Related products are similar alternatives that Shopify can generate automatically.
  • Complementary products are add-ons intended to be bought with the current product. Merchants configure these manually in the Shopify Search & Discovery app.

The word upsell is broader than either Shopify label. Before debugging, decide which storefront behavior you expect. If you manually selected a case, cable, or refill for a main product, you are debugging complementary products.

Shopify documents the difference in its product recommendations overview.

Check the product template, not only the theme preview

A recommendation can be configured correctly while the live product uses a different template.

Open Online Store → Themes → Customize, select the relevant product template, and inspect the product information section. The template needs a complementary products block supported by the theme. Save the change, then open the product in Shopify admin and confirm that the same template is assigned to it.

This is an easy place to lose time: previewing a product inside the theme editor does not assign that template to the product. Shopify also notes that a template edit affects every product assigned to that template. Check the assignment before changing a shared layout.

The available sections and blocks depend on the theme and its version. Shopify allows only one complementary products block on a product page. See Shopify’s documentation for theme templates and complementary product recommendations.

Check every selected product for eligibility

For a complementary product to appear, Shopify requires it to meet all of these conditions:

  • its status is Active;
  • inventory is above zero;
  • it is not an Unlisted product;
  • its price is greater than zero;
  • it is not a gift card;
  • it is published to the Online Store sales channel;
  • it is not already in the visitor’s cart.

There is a particularly useful edge case here: enabling Continue selling when out of stock does not make a zero-inventory item eligible as a complementary recommendation. If every selected add-on is out of stock or otherwise ineligible, the storefront can have nothing to render.

Test with one simple product that is active, in stock, priced, and published. If that product appears, add the other recommendations back one at a time. Shopify supports up to ten manually selected complementary products.

These rules come directly from Shopify’s Search & Discovery recommendation requirements.

Confirm the source product and saved configuration

Complementary recommendations belong to a source product. Make sure you edited the same product whose storefront page you are testing, then save the configuration in Search & Discovery.

For stores with many products, Shopify also exposes standard product metafields for bulk editing recommendations. That is useful operationally, but it adds another place where the source product and recommendation list can be mismatched. Reduce the test to one known source product and one eligible add-on before investigating bulk data.

Identify whether the block belongs to the theme or an app

Many stores have both a native theme block and an app-provided upsell block. They can look similar in the theme editor while reading from different settings and data sources.

Check the block label and app attribution in the editor. If an app owns the block, Shopify’s native complementary product selections might not control it. Conversely, an app’s offer configuration does not necessarily populate Shopify’s standard complementary recommendations.

Before installing another app, answer three questions:

  1. Which block produces the visible markup?
  2. Where does that block read its recommendations?
  3. Is another hidden or empty block rendering on the same template?

Shopify describes app blocks and app embeds as part of theme app extensions. The exact settings remain app-specific.

For custom themes, inspect the storefront request

In a custom theme, recommendations are commonly loaded after the initial page render. Shopify’s Liquid recommendations object is not automatically populated on the first render; the theme requests a rendered section or JSON asynchronously.

Open the browser’s Network panel and filter for recommendations. A complementary request should use the current source product ID and explicitly request the complementary intent. The Ajax endpoint follows this shape:

/{locale}/recommendations/products.json?product_id={product-id}&intent=complementary

If intent is omitted, Shopify defaults to related recommendations. A section-rendering request also needs the correct section_id. Shopify documents invalid parameters as a 422 response and an unpublished source product as 404.

Check the response before editing the layout:

  • If the response contains no products, return to product eligibility and configuration.
  • If the response contains products but the page stays empty, inspect JavaScript errors, stale selectors, section replacement logic, and CSS visibility.
  • If the request uses the wrong product ID or recommendation intent, fix the request construction.
  • If no request is made, inspect the block’s initialization and theme editor section lifecycle.

Use Shopify’s Ajax Product Recommendations API reference and complementary products theme guide as the implementation contract. Keep the product URLs returned by Shopify rather than rebuilding them, because Shopify uses their recommendation parameters for attribution.

Verify the live storefront on mobile and desktop

Do not stop at the theme editor preview. Test the published theme and exact product URL in a fresh session.

  • Confirm that the live product has the expected template.
  • Start with an empty cart, because a recommended item already in the cart is excluded.
  • Test a desktop and a mobile viewport.
  • Inspect whether a slider, collapsed panel, or breakpoint rule hides an otherwise populated block.
  • Add the recommended item to the cart and confirm that its disappearance is expected rather than a new failure.

If the change exists only in an unpublished theme copy, it will not affect the live storefront until that theme is published or the same change is applied to the live theme.

A ten-minute diagnostic sequence

For a small store, this sequence usually isolates the failing layer quickly:

  1. Choose one live source product.
  2. Assign one active, in-stock, priced, Online Store-published add-on.
  3. Confirm the source product’s assigned template.
  4. Confirm that the template has one visible complementary products block.
  5. Open the live URL with an empty cart.
  6. Check the recommendations network response.
  7. If data returns, inspect the block’s JavaScript and CSS.
  8. If no data returns, recheck catalog eligibility and recommendation configuration.

The important result is not merely that the section is missing. It is knowing whether the failure is in configuration, eligibility, request, or rendering.

Measure the block only after it renders reliably

Once recommendations appear consistently, use Search & Discovery analytics to evaluate recommendation click rate, purchase rate, and low-engagement products. Shopify’s recommendation reports use the last 30 days of data, so they are more useful for improving a stable block than diagnosing one that never renders.

See Shopify’s guide to Search & Discovery analytics.

When custom development is justified

Theme work is reasonable when the current theme lacks a compatible block, the store needs a layout that the native block cannot provide, or custom JavaScript does not follow Shopify’s recommendation request contract. It can also make sense to consolidate duplicate native and app implementations so the merchant has one clear place to manage recommendations.

Keep the fix proportional. A product eligibility problem needs a catalog correction. A wrong template needs an assignment change. Only a broken render path needs code.

Need help fixing product recommendations in your Shopify theme? Send us the affected product URL, theme name, and whether the block is native or app-powered. We can trace the render path and fix the smallest part that is actually blocking the recommendation.