# Attach store logo (`attach_store_logo`)

Makes a staged upload the Store logo, which branded emails show, or the logo of the hosted Customiser Links page. Create the upload first with create_upload and purpose store_logo, send the bytes to its target, then pass its upload_id here. Only PNG, JPEG and WebP up to 2 MiB are accepted. Attaching replaces the current logo and deletes its file unless something else still uses it, so the call needs confirm: true. It requires the store:write scope and an idempotency_key, and supports dry_run.

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

## Purpose

Set or replace the Store logo or the Customiser Links page logo.

## Annotations

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

## Prerequisites

- An upload created with create_upload and purpose store_logo, whose bytes were sent to its target. Creating it also needs store:write.
- A merchant has connected this store and approved the store:write scope.

## Side effects

- Sets the logo and deletes the file it replaces, unless something else still uses it.
- Consumes the upload, which is single use.
- Claims the idempotency_key for at least 24 hours.

## Arguments

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `logo` | string | yes | Which logo to set: store for the Store logo that branded emails show, customiser_links for the hosted Customiser Links page logo. One of: `store`, `customiser_links`. |
| `upload_id` | string | yes | The id of an upload created with purpose store_logo, whose bytes have already been sent to its target. Each upload is single use. |
| `confirm` | boolean | unless `dry_run` is true | Must be true to apply the change, because attaching replaces the current logo and deletes its file unless something else still uses it. 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, the upload and its purpose are checked and the upload is not consumed 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 Store, or the Customiser Links page, as it now stands with logo_url set. A dry run returns the attach verdict and consumes nothing.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `request_id` | string | yes |  |
| `store` | object | yes |  |
| `store.id` | integer | yes |  |
| `store.name` | string | yes |  |
| `logo` | string | yes | The logo the call addressed. One of: `store`, `customiser_links`. |
| `resource` | object | no | The Store, or the Customiser Links page, as it now stands with logo_url set. 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 attach verdict. |

## Error cases

| Code | Recovery |
| --- | --- |
| `confirmation_required` | Send confirm: true. Attaching replaces the current logo and deletes its file unless something else still uses it. |
| `insufficient_scope` | The connection was approved without store:write. Ask the merchant to reconnect and approve it, or to remove the connector and add it again if the approval screen does not offer it. |
| `resource_not_found` | No upload with that id belongs to this store. Create one with create_upload. |
| `upload_already_attached` | The upload was already used. Create a new upload for each logo. |
| `upload_purpose_mismatch` | The upload was created for another purpose. Create a new upload with purpose store_logo. |
| `upload_rejected` | The bytes were not a readable PNG, JPEG or WebP image within 2 MiB. Create a new upload with a valid file. |

## Example: Set the Store logo

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "attach_store_logo",
    "arguments": {
      "logo": "store",
      "upload_id": "upl_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "confirm": true,
      "idempotency_key": "6b1f0c2a-3d4e-4f5a-8b6c-7d8e9f0a1b2c"
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "logo": "store",
      "resource": {
        "id": 12,
        "name": "Demo Signs",
        "logo_url": "https://cdn.signcustomiser.com/files/2f6c0b9e.png",
        "use_branding_for_emails": true
      },
      "idempotent_replay": false
    }
  }
}
```

## Example: An upload made for another purpose (error)

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "attach_store_logo",
    "arguments": {
      "logo": "customiser_links",
      "upload_id": "upl_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "dry_run": true
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "upload_purpose_mismatch",
        "title": "Upload purpose mismatch",
        "detail": "This slot accepts uploads created with purpose store_logo, and this upload was created with purpose option_image. Create a new upload with the purpose of the slot.",
        "recovery": "The upload was created for a different purpose. Start again at create_upload with the purpose this attachment needs.",
        "pointer": "/upload_id",
        "allowed_values": [
          "store_logo"
        ]
      }
    }
  }
}
```
