Listings - Depict Documentation

The Platform API currently has two active versions. Build new integrations against the /v3 endpoints — /v3 is the successor to /v2. /v2 is expected to be deprecated within roughly 6 months and /v3 within roughly 9 months, with a v4 API expected in Q4. These are expectations, not committed dates — confirm timelines with your Depict contact before planning a migration deadline.

Listings are category, collection and campaign pages. The Platform API splits a listing page across two calls: a GET for the listing’s metadata (title, breadcrumbs, subcategories, content cards) and a POST for its products.

Endpoint	Method	Purpose
`/v3/listings`	GET	The full listing tree — build navigation menus from one call
`/v3/listings/{listing_id}`	GET	Metadata for one listing, addressed by Depict id
`/v3/listings/external_id/{external_id}`	GET	Metadata for one listing, addressed by your own id
`/v3/listings/{listing_id}/products`	POST	Products in a listing, addressed by Depict id
`/v3/listings/external_id/{external_id}/products`	POST	Products in a listing, addressed by your own id

Limits and behavior

Every route exists in two addressing variants: by Depict listing_id (a UUID) or by external_id (the listing’s id in your PIM, CMS or e-commerce platform). Use whichever id system you store.
The products response contains no listing metadata — no title, breadcrumbs or content cards. Fetch metadata with the GET routes.
Filters, sorting and pagination on the products endpoint work exactly as on search; the same limits apply (cursor limit 1–250, hits_per_page 1–200, no mixing of pagination styles).
There is no query field on listing requests. The per-response tracking id is product_listing_request_id (search: search_request_id) and each display carries product_listing_result_id (search: search_result_id).
The GET routes carry a 10-second cache header — they are designed to be called on every page load.
An unknown listing_id or external_id returns 404.
v2’s body-based addressing (query_id — typically the slug — plus type to disambiguate name collisions) does not exist on v3. v3 addresses listings by path parameter, so slug ambiguity cannot occur.
Response fields with null values are omitted from the JSON (exclude_none serialization).

The listing object

All listing endpoints return listings in this shape:

Field	Type	Description
`listing_id`	string (UUID)	Depict’s id for the listing
`external_id`	string	The listing’s id in your own system. May be absent
`listing_type`	string	One of `category`, `campaign`, `smart_pick`, `brand`, `look`, `style`, `long_tail_collection` — see types of listing pages
`title`	string	Display title of the listing
`slug`	string	URL slug. May be absent
`image_urls`	array of strings	Images for the listing
`show_in_breadcrumbs`	boolean	Whether to show the listing in navigation breadcrumbs
`show_in_quicklinks`	boolean	Whether to show the listing in quicklinks

Listing metadata

GET /v3/listings/{listing_id} or GET /v3/listings/external_id/{external_id} with query parameters merchant, market, locale (all required) and optional session_id. The response is the listing object plus:

Field	Type	Description
`ancestors`	array of listings	Ordered ancestors, root first — use for breadcrumbs
`siblings`	array of listings	Listings sharing the same parent, including the requested listing itself
`children`	array of listings	Direct children — use for subcategory navigation
`content_blocks`	array	The listing’s content cards, to place in the product grid

Content cards

Content cards are merchandising tiles (images or videos) placed in the product grid. On the wire the field is named content_blocks. Each element:

Field	Type	Description
`span_columns`	integer	Grid columns the card spans
`span_rows`	integer	Grid rows the card spans
`row`	integer	Grid row the card is placed on
`position`	string	Horizontal placement: `left`, `center` or `right`
`content`	object	The media: `type` (`image` or `video`), `url`, optional `link`, and an optional single-line text overlay as `text` with `text_position` (one of `top-left`, `top-center`, `top-right`, `middle-left`, `middle-center`, `middle-right`, `bottom-left`, `bottom-center`, `bottom-right`)

GET /v3/listings with query parameters merchant, market, locale (all required) and an optional repeatable types parameter to filter by listing_type. The response is a list of listing objects, each extended with a recursive children array of the same shape — the complete listing tree in one call.

Products in a listing

POST /v3/listings/{listing_id}/products or POST /v3/listings/external_id/{external_id}/products with a JSON body:

Field	Type	Required	Description
`merchant`	string	Yes	Your merchant identifier
`market`	string	Yes	Market identifier
`locale`	string	Yes	Locale identifier
`filters`	array	No	Same semantics as search filters
`sort`	object	No	Same semantics as search sorting
`session_id`	string	No	Session identifier; required for the request to be tracked and attributable
`metadata`	object	No	String-to-string map; only use values agreed with Depict
`cursor` / `limit` / `page` / `hits_per_page`	—	No	Pagination, same rules as search

Example request:

{
  "merchant": "MERCHANT_ID",
  "market": "MARKET",
  "locale": "en",
  "limit": 40,
  "session_id": "SESSION_ID"
}

Response

Field	Type	Description
`displays`	array of objects	The products, one object per card. Merchant-specific product data; each display carries a `product_listing_result_id` used for tracking
`n_hits`	integer	Total number of products in the listing. Not necessarily exact
`sorts`	array	Available sorting methods
`filters`	array	Available filters
`product_listing_request_id`	string	Identifier for this response, used in tracking
`cursor`	string	Cursor for the next page. Absent when there are no more results
`page`	integer	Echoed page index when page-based pagination was used; absent otherwise

​Limits and behavior

​The listing object

​Listing metadata

​Content cards

​Navigation tree

​Products in a listing

​Response

Limits and behavior

The listing object

Listing metadata

Content cards

Navigation tree

Products in a listing

Response