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

# Response contract

> The typed response contract. The product card, variants, colorways, prices, card extras, enums, versioning and error codes.

Every response follows one typed contract. This page describes the product card, how the contract is versioned, and the errors you can get.

## Principles

1. `browse`, `products` and `recommendations` return the same product card, and take the same [`include`](#card-extras) to add to it.
2. A card always has what you need to sell the product. That is its title, slug, images, price, stock, at least one variant, and each variant's `product_id`, plus the [merchant attributes](https://docs.depict.ai/api-v4/attributes.md) your store requires. `images` is `[]` when a product has no images.
3. The card is small by default. It holds what a product grid needs, and [`include`](#card-extras) adds the rest.
4. Ids are strings from your catalog. Numeric ids, such as Shopify's or Centra's, are decimal strings, never JSON numbers.
5. New fields can appear. Ignore fields you don't know, and accept new values in open enums.

## Example

A rain jacket that comes in black and yellow. The card shows the black colorway with its sizes, and lists both colorways for a color picker.

```json theme={null}
{
  "request_id": "...",
  "currency": "SEK",
  "products": [
    {
      "group_id": "G-1001-BLK",
      "title": "Rain Jacket Black",
      "slug": "rain-jacket-black",
      "images": ["https://cdn.acme.example/rain-black-1.jpg", "https://cdn.acme.example/rain-black-2.jpg"],
      "color": {"name": "Black", "hex": "#000000"},
      "price": {"amount": 1999},
      "in_stock": true,
      "badges": [],
      "variants": [
        {"product_id": "V-1001-BLK-S", "size": "S", "in_stock": false},
        {"product_id": "V-1001-BLK-M", "size": "M", "in_stock": true},
        {"product_id": "V-1001-BLK-XL", "size": "XL", "in_stock": true, "price": {"amount": 2199}}
      ],
      "selected": 1,
      "colorways": [
        {"group_id": "G-1001-BLK", "product_id": "V-1001-BLK-M", "color": {"name": "Black", "hex": "#000000"},
         "image": "https://cdn.acme.example/rain-black-1.jpg", "in_stock": true},
        {"group_id": "G-1001-YEL", "product_id": "V-1001-YEL-M", "color": {"name": "Yellow", "hex": "#ffd400"},
         "image": "https://cdn.acme.example/rain-yellow-1.jpg", "price": {"amount": 1499, "compare_at": 1999},
         "in_stock": true, "title": "Rain Jacket Yellow", "slug": "rain-jacket-yellow"}
      ],
      "tracking_id": "..."
    }
  ]
}
```

* `currency` is stated once for the whole response. Every price in it is in that currency.
* The XL variant costs more than the card's price, so it carries its own `price`. The other variants don't.
* The yellow colorway is on sale and has its own title and page, so it carries its own `price`, `title` and `slug`. To show its sizes, send [`include=variants`](#card-extras), or ask [`products`](https://docs.depict.ai/api-v4/endpoints#products) for `V-1001-YEL-M`.

## Product

| Field | Always there | Notes |
| - | - | - |
| `group_id` | yes | The product's id. Where your store groups cards by style, the id of the colorway the card shows |
| `title` | yes | The selected variant's title |
| `brand` | no | |
| `slug` | yes | The product's path on your site. `""` when it has none in the locale |
| `images` | yes | The shown colorway's image URLs in order. By convention `[0]` is the main image and `[1]` the hover image |
| `video` | no | `{url, poster_url?}` |
| `color` | no | The shown colorway's [color](#color), when your store has color names |
| `price` | yes | The selected variant's [price](#price) |
| `in_stock` | yes | Whether any variant, in any colorway, is in stock in the request's market |
| `badges` | yes | Labels for the card. The one badge is `sale`, set when the selected variant's price is reduced. Can be `[]`. More values may be added |
| `variants` | yes | The shown colorway's variants, which are its sizes. At least one. See [Variant order](#variant-order) |
| `selected` | yes | The index in `variants` of the variant to show first. It is the variant that best matches the request. When that one is out of stock, an in-stock variant of the same colorway is selected instead |
| `colorways` | no | Every [colorway](#colorway) of a style card, the shown one included, in the card's order. Absent on a card with one colorway |
| `attributes` | no | With `include=attributes`, your [display attributes](https://docs.depict.ai/api-v4/attributes.md#display-attributes). Each is one value when every variant agrees, else a list of the distinct values. On a style card, a value that differs between colorways is on each variant instead |
| `tracking_id` | yes | An id for this card in this response. Don't parse it |

## Variant

| Field | Always there | Notes |
| - | - | - |
| `product_id` | yes | The variant's id. Use it for your cart and tracking |
| `size` | no | The size name |
| `in_stock` | yes | Whether it is in stock in the request's market. Untracked stock counts as out of stock |
| `price` | no | The variant's [price](#price), only when it differs from the card's `price` |
| `image` | no | The variant's own main image, only when it differs from the card's `images[0]` |
| `sku` | no | With `include=attributes` only |
| `attributes` | for some stores | Your declared [merchant attributes](https://docs.depict.ai/api-v4/attributes.md), such as an add-to-cart id. With `include=attributes`, also the variant's display attribute values |
| `group_id` | no | On another colorway's variants, that colorway's `group_id`. A variant without it belongs to the shown colorway |
| `color` | no | The variant's [color](#color), only when it differs from the card's, as on another colorway's variants |
| `title` | no | Only when it differs from the card's title, as on another colorway's variants |
| `slug` | no | Only when it differs from the card's slug, as on another colorway's variants. Link the variant here |

### Variant order

When your store shows sizes, variants are sorted by size. Letter sizes come first, from smallest to largest, then numeric and half sizes, then one size, then other size names, and last the variants without a size. Otherwise variants are sorted by `product_id`. Some stores keep their catalog's order.

## Colorway

A style card can hold several colorways of one product. `colorways` has one entry for each, with enough to draw a color picker.

| Field | Always there | Notes |
| - | - | - |
| `group_id` | yes | The colorway's id |
| `product_id` | yes | The variant to show for the colorway, one in stock when it has any. Ask [`products`](https://docs.depict.ai/api-v4/endpoints#products) for it to get the colorway's card |
| `color` | no | The colorway's [color](#color), when your store has color names |
| `image` | no | The colorway's main image |
| `price` | no | The price of the colorway's `product_id`, only when it differs from the card's `price` |
| `in_stock` | yes | Whether any of its variants is in stock in the request's market |
| `title`, `slug` | no | Only when they differ from the card's |

## Color

| Field | Notes |
| - | - |
| `name` | The color name from your display settings, `color_name` |
| `hex` | A CSS color such as `#ffd400`, when your display settings have one as `color_hex` or `color_hex_code` |

## Price

| Field | Notes |
| - | - |
| `amount` | The price to pay, in major units. `1999` is 1,999 SEK |
| `compare_at` | The original price. Only there when it is higher than `amount` |

A price has no currency of its own. The response's `currency`, an ISO 4217 code such as `SEK`, applies to every price in it. `currency` is absent when the response has no products.

## Card extras

`include` adds to the card on `browse`, `products` and `recommendations`. Send one or both, comma-separated in a GET or as an array in a POST.

| Value | Adds |
| - | - |
| `variants` | Every colorway's variants, not just the shown one's. Another colorway's variants carry its `group_id` and, when they differ, its `color`, `image`, `price`, `title` and `slug` |
| `attributes` | Your [display attributes](https://docs.depict.ai/api-v4/attributes.md#display-attributes) on the card and each variant, and each variant's `sku` |

```http theme={null}
GET /v4/acme/products?market=se&ids=V-1001-BLK-M&include=variants,attributes
```

* With `include=variants`, the variants are sorted across the whole card, so colorways are interleaved. Group them by `group_id`.
* A recommendation surface's card is narrower. With `include=variants` it has the recommended colorway's sizes and one variant for each other colorway. See [Surfaces](https://docs.depict.ai/api-v4/recommendations.md#surfaces).
* Without `include`, each variant still has your declared attributes, such as an add-to-cart id.
* Both extras make the response bigger, so ask only for what the page shows.
* On `browse`, card extras don't change which [sections](https://docs.depict.ai/api-v4/endpoints.md#browse) you get.

## Open and closed enums

An open enum can get new values, so handle values you don't know. A closed enum can't, so you can handle every value.

| Kind | Enums |
| - | - |
| Open | `badges`, listing `type`, content block `type`, `position` and `visibility`, error `code`, recommendation `inputs` |
| Closed | Facet `type`, sort `order`, suggestion `type`, anchor `type` |

## Versioning

Every `/v4` response sends the header `x-depict-contract: 6.0`, and so do most errors. An unexpected `500` may not.

A minor version only adds things, such as a new optional field, a new value in an open enum, a new error code or a new endpoint. Your code keeps working.

A major version may break things, such as a removed or renamed field, a new required field, a changed type or a new value in a closed enum. A major version gets a new path, `/v5`, and the old one keeps running alongside it.

## Errors

Errors have this shape:

```json theme={null}
{
  "error": {
    "code": "bad_request",
    "message": "limit: Too big: expected number to be <=100",
    "request_id": "...",
    "path": ["limit"]
  }
}
```

* `path` points to the parameter or body field that is wrong, when the error is about one. Every filter error has `["filter_by"]`.
* `allowed` lists the accepted names on `unknown_filter_field` and `unknown_sort_field`.
* Handle codes you don't know by their status.

| Code | Status | When |
| - | - | - |
| `bad_request` | 400 | The request is malformed. Examples are an unknown or repeated parameter, a wrong type, a value out of range, an empty list item, broken percent-encoding, a body that isn't a JSON object or is over 64 KiB, a POST with a query string, a `cursor` that didn't come from a response, a missing or malformed `anchor`, and a `filter_by` over 4,096 characters |
| `invalid_filter` | 400 | See [Filter errors](https://docs.depict.ai/api-v4/filters.md#errors) |
| `unknown_filter_field` | 400 | See [Filter errors](https://docs.depict.ai/api-v4/filters.md#errors) |
| `unknown_sort_field` | 400 | See [Sorts](https://docs.depict.ai/api-v4/filters.md#sorts) |
| `unsupported_input` | 400 | `/recommendations` got an input its type doesn't read. See [Recommendation errors](https://docs.depict.ai/api-v4/recommendations.md#errors) |
| `not_found` | 404 | No such path, or your store can't be searched in this locale |
| `unknown_merchant` | 404 | No store with that name |
| `unknown_market` | 404 | No market matches, or it has no price list |
| `unknown_locale` | 404 | No locale matches |
| `unknown_recommendation_type` | 404 | `/recommendations` got a `type` your store doesn't have |
| `unknown_listing` | 404 | No listing with that id or external id, or the listing has no text in the locale's language |
| `method_not_allowed` | 405 | The path doesn't take this method. The `allow` header lists the ones it takes |
| `search_not_enabled` | 422 | `browse` got a `query`, but search isn't turned on for your store |
| `internal` | 500 | Something failed on Depict's side |
| `not_implemented` | 501 | Your store's setup needs something the API doesn't serve, such as some curated recommendation types. Talk to your Depict contact |
| `upstream_unavailable` | 503 | Search, recommendations or Depict's product data didn't answer in time, or failed. Try again |
| `listing_rule_input_invalid` | 503 | A listing's rules can't be applied right now. Depict is alerted. Try again later |

A 5xx always means a problem on Depict's side, never in your request. Quote the `request_id` when you report one.


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