> ## Documentation Index
> Fetch the complete documentation index at: https://docs.depict.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade from v3/v2

> What to change in a storefront integration built on the v3 or v2 endpoints. Route, request and response mapping to the Platform API, and the behavior that differs.

This page is for an integration that calls the v3 or v2 endpoints on `api.depict.ai`. If you are building a new integration, start at the [introduction](https://docs.depict.ai/api-v4/introduction.md) 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 carry `Deprecation: true` and a `Link` header that points to the [legacy reference](https://docs.depict.ai/api-reference/headless/legacy-v2-v3.md). 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 `merchant` or `tenant` field 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`](https://docs.depict.ai/api-v4/endpoints#browse).
* Every endpoint returns the same [product card](https://docs.depict.ai/api-v4/contract.md#product), with fixed field names.
* Filters are one `filter_by` string instead of a list of filter objects.
* Errors have one shape, with a `code` you can switch on.

## Routes

| v3 or v2 route | Use instead |
| - | - |
| `POST /v3/search/results`, `/v2/search/results` | [`browse`](https://docs.depict.ai/api-v4/endpoints#browse) with `query` |
| `POST /v3/listings/{id}/products` | [`browse`](https://docs.depict.ai/api-v4/endpoints#browse) with `listing` |
| `POST /v3/listings/external_id/{external_id}/products` | [`browse`](https://docs.depict.ai/api-v4/endpoints#browse) with `listing_external_id` |
| `POST /v2/product-listing` | [`browse`](https://docs.depict.ai/api-v4/endpoints#browse) with `listing` |
| `GET /v3/search/suggestions`, `/v2/search/suggestions` | [`suggest`](https://docs.depict.ai/api-v4/endpoints#suggest) |
| `GET /v2/search/content` | [`browse`](https://docs.depict.ai/api-v4/endpoints#browse) with `query` and `include=content` |
| `POST /v3/search/related`, `/v2/search/related` | No single route. Run `browse`, then ask [`recommendations`](https://docs.depict.ai/api-v4/recommendations) with the top product as the anchor |
| `GET /v3/listings` | [`listings`](https://docs.depict.ai/api-v4/endpoints#listing-tree) |
| `GET /v3/listings/{id}`, `/v3/listings/external_id/{external_id}` | [`listings/{id}`](https://docs.depict.ai/api-v4/endpoints#listing-header), or `listings?external_id=` |
| `POST /v3/recommend/products`, `/v2/recommend/products/*` | [`recommendations`](https://docs.depict.ai/api-v4/recommendations) |
| `POST /v3/get-displays` | [`products`](https://docs.depict.ai/api-v4/endpoints#products) |
| `GET /v3/markets`, `/v3/locales` | [`context`](https://docs.depict.ai/api-v4/endpoints#context) |
| `POST /create-events`, `/v2/create-events`, `/v2/track` | [`events`](https://docs.depict.ai/api-v4/events), or keep sending to these. See [Tracking](#tracking) |

## Requests

| v3 or v2 field | Now |
| - | - |
| `merchant`, `tenant` | In the path |
| `market` | `market`. The market ids you send today still work. `/context` lists each market's `key` |
| `locale` | `locale`, now optional. Tags such as `sv-SE` and `sv_SE` both work |
| `query` | `query` |
| `filters` | `filter_by`. See [Filters](#filters) |
| `sort: {field, order}` | The same object in a POST, or `sort=<field>.<order>` in a GET. See [Sorts](#sorts) |
| `cursor`, `limit` | `cursor`, `limit` |
| `page`, `hits_per_page` | Not available. Page with `cursor` |
| `session_id`, `user_id`, `dsid`, `metadata` | Not sent. Shopper identity stays in your tracking events |
| The listing id in the path | `listing`, or `listing_external_id` for your own id |
| `product_ids` on `/v3/get-displays` | `ids`, at most 50 |
| `product_ids` on `/v3/recommend/products` | The first id is the `anchor`. Send the others as `exclude` or `cart` |
| `type` on a recommendation request | `type`. `/context` lists the types your store has |

### Filters

A v3 filter is an object with `field`, `op` and `data`. In `filter_by`, each one becomes a clause, and you join clauses with `&&`.

| v3 `op` | `filter_by` clause |
| - | - |
| `eq` | `field:=value` |
| `neq` | `field:!=value` |
| `in` | `field:=[a,b]` |
| `nin` | `field:!=[a,b]` |
| `leq` | `field:<=100` |
| `geq` | `field:>=100` |
| `inrange` | `field:[100..500]` |

The v3 field `sale_price` is `price`. For other fields, use the `field` of each facet in a browse response. [Filters and sorts](https://docs.depict.ai/api-v4/filters.md) has the full syntax, including `||` and parentheses, which v3 filters could not express.

### Sorts

| v3 sort field | Now |
| - | - |
| `_relevance` | `relevance`, or leave `sort` out |
| `sale_price` | `price` |
| `product_timestamp` | `newest` |

## Responses

### Search and listing pages

| v3 field | Now |
| - | - |
| `displays` | `products` |
| `n_hits` | `total`. It can be absent when the total can't be counted |
| `search_request_id`, `product_listing_request_id` | `request_id` |
| `cursor` | `cursor` |
| `filters` | `facets`, returned by default |
| `sorts` | `sorts`, returned by default |
| `content_search_links` | `content`, with `include=content`. Each link's `page_url` is `url` |

### Product cards

A v3 display has `variant_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`.

| v3 field | Now |
| - | - |
| `variant_displays` | `variants`. By default they are the sizes of the shown colorway. Send `include=variants` for every colorway's |
| `variant_index` | `selected` |
| `title` | `title` on the card. A variant has its own only when it differs |
| `image_urls` | `images` on the card |
| `sale_price` | `price.amount` |
| `original_price` | `price.compare_at`, present only when it is higher than `amount` |
| `in_stock` | `in_stock`, on the card and on each variant |
| `product_id` | `product_id` on each variant |
| `page_url` | `slug`, the product's path on your site |
| Your other display fields | `attributes`, with [`include=attributes`](https://docs.depict.ai/api-v4/attributes#display-attributes) |
| `search_result_id`, `product_listing_result_id`, `recommendation_id` | `tracking_id` on the card |

Prices no longer carry a currency. The response states `currency` once.

### Facets

| v3 filter `meta` | Now |
| - | - |
| `group_title` | `title` |
| `values`, `counts`, `names`, `swatches` as parallel lists | One `values` list. Each entry has `value`, `label`, `count`, `selected` and `swatch` |
| `type: "checkbox-grid"` | `type: "grid"` |
| `type: "checkbox-color"` | `type: "swatch"` |
| `type: "checkbox-hierarchical"` | `type: "hierarchy"` |
| `type: "range"` with `min`, `max` | The same, with the selected range in `selected` |

### Listings

| v3 field | Now |
| - | - |
| `listing_id` | `id` |
| `listing_type` | `type` |
| `image_urls` | `images` |
| `ancestors` | `breadcrumbs`, already limited to the listings set to show in breadcrumbs |
| `children`, `siblings` | `quick_links`, already limited to the listings set to show as quick links |
| `show_in_quicklinks` | Gone. `quick_links` applies it for you |

In a listing suggestion, `ancestors` is now `path`, the parent listings' titles.

### Recommendations

A response has `products` in place of `displays`, and `used_inputs`, which tells you which of your ids matched a product. See [Recommendations](https://docs.depict.ai/api-v4/recommendations.md#response).

### 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](https://docs.depict.ai/api-v4/contract.md#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 as `session_id`.
* The response is smaller by default. Check each page for fields it reads from a variant display, and add `include=attributes` or `include=variants` only 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 to [`POST /v4/{merchant}/events`](https://docs.depict.ai/api-v4/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

| v3 or v2 event | Now |
| - | - |
| `type: "element_visible"` | `type: "impression"` |
| `type: "click"` | `type: "click"` |
| `type: "add_to_cart"` | `type: "add_to_cart"` |
| `type: "page_view"` | `type: "product_view"` |
| A purchase on `/v2/create-events` | `type: "purchase"`, with the order in `purchase` |
| `tenant`, `merchant` | In the path |
| `session_id`, `user_id`, `dsid` | `session_id` only. Send the id that stays the same for the shopper's device |
| `search_result_id`, `product_listing_result_id`, `recommendation_id` | `tracking_id` |
| `depict_ab_variant` | `ab_variant` |
| `document_referrer` | `referrer` |
| A JSON array of events | One event on each line |

Each event also needs an `event_id`, a `market` and a `ts`. [Events](https://docs.depict.ai/api-v4/events.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.