# Delete customiser option (`delete_customiser_option`)

Deletes one record from one customiser option family. The record is removed permanently and any stored file it owned is released, so the call requires confirm true and changes nothing without it. A delete that live records still depend on is refused with resource_in_use; calling with dry_run true first returns the same verdict without deleting anything. It requires the customisers:write scope and an idempotency_key.

- Source URL: https://www.signcustomiser.com/help/mcp/tools/delete_customiser_option/
- Markdown URL: https://www.signcustomiser.com/help/mcp/tools/delete_customiser_option.md
- MCP endpoint: https://web.signcustomiser.com/mcp
- Required scope: `customisers:write`
- Behaviour: destructive write

## Purpose

Take one option off a customiser after the merchant has agreed to it.

## Annotations

| Hint | Value |
| --- | --- |
| readOnlyHint | false |
| destructiveHint | true |
| idempotentHint | true |
| openWorldHint | false |

## Prerequisites

- A record id from list_customiser_options.
- The merchant explicit agreement, sent as confirm true.
- letter_type_id for the letter_part and letter_part_colour families, and letter_part as well for letter_part_colour.
- A merchant has connected this store and approved the customisers:write scope.

## Side effects

- Deletes one option record permanently and releases any stored file it owned.
- Removes the option from the storefront if the customiser is live.
- Clears the customiser cached storefront configuration.
- Claims the idempotency_key for at least 24 hours.

## Arguments

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `customiser_id` | integer | yes | The customiser id, from list_customisers. |
| `option_type` | string | yes | Which option family the record belongs to. One of: `backboard`, `backlight`, `colour`, `extra`, `font`, `form`, `icon`, `jacket`, `letter_type`, `letter_part`, `letter_part_colour`, `material`, `mounting`, `mounting_colour`, `preset`, `size`, `support_finish`, `legacy_fixed_height_size`. |
| `option_id` | integer or string | yes | The record identifier from list_customiser_options: an integer for every family except letter_part, which is addressed by its catalogue name such as face or halo. |
| `confirm` | boolean | no | Must be true to apply the change, because the record and any stored file it owned are removed permanently and cannot be restored through this connector. Without it the call returns a confirmation_required error and changes nothing. A dry run does not need it. |
| `letter_type_id` | integer | no | The letter type that owns the record, required for the letter_part and letter_part_colour families. |
| `letter_part` | string | no | The letter part that owns the colour, required for the letter_part_colour family. One of: `face`, `back`, `side`, `top`, `bottom`, `left`, `right`, `halo`, `trim`, `tube`. |
| `idempotency_key` | string | no | A client-generated key unique to this logical write, such as a UUID. Required: repeating the call with the same key and the same arguments replays the original result instead of writing twice, and the same key with different arguments is an idempotency_key_conflict. A dry run claims no key. |
| `dry_run` | boolean | no | When true, the deletion is checked against everything that still references the record is checked and nothing is written: the result is the same verdict the apply would have reached, and a problem the apply would have raised comes back as the same tool error. Defaults to false. |

## Result

The deleted record id and the record as it was. A dry run returns the delete verdict instead and deletes nothing.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `request_id` | string | yes |  |
| `store` | object | yes |  |
| `store.id` | integer | yes |  |
| `store.name` | string | yes |  |
| `customiser_id` | integer | yes |  |
| `option_type` | string | yes | One of: `backboard`, `backlight`, `colour`, `extra`, `font`, `form`, `icon`, `jacket`, `letter_type`, `letter_part`, `letter_part_colour`, `material`, `mounting`, `mounting_colour`, `preset`, `size`, `support_finish`, `legacy_fixed_height_size`. |
| `option_id` | integer or string | yes | The record identifier that was addressed. |
| `deleted` | boolean | no | True when the record was deleted. Absent on a dry run, where nothing is deleted. |
| `option` | object | no | The record as it was when it was deleted, from the deletion receipt, so the caller can report what it removed. |
| `dry_run` | boolean | no | Present and true only when dry_run was requested. |
| `valid` | boolean | no | Present only on a dry run, and always true: a failing dry run returns a tool error instead. |
| `verdict` | object | no | Present only on a dry run: the delete verdict. |

## Error cases

| Code | Recovery |
| --- | --- |
| `confirmation_required` | Send confirm true once the merchant has agreed to the deletion. Nothing was deleted. |
| `insufficient_scope` | The connection was approved without customisers:write. |
| `letter_part_cascade_blocked` | Records depending on this letter part must be removed first. |
| `missing_idempotency_key` | Send idempotency_key. It is required for this write. |
| `resource_in_use` | Live records still reference this option. Call again with dry_run true to enumerate them. |
| `resource_not_found` | No record with that id exists in that family of that customiser. |

## Example: Delete a colour the merchant confirmed

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "delete_customiser_option",
    "arguments": {
      "customiser_id": 42,
      "option_type": "colour",
      "option_id": 9,
      "confirm": true,
      "idempotency_key": "b8c9d0e1-2f3a-4b4c-9d5e-6f7081920314"
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "customiser_id": 42,
      "option_type": "colour",
      "option_id": 9,
      "deleted": true,
      "option": {
        "id": 9,
        "customiser_id": 42,
        "name": "Sunset Orange",
        "colour_type": "single",
        "hexcode": "#FF7A18"
      }
    }
  }
}
```

## Example: Without confirmation nothing is deleted (error)

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "delete_customiser_option",
    "arguments": {
      "customiser_id": 42,
      "option_type": "colour",
      "option_id": 9,
      "idempotency_key": "b8c9d0e1-2f3a-4b4c-9d5e-6f7081920314"
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "confirmation_required",
        "title": "Confirmation required",
        "detail": "Deleting colour record 9 removes it from the storefront permanently and releases any file it owned.",
        "recovery": "This operation changes something consequential. Send confirm: true once the merchant has agreed to it.",
        "parameter": "confirm",
        "allowed_values": [
          "true"
        ]
      }
    }
  }
}
```