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.
Display fields depend on your merchant configuration — 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`

Common surface names include after_basket for a cart drawer and checkout for checkout recommendations. These are separate surfaces. Preserve the type and product context used by your existing integration. Confirm availability for each market with Depict. Do not select a type only from a surface’s display title. 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

Displays contain merchant-specific objects. Confirm the fields your product cards need with Depict. Preserve each display’s recommendation_id when you transform its product data.

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