# Options and variants (/ai/reference/catalog/product-options)

Toolset `product_options`, 13 tools.

## Records [#records]

### `product_option` [#product_option]

An option products are sold in, such as Size or Colour, with its values. An exclusive option belongs to one product; the others are shared and can be linked to many. get returns the values.

- Permission: `products.read`
- Tools: `product_option_list`, `product_option_get`

Filters on the list:

| Filter | Type | Required | Description |
| --- | --- | --- | --- |
| `q` | string |  |  |
| `title` | string |  |  |
| `is_exclusive` | boolean |  |  |

### `product_option_value` [#product_option_value]

One value of a product option, such as Large. List the values of one option with option_id. get takes <option id>/<value id>.

- Permission: `products.read`
- Tools: `product_option_value_list`, `product_option_value_get`

Filters on the list:

| Filter | Type | Required | Description |
| --- | --- | --- | --- |
| `option_id` | string | yes | The option whose values to list |
| `q` | string |  |  |

### `product_variant` [#product_variant]

A variant of any product: one purchasable combination of option values with its own SKU, price and stock settings. List across all products with q or sku; get takes <product id>/<variant id>.

- Permission: `products.read`
- Tools: `product_variant_list`, `product_variant_get`

Filters on the list:

| Filter | Type | Required | Description |
| --- | --- | --- | --- |
| `q` | string |  |  |
| `sku` | string |  |  |
| `barcode` | string |  |  |
| `manage_inventory` | boolean |  |  |
| `allow_backorder` | boolean |  |  |

## Actions [#actions]

### `product_option_create` [#product_option_create]

Create an option with its values.

Link it to products with product_options_link. is_exclusive makes it private to the one product it is linked to.

- Action key: `product_option.create`
- Permission: `products.write`
- Approval: Waits for approval when the store requires it for this action.
- Effect: Changes the live store.
- Retries: runs at most once; a repeat with the same idempotency key returns the first result.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | string | yes |  |
| `values` | list of string | yes | The values, such as ["S", "M", "L"] |
| `is_exclusive` | boolean |  |  |
| `metadata` | map of string or number or boolean or list of any value or map of any value or null |  |  |

Example input:

```json
{
  "title": "Size",
  "values": [
    "S",
    "M",
    "L"
  ]
}
```

### `product_option_delete` [#product_option_delete]

Delete an option and its values.

- Action key: `product_option.delete`
- Permission: `products.write`
- Approval: Always waits for a person to approve it.
- Effect: Changes the live store.
- Destructive: in compact mode it runs with `run_destructive_action`.
- Retries: safe to repeat with the same input.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `option_id` | string | yes | Product option ID from product_option_list |

Example input:

```json
{
  "option_id": "019bb39d-1471-7070-8cc5-bf1cb17d9bf9"
}
```

### `product_option_update` [#product_option_update]

Rename an option or change its values.

values replaces the option values with this list: values left out are removed from the option and from the variants that use them, so read the option first.

- Action key: `product_option.update`
- Permission: `products.write`
- Approval: Waits for approval when the store requires it for this action.
- Effect: Changes the live store.
- Retries: safe to repeat with the same input.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `option_id` | string | yes | Product option ID from product_option_list |
| `title` | string |  |  |
| `values` | list of string |  |  |
| `is_exclusive` | boolean |  |  |
| `metadata` | map of string or number or boolean or list of any value or map of any value or null |  |  |

Example input:

```json
{
  "option_id": "019bb39d-1471-7070-8cc5-bf1cb17d9bf9",
  "title": "Shirt size"
}
```

### `product_option_value_delete` [#product_option_value_delete]

Delete one value of an option.

- Action key: `product_option_value.delete`
- Permission: `products.write`
- Approval: Always waits for a person to approve it.
- Effect: Changes the live store.
- Destructive: in compact mode it runs with `run_destructive_action`.
- Retries: safe to repeat with the same input.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `option_id` | string | yes | Product option ID from product_option_list |
| `value_id` | string | yes | Option value ID from product_option_value_list |

Example input:

```json
{
  "option_id": "019bb39d-1471-7070-8cc5-bf1cb17d9bf9",
  "value_id": "019bb3aa-7505-7a1f-84cc-94c44394c6ba"
}
```

### `product_option_value_update` [#product_option_value_update]

Change the text of one option value.

- Action key: `product_option_value.update`
- Permission: `products.write`
- Approval: Waits for approval when the store requires it for this action.
- Effect: Changes the live store.
- Retries: safe to repeat with the same input.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `option_id` | string | yes | Product option ID from product_option_list |
| `value_id` | string | yes | Option value ID from product_option_value_list |
| `value` | string |  |  |
| `metadata` | map of string or number or boolean or list of any value or map of any value or null |  |  |

Example input:

```json
{
  "option_id": "019bb39d-1471-7070-8cc5-bf1cb17d9bf9",
  "value_id": "019bb3aa-7505-7a1f-84cc-94c44394c6ba",
  "value": "Extra large"
}
```

### `product_options_link` [#product_options_link]

Add options to a product or take them off it, and add or remove values of its options.

add takes an existing option id, {option id, value_ids} to use some of its values, or a new option {title, values}. remove takes option ids to unlink. update adds or removes values of an option the product already has. The variants of the product are not changed: give a new option its values on each variant with product_variant_update.

- Action key: `product_options.link`
- Permission: `products.write`
- Approval: Waits for approval when the store requires it for this action.
- Effect: Changes the live store.
- Retries: runs at most once; a repeat with the same idempotency key returns the first result.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `product_id` | string | yes |  |
| `add` | list of string or object |  |  |
| `remove` | list of string |  |  |
| `update` | list of object |  |  |
| `update[].product_option_id` | string | yes |  |
| `update[].add` | list of string or object |  |  |
| `update[].remove` | list of string |  |  |

Example input:

```json
{
  "product_id": "019bb58e-0ec1-79c1-9f40-d39d8d07674b",
  "add": [
    {
      "title": "Size",
      "values": [
        "S",
        "M"
      ]
    }
  ]
}
```

### `product_variant_images_update` [#product_variant_images_update]

Link images of the product to a variant, or unlink them.

Image ids come from product_get include gallery. The images stay on the product.

- Action key: `product_variant_images.update`
- Permission: `products.write`
- Approval: Waits for approval when the store requires it for this action.
- Effect: Changes the live store.
- Retries: safe to repeat with the same input.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `product_id` | string | yes |  |
| `variant_id` | string | yes |  |
| `add` | list of string |  |  |
| `remove` | list of string |  |  |

Example input:

```json
{
  "product_id": "019bb58e-0ec1-79c1-9f40-d39d8d07674b",
  "variant_id": "019bb7f3-10ac-7f8b-b47e-f5cd71dff2e1",
  "add": [
    "019bb316-8a7c-75c0-9993-d174937500ba"
  ]
}
```