# Update customiser text template (`update_customiser_text_template`)

Replaces a customiser text template (its fixed lines, and on cut-out metal with Frame Fit its graphic areas, production artwork, mounting holes and manufacturing rules) with a whole new document, or removes it when template is null. Template lengths are millimetres. Send the revision read from get_customiser with include text_template; a stale revision is refused. Production and graphic artwork come from import_customiser_text_template_artwork. It requires the customisers:write scope, takes an optional idempotency_key, supports dry_run, and a removal requires confirm: true.

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

## Purpose

Set up or change the fixed text fields of a customiser, or remove them.

## Annotations

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

## Prerequisites

- A customiser id from list_customisers.
- The current text_template from get_customiser, for its revision and the document to change.
- A merchant has connected this store and approved the customisers:write scope.

## Side effects

- Changes the customer customiser at once, and clears its cached configuration.
- Writes line labels, default wording and area descriptions in the authoring language.

## Arguments

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `customiser_id` | integer | yes | The customiser id, from list_customisers. |
| `revision` | integer or null | yes | The template revision you read, or null when the customiser has none. |
| `template` | object or null | yes | The whole template as get_customiser returns it in text_template.template, changed and without key and revision; null removes the template. New lines and areas send id null. |
| `confirm` | boolean | no | Must be true to apply the change, because removing the template takes the text fields off the customer customiser. Without it the call returns a confirmation_required error and changes nothing. |
| `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 replacement or removal 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. A dry run does not require the confirm argument. |

## Result

The text template document as it now stands, the shape get_customiser returns in text_template. A dry run returns the validation verdict 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 |  |
| `text_template` | object | no | The text template document as it now stands. 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 validation verdict. |
| `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. |
| `idempotent_replay` | boolean | no | True when this call replayed a previously recorded response for the same idempotency_key instead of applying the write again. |

## Error cases

| Code | Recovery |
| --- | --- |
| `confirmation_required` | Send confirm: true to remove the template. |
| `insufficient_scope` | The connection was approved without customisers:write. |
| `stale_revision` | The template changed after it was read. Read it again with get_customiser, reapply the change, and send its revision. |
| `text_template_unavailable` | Text fields are not available for this Store. |
| `text_template_unsupported_sign` | Only LED neon and cut-out metal with Frame Fit carry text fields. |
| `text_template_unsupported_sizing` | Add a width-based size on the Sizes page that the price list covers, then retry. |
| `unknown_field` | Remove the key named by pointer; read-only key and revision belong outside template. |
| `validation_failed` | A rule of the document is broken. Each error names the rule code and the pointer to fix. |

## Example: Remove a template

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_customiser_text_template",
    "arguments": {
      "customiser_id": 42,
      "revision": 3,
      "template": null,
      "confirm": true
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "idempotent_replay": false,
      "customiser_id": 42,
      "text_template": {
        "customiser_id": 42,
        "availability": "available",
        "sign_kind": "neon",
        "template": null,
        "offered_sizes": {
          "presets": [
            {
              "size_id": 7,
              "width_cm": 60,
              "width_in": 23.6220472,
              "authored_units": {
                "width_cm": "centimetres"
              }
            }
          ],
          "custom": null,
          "custom_minimum_set": false,
          "dropped": []
        }
      }
    }
  }
}
```

## Example: A removal without confirmation changes nothing (error)

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_customiser_text_template",
    "arguments": {
      "customiser_id": 42,
      "revision": 3,
      "template": null
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "confirmation_required",
        "title": "Confirmation required",
        "detail": "Removing the text template takes its text fields off the customer customiser.",
        "recovery": "This operation changes something consequential. Send confirm: true once the merchant has agreed to it.",
        "parameter": "confirm",
        "allowed_values": [
          "true"
        ]
      }
    }
  }
}
```
