QSortby Guide
Settings

Storefront data — related products for your theme

Two ways to get each product's related lists into your own theme: a JSON API your theme's JavaScript calls, and metafields written onto every product for Liquid. Bought, added and viewed together, similar, and goes-with.

Last updated · Nov 7, 2026

QSortby’s own blocks render related products for you. Settings → Storefront data is for the other case: your theme draws its own “Complete the look” section, or a developer wants the lists in their own markup. Two switches, both on Pro and Growth, both off until you turn them on.

The five lists

Both features serve the same five lists a product page shows under What it travels with:

ListWhat it isAt most
Bought togetherBought in the same order — things shoppers take as wellEvery pair
Added togetherIn the same cart, whether or not that cart was boughtEvery pair
Viewed togetherOpened in the same visit — alternatives, not add-ons; shoppers chose between themEvery pair
SimilarMost alike in your catalogue, worked out from your products rather than from what shoppers did20, refreshed nightly
Goes withYour own Goes-with rules, exactly as the Goes-with block shows them50

A pair seen only once is not published — the same floor the widgets use — and products that cannot be rendered (draft, unpublished, no handle) are removed before the list is counted.

The storefront data API

Publish related-product lists to my storefront lets your theme’s own JavaScript fetch any of the five lists for one product, as JSON, paginated:

window.fetch('/apps/qsortby/v1/related?product_id=' + productId + '&type=bought&pageSize=4')
  .then((r) => (r.ok ? r.json() : null))
  .then((data) => {
    if (!data) return
    // data.products: [{ id, handle, title, imageUrl, available }]
    // data.page, data.pageSize, data.totalCount, data.totalPages
  })

type is bought, added, viewed, similar or goes_with. Price is not included — read /products/<handle>.js, which Shopify serves in the shopper’s own currency. /apps/qsortby is the App Proxy path; if you have renamed it in Shopify, the card shows yours.

The answer carries a reason when a list is empty: no_data (nothing observed yet), not_built_yet (similar, before the first nightly pass), not_in_plan (goes-with, when Goes-with publishing is off), unknown_product. With the switch off, or on a plan without the feature, every call answers 403 before anything else — your theme should treat that as “render nothing”, the way QSortby’s own blocks do.

Write related products to my product metafields writes each product’s top 10 of every list onto the product itself, so your theme can show them from Liquid without calling anything:

qsortby.related_bought · qsortby.related_added · qsortby.related_viewed · qsortby.related_similar · qsortby.related_goes_with

A check runs every n minutes — you set n, from 5 minutes to once a day — and writes to Shopify only what changed. A check that finds nothing new writes nothing. The status line says where it is: On — the first check starts within a minute, then the time of the last check and how many values it wrote. The card tells you the cost in Shopify writes before you switch it on; a large catalogue’s first run takes a while and is paced to Shopify’s rate limit.

Which one to use

  • Metafields when the theme renders in Liquid and ten per list is enough. Nothing to call, nothing to fail at request time.
  • The API when you need more than ten, pagination, or a list chosen at runtime — a tab strip that switches between bought together and similar, say.

Both can be on at once; they read the same data.

Menus are tucked away for bigger images — hover the edges to peek them, or Focus to pin. Click any image to zoom.

Popular

Set up QSortby — two steps Getting started Auto-sort a collection Auto-sort Create a personalization rule Personalization Upsell offers — the six touch points Upsell Troubleshooting Help
↑↓ to navigate ↵ to open esc to close