# Replace customiser label images (`replace_customiser_label_images`)

Replaces one image list of a customiser whole, in order. list background_images is the Scene Editor background photographs shoppers preview their sign against: each row sends upload_id (a background_image upload) or image_url (an image the list holds, from get_customiser include labels), with width_cm and height_cm, sign_area, linked_size_ids, is_default_background and an optional mobile version; send revision, the labels background_images_revision. list additional_information is the Review Screen cards: each row has header, description and optionally upload_id (a label_image upload) or image_url. An image the list no longer holds is deleted, so the call requires confirm true. It requires the customisers:write scope and an idempotency_key, and supports dry_run.

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

## Purpose

Set the photographs the storefront previews a sign against, or the cards shown on the Review Screen.

## Annotations

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

## Prerequisites

- A customiser id from list_customisers, and its current list from get_customiser with include labels.
- For a new image, an upload from create_upload (purpose background_image or label_image) whose bytes are already sent.
- The merchant explicit agreement, sent as confirm true.
- A merchant has connected this store and approved the customisers:write scope.

## Side effects

- Replaces the whole list. Rows left out are removed, and their images are deleted.
- Consumes each upload: each upload is single use.
- Clears the customiser cached storefront configuration.
- Spends one unit of the store option-write budget.
- Claims the idempotency_key for at least 24 hours.

## Arguments

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `customiser_id` | integer | yes | The customiser id, from list_customisers. |
| `list` | string | yes | Which list to replace. One of: `background_images`, `additional_information`. |
| `items` | array of object | yes | The whole list, in order, with the row fields the tool description names. Send [] to empty it. |
| `revision` | integer | no | Required for background_images: the labels background_images_revision. Not sent for additional_information. |
| `confirm` | boolean | unless `dry_run` is true | Must be true to apply the change, because rows left out of the list are removed and their images deleted. Without it the call returns a confirmation_required error and changes nothing. |
| `idempotency_key` | string | unless `dry_run` is true | 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. |
| `dry_run` | boolean | no | When true, every row and upload 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 list as it now stands (and its new revision for background_images). A dry run returns the verdict and consumes nothing.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `request_id` | string | yes |  |
| `store` | object | yes |  |
| `store.id` | integer | yes |  |
| `store.name` | string | yes |  |
| `customiser_id` | integer | yes |  |
| `list` | string | yes | One of: `background_images`, `additional_information`. |
| `result` | object | no | The list as it now stands, and revision for background_images. Absent on a dry run. |
| `idempotent_replay` | boolean | no | True when this call replayed a previously recorded response for the same idempotency_key instead of applying the write again. |
| `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 verdict. |

## Error cases

| Code | Recovery |
| --- | --- |
| `confirmation_required` | Send confirm true once the merchant has agreed to the new list. Nothing changed. |
| `insufficient_scope` | The connection was approved without customisers:write. |
| `rate_limited` | The store option-write budget is spent. Wait retry_after seconds. |
| `resource_not_found` | No customiser with that id belongs to this store. |
| `stale_revision` | The background list changed after it was read. Read get_customiser with include labels again and send its background_images_revision as revision. |
| `upload_already_attached` | Each upload is single use and this one is spent. Create a new upload. |
| `upload_not_found` | An upload_id is unknown, spent or from another store. The pointer names the row. Create a new upload. |
| `upload_purpose_mismatch` | The upload was created for another purpose. Background images take background_image; cards take label_image. |
| `validation_failed` | A row is not valid, for example an image_url the list does not hold. The pointer names it. |

## Example: Replace the Review Screen cards

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "replace_customiser_label_images",
    "arguments": {
      "customiser_id": 42,
      "list": "additional_information",
      "items": [
        {
          "header": "Free express shipping",
          "description": "Every sign ships free, worldwide.",
          "upload_id": "upl_9f2c4b7ad13e6058ba41cd4201"
        }
      ],
      "confirm": true,
      "idempotency_key": "f6a7b8c9-d0e1-4f2a-9b3c-4d5e6f7a8b9c"
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "customiser_id": 42,
      "list": "additional_information",
      "result": {
        "additional_information": [
          {
            "header": "Free express shipping",
            "description": "Every sign ships free, worldwide.",
            "image_url": "https://cdn.signcustomiser.com/files/shipping.png"
          }
        ]
      },
      "idempotent_replay": false
    }
  }
}
```

## Example: An unknown upload id (error)

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "replace_customiser_label_images",
    "arguments": {
      "customiser_id": 42,
      "list": "background_images",
      "revision": 3,
      "items": [
        {
          "upload_id": "upl_00000000000000000000000000",
          "width_cm": 150,
          "height_cm": 100
        }
      ],
      "dry_run": true
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "upload_not_found",
        "title": "Upload not found",
        "detail": "No pending upload with this id belongs to this store.",
        "recovery": "No pending upload with that id belongs to this store. Create a new upload with create_upload and send its id.",
        "pointer": "/background_images/0/upload_id"
      }
    }
  }
}
```
