GET /v4/{merchant}/recommendations returns recommended products. You can also send a POST with the same fields as a JSON body.
Each request names a recommendation type, such as similar products on a product page. A type decides which inputs it reads. /context lists your store’s types under recommendation_types.
Types
- A surface’s type also answers to the surface’s name or id.
- A store with surfaces gets its surfaces instead of
similar./contextalways lists what your store has. - A store with no types has no
recommendation_typesin/context, and everytypegets404 unknown_recommendation_type.
Request
- There is one anchor per request. Send other products as
cartorrecent_views. - Recent views count newest first, by
at, and only the newest 20 count. - An input the type doesn’t read gets
400 unsupported_input, so a wrong input never silently returns the wrong products. similarneeds an anchor. A surface answers without one, from its steps that need no anchor.
%3A, a comma %2C, an @ %40, and a + in a time %2B. Encode each id on its own with encodeURIComponent, then join them with literal commas and @. Don’t pass a whole list to URLSearchParams. It encodes the commas too, so the list arrives as one id or the request fails.
How many products you get
similarreturns 20 by default.- A surface returns its own size by default, or 25 when it sets none.
limitcan lower the count but not raise it above the surface’s size. - A surface that shows Looks returns 30 by default, and never more.
checkout in this store’s setup:
Response
An id that matched no product is left out of
used_inputs. Compare used_inputs with your request to see which ids weren’t found. A product anchor that matches nothing is not an error, and similar then returns no products. A category anchor is always echoed.
How types choose products
similar
- Products are ranked by how similar they are to the anchor. Products that aren’t similar enough are left out, even if the list gets short. A short list isn’t filled with other products.
- Only products that are active, priced and sold in the request’s market, and in stock there, are returned.
- One card per product. The anchor’s product and the
excludeproducts never appear, and neither does a card that holds one of them. - The card’s selected variant is the one that matched best.
Surfaces
- A surface runs the steps set up for it, in order. When one step comes up short, the next steps fill the list.
- Your custom rules, which are pins and hides, and your Look pins apply. A surface set to show only pinned products answers from them alone. If your rules can’t be applied, some surfaces show best sellers instead.
- Products you hide from recommendations are left out.
- The anchor’s product, and other products your storefront shows as the same product, never appear. Neither do the
excludeproducts. - Products in
cartnever appear. - A surface set to avoid other surfaces leaves out the products they show.
- Out-of-stock products are left out when your setup filters them.
- You get one card per recommended colorway, so two colorways of one product can both appear. On stores whose cards hold every colorway, the card shows the recommended colorway’s sizes and lists the others in
colorways. Withinclude=variantsit adds one variant for each other colorway, not all their sizes. - A surface set to shuffle returns a different order on each request.

