# Attribute options

> An Attribute option is one allowed value of a list attribute definition.
{/* generated:versioned-pages - edit _pm-authored, not this file */}

An **Attribute option** is one allowed value of a `list` [attribute definition](/api/product-management/attribute-definitions/) - `Red` or `Black` for a `Color` definition. Together, a definition's options form the reference list products pick from: a product references an option in its `attributes`, rather than repeating the text.

Options are **created and listed under their definition** (`/api/attribute_definitions/{definitionId}/options`), then read, updated and deleted by their own id (`/api/attribute_options/{id}`). Only `list` definitions accept options: creating one under a `string` definition is rejected with `422`.

Each option has a translatable `value` and a `position` that orders it within its definition.

## The Attribute option object

## Common workflows

- **Build the reference list.** Create one option per allowed value under the definition. Omit `position` to append each at the end.
- **Reorder.** Patch the `position` of an option, and list with `order[position]` to read them in display order.
- **Localize.** Read or write the translatable `value` per locale with the `Flowkiwi-Locale` header.

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