> ## 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.

# Recommendations

> The recommendations endpoint. Recommendation types, the anchor, cart, recent views and exclude inputs, used_inputs and errors.

`GET /v4/{merchant}/recommendations` returns recommended products. You can also send a `POST` with the same fields as a JSON body.

Each request names a recommendation type, such as similar products on a product page. A type decides which inputs it reads. [`/context`](https://docs.depict.ai/api-v4/endpoints#context) lists your store's types under `recommendation_types`.

## Types

| Your store has | Types | Each type reads |
| - | - | - |
| No recommendation setup with Depict | `similar`: products similar to one product, for a product page | `anchor` (a product) |
| Recommendation surfaces set up with Depict | One type per surface, such as similar products, up-sell, cart, checkout or landing page, named by the surface's key | `cart` and `recent_views`, plus an `anchor` when the surface is for a product or category page |

* A surface's type also answers to the surface's name or id.
* A store with surfaces gets its surfaces instead of `similar`. `/context` always lists what your store has.
* A store with no types has no `recommendation_types` in `/context`, and every `type` gets `404 unknown_recommendation_type`.

## Request

| Parameter (GET) | POST field | Notes |
| - | - | - |
| `market` | `market` | Required |
| `locale` | `locale` | Optional |
| `type` | `type` | Required. One of your store's types |
| `anchor=product:<id>` | `anchor: {"type", "id"}` | The product or category the recommendations are for. `type` is `product` or `category`. A product's `id` is a `product_id`, SKU or `group_id` |
| `cart` | `cart` | The products in the cart, as 1 to 100 `product_id`s, SKUs or `group_id`s |
| `recent_views=<id>@<time>,...` | `recent_views: [{"id", "at"}]` | 1 to 50 products the shopper viewed. Each is a `product_id`, SKU or `group_id` with `at`, the time of the view, such as `2026-10-26T12:00:00Z` |
| `exclude` | `exclude` | Up to 100 `product_id`s, SKUs or `group_id`s never to return. Every type takes it |
| `limit` | `limit` | 1 to 100. See [How many products you get](#how-many-products-you-get) |
| `include` | `include` | [Card extras](https://docs.depict.ai/api-v4/contract.md#card-extras): `attributes`, `variants` or both. Every type takes it |

* There is one anchor per request. Send other products as `cart` or `recent_views`.
* Recent views count newest first, by `at`, and only the newest 20 count.
* An input the type doesn't read gets `400 unsupported_input`, so a wrong input never silently returns the wrong products.
* `similar` needs an anchor. A surface answers without one, from its steps that need no anchor.

In a GET, encode special characters inside an id. A colon is `%3A`, a comma `%2C`, an `@` `%40`, and a `+` in a time `%2B`. Encode each id on its own with `encodeURIComponent`, then join them with literal commas and `@`. Don't pass a whole list to `URLSearchParams`. It encodes the commas too, so the list arrives as one id or the request fails.

### How many products you get

* `similar` returns 20 by default.
* A surface returns its own size by default, or 25 when it sets none. `limit` can lower the count but not raise it above the surface's size.
* A surface that shows Looks returns 30 by default, and never more.

Similar products for a product page:

```http theme={null}
GET /v4/acme/recommendations?market=se&locale=sv-SE&type=similar&anchor=product:V-1001-M&limit=4
```

The same as a POST, leaving out two products:

```http theme={null}
POST /v4/acme/recommendations

{"market": "se", "locale": "sv-SE", "type": "similar",
 "anchor": {"type": "product", "id": "V-1001-M"},
 "exclude": ["V-1002-L", "G-3003"], "limit": 8}
```

A checkout surface, keyed `checkout` in this store's setup:

```http theme={null}
POST /v4/acme/recommendations

{"market": "se", "type": "checkout", "cart": ["V-1001-M", "V-2002-S"],
 "recent_views": [{"id": "V-3003-L", "at": "2026-10-30T09:12:00Z"}]}
```

## Response

```json theme={null}
{
  "request_id": "...",
  "currency": "SEK",
  "products": [
    {"group_id": "G-2002", "title": "Rain Jacket", "...": "..."}
  ],
  "used_inputs": {
    "anchor": {"type": "product", "id": "V-1001-M"}
  }
}
```

| Field | Notes |
| - | - |
| `request_id` | The request's id |
| `currency` | The currency of every price in `products`, such as `SEK`. Absent when there are no products |
| `products` | [Product cards](https://docs.depict.ai/api-v4/contract.md#product), best first. At most `limit`, and possibly fewer or none |
| `used_inputs` | The inputs the type used. That is the `anchor`, and the `cart`, `recent_views` and `exclude` ids that matched a product |

An id that matched no product is left out of `used_inputs`. Compare `used_inputs` with your request to see which ids weren't found. A product anchor that matches nothing is not an error, and `similar` then returns no products. A category anchor is always echoed.

## How types choose products

### `similar`

* Products are ranked by how similar they are to the anchor. Products that aren't similar enough are left out, even if the list gets short. A short list isn't filled with other products.
* Only products that are active, priced and sold in the request's market, and in stock there, are returned.
* One card per product. The anchor's product and the `exclude` products never appear, and neither does a card that holds one of them.
* The card's selected variant is the one that matched best.

### Surfaces

* A surface runs the steps set up for it, in order. When one step comes up short, the next steps fill the list.
* Your custom rules, which are pins and hides, and your Look pins apply. A surface set to show only pinned products answers from them alone. If your rules can't be applied, some surfaces show best sellers instead.
* Products you hide from recommendations are left out.
* The anchor's product, and other products your storefront shows as the same product, never appear. Neither do the `exclude` products.
* Products in `cart` never appear.
* A surface set to avoid other surfaces leaves out the products they show.
* Out-of-stock products are left out when your setup filters them.
* You get one card per recommended colorway, so two colorways of one product can both appear. On stores whose cards hold every colorway, the card shows the recommended colorway's sizes and lists the others in `colorways`. With `include=variants` it adds one variant for each other colorway, not all their sizes.
* A surface set to shuffle returns a different order on each request.

## Errors

| Code | Status | When |
| - | - | - |
| `unknown_recommendation_type` | 404 | `type` isn't one of your store's types. `path` is `["type"]` |
| `unsupported_input` | 400 | The type doesn't read an input you sent. Examples are `cart` or `recent_views` on `similar`, an anchor on a surface that takes none, and an anchor of the wrong kind, such as a category anchor on a product surface. `path` names the input, such as `["cart"]` |
| `bad_request` | 400 | No `anchor` on `similar`, a GET `anchor` that isn't `<type>:<id>`, a recent view without a valid `at`, a value out of range, or an unknown parameter |
| `not_implemented` | 501 | The surface uses custom rules or Looks that the API can't serve for your store. Talk to your Depict contact |
| `upstream_unavailable` | 503 | Your recommendation setup couldn't be read, or the recommendations failed. Try again |

```json theme={null}
{"error": {"code": "unsupported_input", "message": "surface similar does not read cart", "request_id": "...", "path": ["cart"]}}
```

Other errors are the same as on every endpoint. See [Errors](https://docs.depict.ai/api-v4/contract.md#errors).


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