Principles
browse,productsandrecommendationsreturn the same product card, and take the sameincludeto add to it.- A card always has what you need to sell the product. That is its title, slug, images, price, stock, at least one variant, and each variant’s
product_id, plus the merchant attributes your store requires.imagesis[]when a product has no images. - The card is small by default. It holds what a product grid needs, and
includeadds the rest. - Ids are strings from your catalog. Numeric ids, such as Shopify’s or Centra’s, are decimal strings, never JSON numbers.
- New fields can appear. Ignore fields you don’t know, and accept new values in open enums.
Example
A rain jacket that comes in black and yellow. The card shows the black colorway with its sizes, and lists both colorways for a color picker.currencyis stated once for the whole response. Every price in it is in that currency.- The XL variant costs more than the card’s price, so it carries its own
price. The other variants don’t. - The yellow colorway is on sale and has its own title and page, so it carries its own
price,titleandslug. To show its sizes, sendinclude=variants, or askproductsforV-1001-YEL-M.
Product
Variant
Variant order
When your store shows sizes, variants are sorted by size. Letter sizes come first, from smallest to largest, then numeric and half sizes, then one size, then other size names, and last the variants without a size. Otherwise variants are sorted byproduct_id. Some stores keep their catalog’s order.
Colorway
A style card can hold several colorways of one product.colorways has one entry for each, with enough to draw a color picker.
Color
Price
A price has no currency of its own. The response’s
currency, an ISO 4217 code such as SEK, applies to every price in it. currency is absent when the response has no products.
Card extras
include adds to the card on browse, products and recommendations. Send one or both, comma-separated in a GET or as an array in a POST.
- With
include=variants, the variants are sorted across the whole card, so colorways are interleaved. Group them bygroup_id. - A recommendation surface’s card is narrower. With
include=variantsit has the recommended colorway’s sizes and one variant for each other colorway. See Surfaces. - Without
include, each variant still has your declared attributes, such as an add-to-cart id. - Both extras make the response bigger, so ask only for what the page shows.
- On
browse, card extras don’t change which sections you get.
Open and closed enums
An open enum can get new values, so handle values you don’t know. A closed enum can’t, so you can handle every value.Versioning
Every/v4 response sends the header x-depict-contract: 6.0, and so do most errors. An unexpected 500 may not.
A minor version only adds things, such as a new optional field, a new value in an open enum, a new error code or a new endpoint. Your code keeps working.
A major version may break things, such as a removed or renamed field, a new required field, a changed type or a new value in a closed enum. A major version gets a new path, /v5, and the old one keeps running alongside it.
Errors
Errors have this shape:pathpoints to the parameter or body field that is wrong, when the error is about one. Every filter error has["filter_by"].allowedlists the accepted names onunknown_filter_fieldandunknown_sort_field.- Handle codes you don’t know by their status.
A 5xx always means a problem on Depict’s side, never in your request. Quote the
request_id when you report one.
