DiscoveryService class (accessed via client.discovery) returns windowed product rankings
built from live shopper signals — the products getting the most views, the most add-to-carts, or
the highest view→purchase conversion over a time window. Use them to power a “Popular now” homepage
shelf, a “Trending in carts” section, or a PDP “hot” badge.
All three reads are publishable-key accessible (safe to call from a browser/app) and available
on every plan. Each returns product ids + a score; hydrate the product details from
Products.
Discovery is distinct from Recommendations.
Recommendations is the personalized/ML engine (secret-key, similar / bought-together / next).
Discovery is a simple, non-personalized signal ranking anyone can render on a storefront.
Methods
getMostViewedProducts
The most-viewed products over a window, ranked by view count.
score is the view count in the window. A product’s presence in getMostViewedProducts({ windowHours: 1 }) is a natural “hot right now” signal for a PDP badge.
getMostAddedToCartProducts
The most-added-to-cart products over a window, ranked by add-to-cart count — a strong
purchase-intent signal.
score is the add-to-cart count in the window.
getBestConvertingProducts
The best-converting products over a window, ranked by view→purchase ratio (units purchased ÷
product views). Surfaces high-intent “customer favorites” — products that convert, not just
products that get traffic. Products with fewer than 5 views in the window are excluded so a tiny
sample can’t top the list.
score is the view→purchase ratio; a score above 1 means more units sold than distinct views were
recorded in the window.
Parameters
Building a PDP “hot” badge
FetchgetMostViewedProducts({ windowHours: 1 }) once per page load (or cache it briefly on your
storefront), then badge any product whose product_id appears in the list — no per-product call
needed.
Response Codes
Minimum results guarantee
Every discovery list is topped up to at least 8 products (capped at thelimit you request, and
at the number of active products the store has), so a “Popular now” shelf never renders with only one
or two items. This matters most for best-converting, which excludes products with fewer than five
views and so can start out very short on a new or low-traffic store. When a list is short on genuine
signal, it is backfilled — in order — from what’s trending, what shoppers are viewing and adding to
cart, the store’s featured products, and its newest arrivals, de-duplicated against the products
already in the list.