Skip to main content
Every path starts with /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 include you get facets and sorts.
  • Naming a section replaces that default, so send facets,sorts,listing to get all three.
  • Send an empty include= for no sections.
  • The card extras attributes and variants add to the cards and keep the default sections. include=variants returns facets and sorts too.

Example

A listing page, filtered to red or blue products from 100 to 500, cheapest first:
The same request as a POST:

Response

Which products browse returns

  • browse returns 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 no sort.
  • 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.
A sort replaces the pins and rules. On a listing page, the boost and bury score breaks its ties. 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 typed query always runs as a search. These rules follow your search settings.
  • 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, so t-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.
  • products follow the order of ids. 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’s group_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.
  • missing lists 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.
  • currency is absent when products is empty.

context

GET /v4/{merchant}/context describes your store. It takes no parameters. Call it once when your storefront builds or starts.
  • markets lists the markets that have a price list. Send a market’s key as market on the other endpoints.
  • locales are the locales your store can be searched in. Every market lists the same locales. default_locale is the market’s own default.
  • recommendation_types lists the types /recommendations takes 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 empty query= 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:
  • listings holds the top-level listings. Each node is a listing reference with type and children, 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 types doesn’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: