Interfacing directly with the API - 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.

If you don’t want to use our API Client you can make the requests yourself. Recommendations are served by a single endpoint:

POST https://api.depict.ai/v3/recommend/products

It replaces the three v2 endpoints /v2/recommend/products/general, /v2/recommend/products/product and /v2/recommend/products/products — the number of ids in product_ids selects the behavior. The full request/response schema is in the API Reference tab, under Platform API.

Limits and behavior

limit is 1–128.
No category parameter exists on /v3/recommend/products, and category recommendations have no v3 endpoint — see Category recommendations.
Valid type values are configured per merchant. Get your list from your Depict contact; an unconfigured combination returns an error (see Errors).
Unknown request fields are silently ignored — a misspelled field name is dropped, not rejected.
The response on the wire differs from the response model in the OpenAPI spec — see Response.

Request

Field	Type	Required	Description
`merchant`	string	Yes	Your merchant identifier, provided by Depict
`market`	string	Yes	Market identifier
`locale`	string	Yes	Locale identifier
`type`	string	Yes	The recommendation type, e.g. `cross_sell`. Configured per merchant
`product_ids`	array of strings	No	Zero, one or multiple product identifiers — selects the behavior, see below. Default `[]`
`limit`	integer	No	Maximum number of recommendations, 1–128
`session_id`	string	No	Session identifier; links the request to tracking

product_ids selects which recommendations you get:

`product_ids`	Behavior	Typical placement	v2 endpoint it replaces
Empty / omitted	General recommendations for the page type	Front page	`/v2/recommend/products/general`
One id	Recommendations for that product	Product page	`/v2/recommend/products/product`
Two or more ids	Recommendations for the set of products	Cart	`/v2/recommend/products/products`

Example request:

{
  "merchant": "MERCHANT_ID",
  "market": "MARKET",
  "locale": "en",
  "type": "TYPE",
  "product_ids": ["product-1", "product-2"],
  "session_id": "SESSION_ID"
}

Response

On the wire the response is:

Field	Type	Description
`displays`	array of objects	The recommendations, one object per product card. Merchant-specific product data; each display carries a `recommendation_id` used for tracking
`error`	string	Error message. Absent on success
`variant`	integer	A/B test variant, when an experiment is running. May be absent
`experiment_id`	string	A/B test experiment identifier. May be absent

The OpenAPI spec declares a different response model for this endpoint (typed displays without variant/experiment_id). The serving code bypasses that model: what actually comes back is the shape above, with displays as untyped merchant-specific objects. Code against the wire shape documented here, not against the spec’s declared response model.

Category recommendations

POST /v2/recommend/products/category is deprecated and closed to new integrations. It remains available for its existing consumers, and its removal is aligned with the upcoming v4 recommendations launch — not with the general v2 deprecation timeline. No v3 equivalent exists today, and /v3/listings is not a substitute: it serves merchandised category browsing, which is a different contract from category recommendations.

If you have an existing integration on this endpoint: it takes a v2-shaped body (tenant, market, category_id, type) and returns the same response shape as above. Do not build new functionality on it.

Errors

An unconfigured merchant returns 400 with {"detail": "Merchant {merchant} not configured for recommendations."}.
An unconfigured (merchant, market, type) combination returns {"error": "(tenant, market, type) not yet configured. Please contact Depict."}. The message wording uses the v2 vocabulary (tenant) and may change — match on the presence of error, not on the exact message text.

​Limits and behavior

​Request

​Response

​Category recommendations

​Errors

Limits and behavior

Request

Response

Category recommendations

Errors