/v4/{merchant}. Making requests explains how to send parameters, markets and locales. Response contract describes the product card that several endpoints return.
browse
GET /v4/{merchant}/browse returns a search page or a listing page. Send a query for search, a listing for a listing page, or both to search within a listing.
Sections
include names the sections you want besides the cards. The sections are facets, sorts, content and listing.
- Without
includeyou getfacetsandsorts. - Naming a section replaces that default, so send
facets,sorts,listingto get all three. - Send an empty
include=for no sections. - The card extras
attributesandvariantsadd to the cards and keep the default sections.include=variantsreturns facets and sorts too.
Example
A listing page, filtered to red or blue products from 100 to 500, cheapest first:Response
Which products browse returns
browsereturns products a shopper can buy. It leaves out inactive products, products without a price, and products not sold in the request’s market.- If your store hides out-of-stock products, a product shows while any of its sizes is in stock in the market, or when it is exempt from auto-hide. On search, your search’s own hide-out-of-stock setting applies. A search inside a listing follows the listing’s stock rule. A filter on a size shows only products in stock in that size.
- Products you hide from search are left out of every request without a listing. Products you hide in a listing, or from listing pages, are left out of listing pages. A search inside a listing follows the listing’s hides, not the search hides.
- A listing holds the products assigned to it and the products its rules match. A listing with neither serves an empty page, unless it has pins or hides. Then it serves your whole catalog with those applied.
- A listing that doesn’t exist, or has no text in the locale’s language, gets
404 unknown_listing. - A listing’s pins and hides are read for the request’s market. A market without its own uses its market group’s, then your global ones. A boost or bury rule applies in the markets it names, or in every market when it names none.
- You get one card per product, as your store groups products for display. You don’t get one card per variant.
Order
This is the order when you send nosort.
- A listing page follows the listing’s merchandising. Pins keep their slots, then come boost and bury rules, then the market’s boost and bury score, then newest first.
- Search orders products by relevance to the query, using text matches and closeness in meaning. Your search boost and bury rules contribute to that score.
- Inside a listing, search rules don’t apply. Pins don’t apply to any search, even within a listing.
- A request with no query and no listing returns your whole catalog in merchandising order.
Search
Depict’s hybrid search combines keyword-based text matching with vector-based matching by meaning.- Search uses the fields and weights in your store’s Searchable fields setting in the portal.
- Text matching allows one typo per word, tried only when the exact words find nothing. Product codes get no typos.
- Product names support prefix matching, so the beginning of a word can match. Added searchable attributes use whole-word matching.
- Search uses only the first 100 characters of the query.
- Matching by meaning adds relevant products that may not contain the query’s words.
- When nothing matches, search returns no results. Your storefront shows the no-results state you configured in the portal.
- A shopper sort changes the result order. The request remains a search.
- A color word filters by color. If your store has no products in that color, search returns no results.
- A query that looks like a product code, such as an SKU or article number, also searches your product code fields, and the matching products lead the page. A hyphenated code also finds a code stored without hyphens.
- Query rules apply searchandising choices per query and are configured in the portal.
- A product added by a query rule joins the results and is ranked like the other products. It is not pinned.
- Products a rule hides stay hidden when the query is the rule’s term, in the request’s language.
Text matching
Text matches the way your catalog writes it, sot-shirt matches “T-Shirt”, and case doesn’t matter. A leading - is a space, not an exclusion.
products
GET /v4/{merchant}/products returns product cards by id, for example for a wishlist or a cart.
productsfollow the order ofids. If two ids belong to the same colorway, its card appears once, for the first id. Ids from different colorways each get a card.- For a variant id, the card shows that variant’s colorway, with that variant
selected. For a colorway’sgroup_id, the card shows that colorway, with its first variant in stock selected. - Variant ids come back in the kind you sent, so ask by SKU and you get SKUs. If one request mixes SKUs with other ids, every card uses SKUs. When every id is a group id, variant ids come back as your storefront’s ids.
missinglists the ids that have no card in this market. The product is unknown, inactive, not priced there, or has no title in the locale. It is absent when every id has a card.currencyis absent whenproductsis empty.
context
GET /v4/{merchant}/context describes your store. It takes no parameters. Call it once when your storefront builds or starts.
marketslists the markets that have a price list. Send a market’skeyasmarketon the other endpoints.localesare the locales your store can be searched in. Every market lists the same locales.default_localeis the market’s own default.recommendation_typeslists the types/recommendationstakes for your store, each with the inputs it reads. It is absent when your store has none.
recommendations
GET /v4/{merchant}/recommendations returns recommended products, such as similar products on a product page. See Recommendations.
suggest
GET /v4/{merchant}/suggest returns suggestions while the shopper types. Matching listings come first, then up to 4 popular searches. Popular searches leave out the shopper’s own query and near-duplicates.
- A listing suggestion has the listing and its
path, the titles of its parent listings from the top level down. - A query suggestion has a popular search to run.
- Your store gets listing suggestions, popular searches or both, as Depict has set it up. If one kind can’t be loaded, you get the other, not an error.
The start view
An emptyquery= returns what to show before the shopper types.
- Your pinned suggestion listings come first.
- A store with a saved start view gets its start-view phrases instead of popular searches, and there can be more than 4.
- If you turned suggested searches off for the start view, an empty query returns listings only.
listings
Two endpoints share the/listings path: your listing tree, and one listing’s header.
Breadcrumbs, quick links and tree nodes use a listing reference:
Listing tree
GET /v4/{merchant}/listings?market= returns your listings in the locale, as a tree. Use it to build menus. When a listing has no text in the request’s locale, v4 uses another locale of the same language. This holds for the tree and for the listing header.
Only categories, as a POST:
listingsholds the top-level listings. Each node is a listing reference withtypeandchildren, to any depth.- Children are sorted in the order you pinned them on the parent, then by title. Top-level listings are sorted by title.
- A listing is left out when it has no text in the locale’s language, or when
typesdoesn’t name its type. Its children are left out too. - Disabled listings are included.
Listing header
GET /v4/{merchant}/listings/{id}?market=, or GET /v4/{merchant}/listings?market=&external_id=, returns what a listing page shows around its products. Browse returns the same header with include=listing.
Breadcrumbs and quick links come ready to render. Quick links follow the order you pinned them in, then title. Parents, siblings and children without text in the locale’s language are left out.
A listing that doesn’t exist, or has no text in the locale’s language, gets
404 unknown_listing. Sending both an id and an external_id gets 400 bad_request. Disabled listings are served.
A content block:

