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

# Merchant attributes

> Fields on the product card that only your store defines, such as an add-to-cart id, and the display attributes you can add with include=attributes.

Some stores need fields on the product card that only they define. A common case is an add-to-cart id: your cart takes an id other than the variant's `product_id`, and Depict computes it from your product data. If a card went out without it, your storefront couldn't add the product to the cart. Merchant attributes make such fields part of your store's contract.

The card carries two kinds of attribute. Declared attributes are computed when Depict imports your product data, and come on every card. [Display attributes](#display-attributes) are the fields your display settings list, and come only when you ask with `include=attributes`.

## Declared attributes

Depict computes each declared attribute when it imports your product data, and stores the result. The API reads the stored value. It returns declared attributes on `browse`, `products` and `recommendations`, with or without `include`.

On the card, an attribute appears under its `key`, on each variant:

```json theme={null}
{
  "product_id": "V-1001-M",
  "attributes": { "add_to_cart_id": "1001-M-SE" }
}
```

You can filter on the same `key`, as in `filter_by=add_to_cart_id:=1001-M-SE`. See [Fields you can filter on](https://docs.depict.ai/api-v4/filters.md#fields-you-can-filter-on).

Each attribute has a type:

| Type | Example key |
| - | - |
| string | `add_to_cart_id` |
| number | `weight_kg` |
| boolean | `in_sweden` |
| string list | `occasions` |

* A key is lowercase snake case, matching `^[a-z][a-z0-9_]*$`.
* A variant without a value for an attribute doesn't carry it, unless the attribute is [required](#required-attributes).
* Changing an attribute's type is a breaking change for your store's card. To change what an attribute means with the same type, say from color names to hex codes, use a new key.
* If one key ends up stored with two types, neither is served. Use a new key instead.
* An empty string counts as no value.

## Required attributes

Depict can mark an attribute as required for your store, with an optional pattern its values must match, such as your cart's id format. One attribute can be marked as the add-to-cart id. The add-to-cart id is always required.

* Every variant on a card carries a valid value for each required attribute.
* A variant without a valid value is left out of the card. A card with no variants left is left out of the page. The rest of the page is still served.
* On `products`, the id of a card left out this way is in `missing`.

Talk to your Depict contact to set up declared or required attributes.

## Display attributes

Send `include=attributes` on `browse`, `products` or `recommendations` to get the fields your store's display settings list, named by their id in those settings:

```http theme={null}
GET /v4/acme/browse?market=se&query=jacket&include=attributes
```

* `variants[i].attributes.<id>` is that variant's value.
* `attributes.<id>` on the card is the value when every variant agrees. Otherwise it is a list of the distinct values, with numbers and booleans as strings. On a style card, a value that differs between colorways is on each variant, not on the card.
* A value with translations comes in the request's language.
* A display attribute that lives on your price list, such as a `show_as_sale` flag, takes its value from the request's market.
* Ids that are already card fields, such as the title, SKU, prices and images, are not repeated.
* On a variant, a declared attribute wins over a display attribute with the same name.
* The ids your store groups cards by, such as `item_group_id`, are display attributes too, even when your display settings don't list them.
* Color comes without `include`. The color name `color_name` and the hex code `color_hex` or `color_hex_code` are served as the card's [`color`](https://docs.depict.ai/api-v4/contract#color) and each colorway's, not in `attributes`. With `include=attributes` they are in `attributes` too. A color attribute you declare is always in `attributes`.
* Image details such as alt text are not part of the card.

These built-in ids are filled when your display settings list them:

| Id | Type | Value |
| - | - | - |
| `currency` | string | The price's currency |
| `description` | string | The product description |
| `handle` | string | The slug |
| `inactive` | boolean | Always `false`: inactive products are never returned |
| `item_group_id` | string | Your id for the product |
| `transaction_product_id` | string | The SKU, or a bundle's own id |
| `quantity` | number | Stock you can sell in the request's market, summed over locations. Absent when stock isn't tracked |
| `category_ids` | string list | Category ids. `[]` when none |
| `tags` | string list | `[]` when none |
| `barcode` | string | The GTIN |
| `pim_variant_index` | number | The variant's position |
| `product_type` | string | The product type |
| `published_at` | string | When the product was created, as an ISO 8601 time |
| `variant_title` | string | The size name |

If your store has its own attribute with one of these ids, you get your value instead. On Shopify stores you always get the built-in, and `tags`, `barcode`, `pim_variant_index`, `product_type`, `published_at` and `variant_title` come from Shopify's product fields.


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