# Set customiser status (`set_customiser_status`)

Moves a customiser between storefront states: activate publishes it to shoppers, deactivate withdraws it while keeping its configuration, and restore brings back a customiser that was deleted but is still inside its recovery window. Activation runs the same readiness guard the merchant admin runs, so a customiser that is not ready is refused with the reason rather than published broken. Every transition has an inverse. It requires the customisers:write scope and an idempotency_key, and supports dry_run.

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

## Purpose

Publish a customiser to the storefront, withdraw it, or bring a deleted one back.

## Annotations

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

## Prerequisites

- A customiser id from list_customisers.
- For restore, a customiser deleted by delete_customiser and still inside its recovery window.
- A merchant has connected this store and approved the customisers:write scope.

## Side effects

- Changes whether one customiser is live on the storefront, or brings a deleted one back.
- Clears the customiser cached storefront configuration.
- Claims the idempotency_key for at least 24 hours.

## Arguments

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `customiser_id` | integer | yes | The customiser id, from list_customisers. |
| `transition` | string | yes | Which transition to apply: activate publishes the customiser, deactivate withdraws it, restore brings a deleted one back. One of: `activate`, `deactivate`, `restore`. |
| `idempotency_key` | string | no | 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. A dry run claims no key. |
| `dry_run` | boolean | no | When true, the transition is checked against the customiser current state and its activation readiness 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 transition applied and the customiser as it now stands. A dry run returns the transition verdict instead and changes nothing.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `request_id` | string | yes |  |
| `store` | object | yes |  |
| `store.id` | integer | yes |  |
| `store.name` | string | yes |  |
| `customiser_id` | integer | yes |  |
| `transition` | string | yes | The transition that was requested. One of: `activate`, `deactivate`, `restore`. |
| `applied` | boolean | no | True when the transition was applied. Absent on a dry run, where nothing is applied. |
| `customiser` | object | no | The customiser as it now stands, with the fields get_customiser publishes. Read active to see the result; no deleted_at is published on this surface. |
| `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 transition 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. |
| `missing_idempotency_key` | Send idempotency_key. It is required for this write. |
| `resource_not_found` | No customiser with that id exists in this store. |
| `resource_state_conflict` | The customiser is already in that state, or is outside the window restore allows. |
| `validation_failed` | Activation readiness failed: the customiser is missing options it needs before shoppers can design with it. |

## Example: Withdraw a customiser from the storefront

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "set_customiser_status",
    "arguments": {
      "customiser_id": 42,
      "transition": "deactivate",
      "idempotency_key": "c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f"
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "customiser_id": 42,
      "transition": "deactivate",
      "applied": true,
      "customiser": {
        "id": 42,
        "name": "Neon sign builder",
        "active": false,
        "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: Restoring a customiser that was never deleted (error)

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "set_customiser_status",
    "arguments": {
      "customiser_id": 42,
      "transition": "restore",
      "idempotency_key": "d4e5f6a7-8b9c-4d0e-9f1a-2b3c4d5e6f70"
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "resource_state_conflict",
        "title": "Resource state conflict",
        "detail": "This customiser is not deleted.",
        "recovery": "The resource is not in a state this transition allows. Read it first and choose the transition its current state permits."
      }
    }
  }
}
```