Customisers

create_customiser

write

Create customiser

Copy page

Add a new configurable sign product to the Store, starting from a prototype rather than from nothing.

Overview

Creates a customiser in the connected Store from one of the prototype ids list_customiser_prototypes returns, optionally naming it. The prototype fixes the pricing model, sign category and sizing strategy, and the new customiser is populated with that prototype demo configuration. Whether it goes live is decided by the store activation quota, so read active back rather than assuming it. It requires the customisers:write scope and an idempotency_key, and supports dry_run.

Permission

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

Annotations

readOnlyHintfalse

destructiveHintfalse

idempotentHinttrue

openWorldHintfalse

Prerequisites

A prototype id from list_customiser_prototypes whose available member is true.
A merchant has connected this store and approved the customisers:write scope.

Side effects

Creates one customiser in the Store, populated with the prototype demo configuration.
May publish it to the storefront immediately, if the store activation quota has room.
Claims the idempotency_key for at least 24 hours.

Arguments

prototypestringrequired

The prototype id to build from, as returned in the id member of list_customiser_prototypes.

namestring

The customiser name. Defaults to the prototype own default_customiser_name.

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 create is checked against the prototype and the store plan 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 created customiser record, and whether the call replayed an earlier one. A dry run returns the create verdict instead, including whether the customiser would be live.

request_idstringalways present

storeobjectalways present

store.idintegeralways present

store.namestringalways present

customiserobject

The created customiser, with the fields get_customiser publishes. Absent on a dry run.

idempotent_replayboolean

True when this call replayed an earlier write carrying the same idempotency_key rather than creating a second customiser.

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 create verdict, including will_be_active.

linksobject

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

links.admin_urlstringalways present

Error cases

idempotency_key_conflict

That key was used with different arguments. Re-send the original arguments or issue a new key.

insufficient_scope

The connection was approved without customisers:write.

missing_idempotency_key

Send idempotency_key. It is required for this write.

prototype_not_available

The store plan does not include that prototype; unavailable_reasons says why.

prototype_not_found

No prototype has that id. Call list_customiser_prototypes and send an id it returns.

Create a neon customiser

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_customiser",
    "arguments": {
      "prototype": "neon-frame-fit",
      "name": "Neon sign builder",
      "idempotency_key": "b2c3d4e5-6f70-4a8b-9c0d-1e2f3a4b5c6d"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "customiser": {
        "id": 42,
        "name": "Neon sign builder",
        "active": true,
        "pricing_model": "frame_fit",
        "pricing_model_display_name": "Frame Fit",
        "sign_category": "neon",
        "product_family": "neon",
        "selection_mode": "per_word",
        "created_at": "2026-08-24T00:00:00Z",
        "updated_at": "2026-08-24T00:00:00Z"
      },
      "idempotent_replay": false,
      "links": {
        "admin_url": "https://web.signcustomiser.com/customisers/42"
      }
    }
  }
}

A prototype id that does not exist (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_customiser",
    "arguments": {
      "prototype": "neon",
      "idempotency_key": "b2c3d4e5-6f70-4a8b-9c0d-1e2f3a4b5c6d"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "validation_failed",
        "title": "Validation failed",
        "detail": "There is no prototype with id \"neon\".",
        "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": "/prototype"
      }
    }
  }
}