# Update customiser option section (`update_customiser_option_section`)

Applies a JSON merge patch to the section of one option family of one customiser: the step heading and text the customer customiser shows above that family options, and the step-wide switches some families carry (border_margin_cm on sizes, optional, optional_label and optional_default_none on backlights, hidden on jackets). Only the members present change, and a member the family section does not carry is refused. It requires the customisers:write scope, takes an optional idempotency_key for replay, and supports dry_run.

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

## Purpose

Change the heading, the text or a step-wide switch of one option family step in the customer customiser, one family at a time.

## Annotations

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

## Prerequisites

- A customiser id from list_customisers.
- The section current values, from get_customiser_option_section, so the patch is built against what is there now.
- A merchant has connected this store and approved the customisers:write scope.

## Side effects

- Changes the section of one option family of one customiser, creating the stored section on its first write.
- Writes title, description and optional_label as customiser text in the authoring language, replacing an unpublished Languages draft of the same text.
- Clears the customiser cached storefront configuration.

## Arguments

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `customiser_id` | integer | yes | The customiser id, from list_customisers. |
| `option_type` | string | yes | Which option family section to patch. The values are the option_type values of the option tools for the twelve families that have a section. One of: `backboard`, `backlight`, `colour`, `font`, `icon`, `jacket`, `letter_type`, `material`, `mounting`, `mounting_colour`, `size`, `support_finish`. |
| `patch` | object | yes | The RFC 7396 merge patch to apply. Every family accepts title and description; sizes add border_margin_cm (or border_margin_in with authored_units, and unit_revision), backlights add optional, optional_label and optional_default_none, and jackets add hidden. A member set to null clears a nullable field. Read the section first with get_customiser_option_section. |
| `idempotency_key` | string | no | An optional client-generated key unique to this logical write, such as a UUID. Repeating the call with the same key and the same arguments replays the original result; the route does not require one. |
| `dry_run` | boolean | no | When true, the patch is checked against the family section and the customiser sign type 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. A dry run claims no key. |

## Result

The patched section as it now stands, and the replaced Languages draft keys when the write replaced any. A dry run returns the update verdict instead and writes 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 | The family whose section was patched. One of: `backboard`, `backlight`, `colour`, `font`, `icon`, `jacket`, `letter_type`, `material`, `mounting`, `mounting_colour`, `size`, `support_finish`. |
| `section` | object | no | The section document as it now stands, with the members get_customiser_option_section returns. Absent on a dry run. |
| `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 update verdict. |
| `idempotent_replay` | boolean | no | True when this call replayed a previously recorded response for the same idempotency_key instead of applying the write again. |
| `replaced_drafts` | array of string | no | The translation keys of the unpublished Languages drafts that this write replaced in the authoring language. This member is present only when the write replaced a draft. Tell the merchant that the replaced draft is gone. |

## Error cases

| Code | Recovery |
| --- | --- |
| `conflicting_units` | border_margin_cm and border_margin_in disagree. Send one of them, or both with the exact projection. |
| `idempotency_subject_changed` | The customiser was deleted after the recorded update. Issue a new key and re-check the resource before writing again. |
| `insufficient_scope` | The connection was approved without customisers:write. |
| `option_family_not_supported` | The customiser sign type does not offer this family, so its section cannot be changed. |
| `rate_limited` | The store option-write budget is spent. Wait retry_after seconds. |
| `resource_not_found` | No customiser with that id exists in this store. |
| `stale_revision` | The Store unit preferences changed after the unit_revision the patch sent. Read the Store again and re-send the patch. |
| `unknown_field` | The patch names a member this family section does not carry, or a read-only member such as customiser_id or updated_at. Remove the field named by pointer. |
| `validation_failed` | A patched value is the wrong type or out of range, such as a title over 255 characters or a null hidden. The pointer names it. |

## Example: Rename the fonts step

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_customiser_option_section",
    "arguments": {
      "customiser_id": 42,
      "option_type": "font",
      "patch": {
        "title": "Choose your font"
      }
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "customiser_id": 42,
      "option_type": "font",
      "section": {
        "customiser_id": 42,
        "title": "Choose your font",
        "description": null,
        "updated_at": "2026-11-14T09:12:31Z"
      },
      "idempotent_replay": false
    }
  }
}
```

## Example: Check a backlights patch without writing it

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_customiser_option_section",
    "arguments": {
      "customiser_id": 42,
      "option_type": "backlight",
      "patch": {
        "optional": true,
        "optional_label": "No backlight"
      },
      "dry_run": true
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "customiser_id": 42,
      "option_type": "backlight",
      "dry_run": true,
      "valid": true,
      "verdict": {
        "operation": "update",
        "customiser_id": 42
      }
    }
  }
}
```

## Example: A family the sign type does not offer (error)

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_customiser_option_section",
    "arguments": {
      "customiser_id": 42,
      "option_type": "backlight",
      "patch": {
        "title": "Choose a backlight"
      }
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "option_family_not_supported",
        "title": "Option family not supported",
        "detail": "Backlights are offered only on cut-out metal signs. This customiser cannot create, change or reorder backlights; you can still read and delete existing ones.",
        "recovery": "The customiser sign type does not offer this option family, so it cannot be created, changed or reordered. Records left in it can still be read and deleted.",
        "pointer": ""
      }
    }
  }
}
```