# Product badges (/ai/reference/catalog/product-badges)

Toolset `product_badges`, 8 tools.

## Records [#records]

### `product_badge` [#product_badge]

A badge shown on product cards, such as New or Sale: the automatic ones turn on by rule (days or threshold) and the manual ones are assigned by hand. Listed in the order they show.

- Permission: `products.read`
- Tools: `product_badge_list`

### `product_badge_set` [#product_badge_set]

The badges one product shows and why: the manual picks, the automatic badges it earns and the ones left out. Pass the product id.

- Permission: `products.read`
- Tools: `product_badge_set_get`

## Actions [#actions]

### `product_badge_assign` [#product_badge_assign]

Put one manual badge on many products, or remove it from them.

- Action key: `product_badge.assign`
- 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 |
| --- | --- | --- | --- |
| `badge_id` | string | yes | Badge ID from product_badge_list |
| `product_ids` | list of string | yes | 1 to 500 items. at least 1 characters |
| `action` | string | yes | one of "add", "remove" |

Example input:

```json
{
  "badge_id": "019bb507-8a53-7211-ab8c-5b3e776af60f",
  "product_ids": [
    "019bb58e-0ec1-79c1-9f40-d39d8d07674b"
  ],
  "action": "add"
}
```

### `product_badge_create` [#product_badge_create]

Add a badge products can carry.

- Action key: `product_badge.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 |
| --- | --- | --- | --- |
| `label` | string | yes |  |
| `color` | string |  | Background colour, such as #d7263d |
| `text_color` | string or null |  |  |

Example input:

```json
{
  "label": "Handmade",
  "color": "#2b6cb0"
}
```

### `product_badge_delete` [#product_badge_delete]

Delete a badge and take it off every product.

- Action key: `product_badge.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 |
| --- | --- | --- | --- |
| `badge_id` | string | yes | Badge ID from product_badge_list |

Example input:

```json
{
  "badge_id": "019bb507-8a53-7211-ab8c-5b3e776af60f"
}
```

### `product_badge_reorder` [#product_badge_reorder]

Put the badges in the order they show on product cards.

- Action key: `product_badge.reorder`
- 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 |
| --- | --- | --- | --- |
| `ids` | list of string | yes | Every badge id, first shown first. at least 1 characters |

Example input:

```json
{
  "ids": [
    "019bb50a-b5b6-7132-a6bd-6261b886a31b",
    "019bb504-7fbb-7f64-acfd-075ffacb47ff"
  ]
}
```

### `product_badge_update` [#product_badge_update]

Change the label, colours or automatic rule of a badge.

enabled turns an automatic badge on or off; days and threshold set its rule (for example how many days a product counts as new).

- Action key: `product_badge.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 |
| --- | --- | --- | --- |
| `badge_id` | string | yes | Badge ID from product_badge_list |
| `label` | string |  |  |
| `color` | string |  |  |
| `text_color` | string or null |  |  |
| `enabled` | boolean |  |  |
| `days` | integer |  | at least -9007199254740991 |
| `threshold` | integer |  | at least -9007199254740991 |

Example input:

```json
{
  "badge_id": "019bb507-8a53-7211-ab8c-5b3e776af60f",
  "label": "New in",
  "days": 14
}
```

### `product_badges_set` [#product_badges_set]

Replace the manual badges of one product with this list.

Badges left out are taken off the product. Read product_badge_set_get first.

- Action key: `product_badges.set`
- 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 |  |
| `badge_ids` | list of string | yes | at least 1 characters |

Example input:

```json
{
  "product_id": "019bb58e-0ec1-79c1-9f40-d39d8d07674b",
  "badge_ids": [
    "019bb507-8a53-7211-ab8c-5b3e776af60f"
  ]
}
```