Customisers

update_customiser

write

Update customiser

Copy page

Change a customiser name, styling mode, behavioural settings or storefront labels, one section at a time.

Overview

Applies a JSON merge patch to exactly one section of a customiser: its own metadata, its behavioural settings document, or its editable storefront labels. Only the fields present in the patch change, and a field the section does not accept is refused rather than ignored. The active state is not patchable here — set_customiser_status owns it. It requires the customisers:write scope, takes an optional idempotency_key for replay, and supports dry_run.

Permission

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

Annotations

readOnlyHintfalse

destructiveHintfalse

idempotentHintfalse

openWorldHintfalse

Prerequisites

A customiser id from list_customisers.
The section current values, from get_customiser with the matching include, so the patch is built against what is there now.
A merchant has connected this store and approved the customisers:write scope.

Side effects

Changes the named section of one customiser.
Clears the customiser cached storefront configuration.

Arguments

customiser_idintegerrequired

The customiser id, from list_customisers.

sectionstringrequired

Which document to patch: customiser for the record own name and styling mode, settings for its behavioural configuration, labels for its editable storefront text.

One of: customiser, settings, labels

patchobjectrequired

The RFC 7396 merge patch to apply. Only the members present change; a member set to null clears a nullable field. Read the section first with get_customiser so the patch is built against current values.

idempotency_keystring

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_runboolean

When true, the patch is checked against the section schema and the customiser pricing model 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 patched section as it now stands. A dry run returns the update verdict instead and writes nothing.

request_idstringalways present

storeobjectalways present

store.idintegeralways present

store.namestringalways present

customiser_idintegeralways present

sectionstringalways present

The section the patch was applied to.

One of: customiser, settings, labels

customiserobject

The customiser record, present only when section was customiser.

settingsobject

The settings document, present only when section was settings.

labelsobject

The labels document, present only when section was labels.

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 update verdict.

linksobject

The merchant-admin page for the customiser. Absent on a dry run.

links.admin_urlstringalways present

Error cases

insufficient_scope

The connection was approved without customisers:write.

resource_not_found

No customiser with that id exists in this store.

selection_mode_not_available

This customiser or this store plan cannot offer the requested styling mode; the problem reason member says which.

unknown_field

The patch names a field this section does not have. Remove the field named by pointer.

validation_failed

A patched value is out of range or the wrong type, or active was sent to the customiser section, where it is read-only.

Rename a customiser

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_customiser",
    "arguments": {
      "customiser_id": 42,
      "section": "customiser",
      "patch": {
        "name": "Neon sign builder v2"
      }
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "customiser_id": 42,
      "section": "customiser",
      "customiser": {
        "id": 42,
        "name": "Neon sign builder v2",
        "active": true,
        "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"
      }
    }
  }
}

The active state is not patchable (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_customiser",
    "arguments": {
      "customiser_id": 42,
      "section": "customiser",
      "patch": {
        "active": false
      }
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "validation_failed",
        "title": "Validation failed",
        "detail": "The request payload failed validation.",
        "recovery": "Correct every field listed in errors, using its pointer to locate the value and allowed_values where one is given, then call the tool again.",
        "pointer": "/active"
      }
    }
  }
}