# Update customiser (`update_customiser`)

Applies a JSON merge patch to exactly one section of a customiser: its own metadata, its behavioural settings document, or its editable storefront labels. Only the fields present in the patch change, and a field the section does not accept is refused rather than ignored. The active state is not patchable here — set_customiser_status owns it. 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/
- Markdown URL: https://www.signcustomiser.com/help/mcp/tools/update_customiser.md
- MCP endpoint: https://web.signcustomiser.com/mcp
- Required scope: `customisers:write`
- Behaviour: write

## Purpose

Change a customiser name, styling mode, behavioural settings or storefront labels, one section at a time.

## Annotations

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

## Prerequisites

- A customiser id from list_customisers.
- The section current values, from get_customiser with the matching include, 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 named section of one customiser.
- Clears the customiser cached storefront configuration.

## Arguments

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `customiser_id` | integer | yes | The customiser id, from list_customisers. |
| `section` | string | yes | Which document to patch: customiser for the record own name and styling mode, settings for its behavioural configuration, labels for its editable storefront text. One of: `customiser`, `settings`, `labels`. |
| `patch` | object | yes | The RFC 7396 merge patch to apply. Only the members present change; a member set to null clears a nullable field. Read the section first with get_customiser so the patch is built against current values. |
| `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 section schema and the customiser pricing model 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 patched section as it now stands. 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 |  |
| `section` | string | yes | The section the patch was applied to. One of: `customiser`, `settings`, `labels`. |
| `customiser` | object | no | The customiser record, present only when section was customiser. |
| `settings` | object | no | The settings document, present only when section was settings. |
| `labels` | object | no | The labels document, present only when section was labels. |
| `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. |
| `links` | object | no | The merchant-admin page for the customiser. Absent on a dry run. |
| `links.admin_url` | string | yes |  |

## Error cases

| Code | Recovery |
| --- | --- |
| `insufficient_scope` | The connection was approved without customisers:write. |
| `resource_not_found` | No customiser with that id exists in this store. |
| `selection_mode_not_available` | This customiser or this store plan cannot offer the requested styling mode; the problem reason member says which. |
| `unknown_field` | The patch names a field this section does not have. Remove the field named by pointer. |
| `validation_failed` | A patched value is out of range or the wrong type, or active was sent to the customiser section, where it is read-only. |

## Example: Rename a customiser

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_customiser",
    "arguments": {
      "customiser_id": 42,
      "section": "customiser",
      "patch": {
        "name": "Neon sign builder v2"
      }
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "customiser_id": 42,
      "section": "customiser",
      "customiser": {
        "id": 42,
        "name": "Neon sign builder v2",
        "active": true,
        "pricing_model": "simple_letter",
        "pricing_model_display_name": "Simple Letter",
        "sign_category": "neon",
        "product_family": "neon",
        "selection_mode": "single_style",
        "created_at": "2026-08-13T00:00:00Z",
        "updated_at": "2026-08-24T00:05:00Z"
      },
      "links": {
        "admin_url": "https://web.signcustomiser.com/customisers/42"
      }
    }
  }
}
```

## Example: The active state is not patchable (error)

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_customiser",
    "arguments": {
      "customiser_id": 42,
      "section": "customiser",
      "patch": {
        "active": false
      }
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "validation_failed",
        "title": "Validation failed",
        "detail": "The request payload failed validation.",
        "recovery": "Correct every field listed in errors, using its pointer to locate the value and allowed_values where one is given, then call the tool again.",
        "pointer": "/active"
      }
    }
  }
}
```