Customisers

list_customisers

read

List customisers

Copy page

Discover what a Store sells and obtain the customiser ids the rest of the customiser surface takes.

Overview

Lists the Store customisers, the configurable sign products shoppers design on the storefront, and returns the integer customiser id every other customiser tool needs. Each row reports the customiser name, pricing model, sign category, product family, styling selection mode and whether it is active on the storefront. Results are paginated and always limited to the Store this connection was authorised for. 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

limitinteger

How many customisers to return per page, between 1 and 100. Defaults to 20.

cursorstring

The opaque next_cursor value from the previous page. Omit it for the first page and keep every filter identical between pages.

filterobject

Optional filters. An unknown filter is rejected, never ignored.

filter.activeboolean

Only return customisers that are, or are not, live on the storefront.

filter.pricing_modelstring

Only return customisers using this pricing model.

One of: simple_letter, advanced_letter, frame_fit

Result

Up to `limit` customiser rows in creation order, oldest first and stable across pages, plus the pagination cursor for the next page.

request_idstringalways present

storeobjectalways present

store.idintegeralways present

store.namestringalways present

customisersarray of objectalways present

The page of customisers, oldest first.

customisers[].idintegeralways present

customisers[].namestring or null

customisers[].activebooleanalways present

customisers[].pricing_modelstringalways present

One of: simple_letter, advanced_letter, frame_fit

customisers[].pricing_model_display_namestringalways present

customisers[].sign_categorystring or null

customisers[].product_familystring or null

customisers[].selection_modestringalways present

customisers[].updated_atstring or null

paginationobjectalways present

pagination.has_morebooleanalways present

pagination.next_cursorstring or null

Send this back as `cursor` with identical filters to read the next page.

Error cases

insufficient_scope

The connection was approved without customisers:read.

invalid_cursor

The cursor was altered or reused with different filters; restart with no cursor.

unsupported_value

A filter value is not one this API accepts; allowed_values lists the accepted set.

First page of the active customisers

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_customisers",
    "arguments": {
      "limit": 2,
      "filter": {
        "active": true
      }
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "customisers": [
        {
          "id": 42,
          "name": "Neon sign builder",
          "active": true,
          "pricing_model": "simple_letter",
          "pricing_model_display_name": "Simple Letter",
          "sign_category": "neon",
          "product_family": "neon",
          "selection_mode": "single_style",
          "updated_at": "2026-06-01T22:09:41Z"
        }
      ],
      "pagination": {
        "has_more": false,
        "next_cursor": null
      }
    }
  }
}

A pricing model that does not exist (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_customisers",
    "arguments": {
      "filter": {
        "pricing_model": "fixed_height"
      }
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "invalid_parameter",
        "title": "Invalid query parameter",
        "detail": "The filter[pricing_model] value is not a supported pricing model.",
        "recovery": "Correct the parameter named in parameter. Dates are YYYY-MM-DD in UTC and identifiers are integers between 1 and 2147483647.",
        "parameter": "filter[pricing_model]",
        "allowed_values": [
          "simple_letter",
          "advanced_letter",
          "frame_fit"
        ]
      }
    }
  }
}