Customisers

list_customiser_prototypes

read

List customiser prototypes

Copy page

Discover which kinds of sign product this Store can create a customiser for, and get the prototype id that creation takes.

Overview

Lists the starting points a new customiser can be created from: each prototype stable id, its sign category, pricing model, sizing strategy, default styling mode, a one-line description of what it produces, and whether the connected Store plan makes it available. Creating a customiser takes one of these ids, so this is the discovery call that precedes it. The catalogue is complete and returned in one page. It requires the customisers:read scope and has no side effects.

Permission

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

Annotations

readOnlyHinttrue

destructiveHintfalse

idempotentHinttrue

openWorldHintfalse

Prerequisites

A merchant has connected this store and approved the customisers:read scope.

Arguments

This tool takes no arguments.

Result

The complete prototype catalogue in one page. It is a fixed server-owned list, so its size does not vary with the store.

request_idstringalways present

storeobjectalways present

store.idintegeralways present

store.namestringalways present

prototypesarray of objectalways present

The complete prototype catalogue.

prototypes[].idstringalways present

The stable prototype id a creation call takes.

prototypes[].namestringalways present

prototypes[].descriptionstring or null

prototypes[].default_customiser_namestring or null

prototypes[].sign_categorystring or null

The kind of sign the prototype produces. Expected to grow: tolerate unknown values.

prototypes[].pricing_modelstringalways present

One of: simple_letter, advanced_letter, frame_fit

prototypes[].sizing_strategystring or null

prototypes[].selection_modestring or null

prototypes[].ai_sign_designerboolean or null

prototypes[].availablebooleanalways present

Whether this Store plan allows a customiser to be created from the prototype.

prototypes[].unavailable_reasonsarray of stringalways present

Why the prototype is unavailable, empty when it is available.

paginationobjectalways present

Always reports no further pages: the catalogue is one complete collection.

pagination.has_morebooleanalways present

pagination.next_cursorstring or null

Error cases

insufficient_scope

The connection was approved without customisers:read.

unknown_parameter

This route accepts no query parameters, so the tool takes no arguments.

Read the prototype catalogue

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_customiser_prototypes",
    "arguments": {}
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "prototypes": [
        {
          "id": "neon-frame-fit",
          "name": "Neon Letter Signs - Price per square metre/foot",
          "description": "Neon and Flex LED neon letter signs.",
          "default_customiser_name": "Neon Sign Customiser",
          "sign_category": "neon",
          "pricing_model": "frame_fit",
          "sizing_strategy": null,
          "selection_mode": "per_word",
          "ai_sign_designer": false,
          "available": true,
          "unavailable_reasons": []
        }
      ],
      "pagination": {
        "has_more": false,
        "next_cursor": null
      }
    }
  }
}

A connection without customisers:read (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_customiser_prototypes",
    "arguments": {}
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "insufficient_scope",
        "title": "Insufficient scope",
        "detail": "The tool [list_customiser_prototypes] requires the customisers:read scope, which this connection was not granted.",
        "recovery": "The connection was authorised without the scope this tool needs. Ask the merchant to reconnect the connector and approve the scope named in required_scopes. Do not retry this call.",
        "required_scopes": [
          "customisers:read"
        ],
        "granted_scopes": [
          "store:read"
        ]
      }
    }
  }
}