# Attribute definitions

> An Attribute definition is a reusable product attribute, free text or a fixed list of options, attached to categories.
{/* generated:versioned-pages - edit _pm-authored, not this file */}

An **Attribute definition** declares a property that products can describe themselves with - a material, a color, a care note. It is attached to one or more [categories](/api/product-management/categories/), and products of those categories (or of their descendants) carry a value for it in their `attributes`.

A definition has one of two `type`s:

- `string` - the value is free, translatable text (a care note, say).
- `list` - the value must be one of the definition's [attribute options](/api/product-management/attribute-options/) (Red, Black, ...). When `multiple` is `true`, a product can carry several options of the same definition.

The `code` is the stable, machine-readable identifier of the definition. `code`, `type` and `multiple` are **immutable** once created; the translatable `name` and the `categories` can change.

## The Attribute definition object

## Common workflows

- **Describe products with free text.** Create a `string` definition, attach it to a category, then set a `value` for it in the `attributes` of the category's products.
- **Offer a fixed set of choices.** Create a `list` definition, add its [options](/api/product-management/attribute-options/), then reference an `option` in the products' `attributes`.
- **Audit usage.** Each definition reports a `valuesCount` - how many product attribute values currently reference it.

## Conventions

### Version

This resource is only available in the `unstable` version. Select it with the request header:

```
Flowkiwi-Api-Version: unstable
```

### Authentication and headers

All requests require an OAuth 2.0 bearer token:

```
Authorization: Bearer <token>
```

Reading requires the `categories:read` scope; writing also requires `categories:write`.

Set the active locale for translatable fields:

```
Flowkiwi-Locale: fr-FR
```

### Partial updates

`PATCH` uses [JSON Merge Patch](https://datatracker.ietf.org/doc/html/rfc7396) with `Content-Type: application/merge-patch+json`.