Customisers

delete_customiser

destructive write

Delete customiser

Copy page

Remove a customiser from the Store after the merchant has agreed to it.

Overview

Deletes a customiser and withdraws it from the storefront. The deletion is recoverable for a period through set_customiser_status with restore, but it takes the sign product off sale immediately and ends any storefront design in progress, so the call requires confirm true and changes nothing without it. Calling with dry_run true first reports whether the deletion would be allowed without deleting anything. It requires the customisers:write scope and an idempotency_key.

Permission

Requires thecustomisers:writepermission. A connection without it answersinsufficient_scopenaming the permission to approve.

Annotations

readOnlyHintfalse

destructiveHinttrue

idempotentHinttrue

openWorldHintfalse

Prerequisites

A customiser id from list_customisers.
The merchant explicit agreement, sent as confirm true.
A merchant has connected this store and approved the customisers:write scope.

Side effects

Deletes one customiser and withdraws it from the storefront immediately.
Ends any storefront design in progress against it.
Claims the idempotency_key for at least 24 hours.

Arguments

customiser_idintegerrequired

The customiser id, from list_customisers.

confirmboolean

Must be true to apply the change, because the sign product leaves the storefront immediately and any design in progress against it ends. Without it the call returns a confirmation_required error and changes nothing. A dry run does not need it.

idempotency_keystring

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_runboolean

When true, the deletion is checked against everything that still references the customiser 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 deleted customiser id and the record as it was. A dry run returns the delete verdict instead and deletes nothing.

request_idstringalways present

storeobjectalways present

store.idintegeralways present

store.namestringalways present

customiser_idintegeralways present

deletedboolean

True when the customiser was deleted. Absent on a dry run, where nothing is deleted.

customiserobject

The customiser as it was when it was deleted, from the deletion receipt, so the caller can report what it removed.

dry_runboolean

Present and true only when dry_run was requested.

validboolean

Present only on a dry run, and always true: a failing dry run returns a tool error instead.

verdictobject

Present only on a dry run: the delete verdict.

Error cases

confirmation_required

Send confirm true once the merchant has agreed to the deletion. Nothing was deleted.

insufficient_scope

The connection was approved without customisers:write.

missing_idempotency_key

Send idempotency_key. It is required for this write.

resource_in_use

Other records still reference this customiser. Call again with dry_run true to enumerate them.

resource_not_found

No customiser with that id exists in this store.

resource_state_conflict

The customiser is not in a state that allows deletion.

Delete a customiser the merchant confirmed

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "delete_customiser",
    "arguments": {
      "customiser_id": 42,
      "confirm": true,
      "idempotency_key": "e5f6a7b8-9c0d-4e1f-8a2b-3c4d5e6f7081"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "customiser_id": 42,
      "deleted": 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"
      }
    }
  }
}

Without confirmation nothing is deleted (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "delete_customiser",
    "arguments": {
      "customiser_id": 42,
      "idempotency_key": "e5f6a7b8-9c0d-4e1f-8a2b-3c4d5e6f7081"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "confirmation_required",
        "title": "Confirmation required",
        "detail": "Deleting customiser 42 takes the sign product off the storefront immediately.",
        "recovery": "This operation changes something consequential. Send confirm: true once the merchant has agreed to it.",
        "parameter": "confirm",
        "allowed_values": [
          "true"
        ]
      }
    }
  }
}