api.depict.ai. If you are building a new integration, start at the introduction instead.
You don’t have to upgrade today
The v2 and v3 routes keep working. They take the same paths and requests and return the same responses, so an existing storefront needs no code change. Most of their responses carryDeprecation: true and a Link header that points to the legacy reference. No end date is set.
Upgrade when you want what the current API adds, which is one endpoint for search and listing pages, a smaller typed product card, and filters that can combine conditions with || and parentheses.
What changes
- The host stays
https://api.depict.ai. Every path now starts with/v4. - The store’s name moves from the
merchantortenantfield into the path, as/v4/{merchant}/.... - Every endpoint that returns data takes a GET as well as a POST.
- Search results and listing products come from one endpoint,
browse. - Every endpoint returns the same product card, with fixed field names.
- Filters are one
filter_bystring instead of a list of filter objects. - Errors have one shape, with a
codeyou can switch on.
Routes
Requests
Filters
A v3 filter is an object withfield, op and data. In filter_by, each one becomes a clause, and you join clauses with &&.
The v3 field
sale_price is price. For other fields, use the field of each facet in a browse response. Filters and sorts has the full syntax, including || and parentheses, which v3 filters could not express.
Sorts
Responses
Search and listing pages
Product cards
A v3 display hasvariant_index and variant_displays, and each variant display carries the fields your display settings list. The current card has fixed fields, and your display fields move behind include=attributes.
Prices no longer carry a currency. The response states
currency once.
Facets
Listings
In a listing suggestion,
ancestors is now path, the parent listings’ titles.
Recommendations
A response hasproducts in place of displays, and used_inputs, which tells you which of your ids matched a product. See Recommendations.
Errors
Errors are{"error": {"code", "message", "request_id", "path"}} in place of {"detail": ...}. A request that fails validation gets 400, where v3 sent 422. Errors lists every code.
Behavior that differs
- Ids in a POST body are JSON strings, numeric ids too.
- An unknown parameter or body field gets
400 bad_request. Remove fields the API doesn’t take, such assession_id. - The response is smaller by default. Check each page for fields it reads from a variant display, and add
include=attributesorinclude=variantsonly where it needs them. - A style card lists its colorways in
colorways, with enough to draw a color picker. You no longer build the picker from variant displays. - Breadcrumbs and quick links come ready to render.
Tracking
New integrations send events toPOST /v4/{merchant}/events. An existing integration has two choices.
Keep your current tracking
/create-events, /v2/create-events and /v2/track keep working. The one change is the result id. Each card now has a single tracking_id. Send it where your events carried search_result_id, product_listing_result_id or recommendation_id.
Move to the events endpoint
Each event also needs an
event_id, a market and a ts. Events lists every field.
Move one action at a time if you like, but send each action to one place only. An action sent to both the old endpoints and the events endpoint is counted twice.
The track: false header works as before.
