Customisers

get_customiser_option_section

read

Get customiser option section

Copy page

Read the heading, the text and the step-wide switches of one option family step before changing them with update_customiser_option_section.

Overview

Reads the section of one option family of one customiser: the step heading and the text the customer customiser shows above that family options, plus the step-wide switches some families carry (the default border margin of sizes, the no-backlight choice of backlights, and whether the jacket step is hidden). The family is chosen with option_type, and one family is read per call. It requires the customisers:read scope, has no side effects and is safe to retry.

Permission

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

Annotations

readOnlyHinttrue

destructiveHintfalse

idempotentHinttrue

openWorldHintfalse

Prerequisites

A customiser id from list_customisers.
A merchant has connected this store and approved the customisers:read scope.

Arguments

customiser_idintegerrequired

The customiser id, from list_customisers.

option_typestringrequired

Which option family section to read. The values are the option_type values of the option tools for the twelve families that have a section.

One of: backboard, backlight, colour, font, icon, jacket, letter_type, material, mounting, mounting_colour, size, support_finish

Result

One section document with the field names the public API publishes for that family. A customiser that never saved the section reads title and description as null and every switch at its default. The document is a fixed set of fields, so its size does not grow with the number of options.

request_idstringalways present

storeobjectalways present

store.idintegeralways present

store.namestringalways present

customiser_idintegeralways present

option_typestringalways present

The family whose section was read.

One of: backboard, backlight, colour, font, icon, jacket, letter_type, material, mounting, mounting_colour, size, support_finish

sectionobjectalways present

The section document: title, description, the family own step-wide switches and updated_at. Its members are the ones update_customiser_option_section patches.

Error cases

insufficient_scope

The connection was approved without customisers:read.

resource_not_found

No customiser with that id belongs to this store. Call list_customisers to rediscover a valid id.

Read the sizes section

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_customiser_option_section",
    "arguments": {
      "customiser_id": 42,
      "option_type": "size"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "customiser_id": 42,
      "option_type": "size",
      "section": {
        "customiser_id": 42,
        "title": "Choose your size",
        "description": "Pick one of our sizes.",
        "border_margin_cm": 2.5,
        "border_margin_in": 0.984252,
        "authored_units": {
          "border_margin_cm": "centimetres"
        },
        "updated_at": "2026-05-04T09:12:31Z"
      }
    }
  }
}

A customiser that belongs to another store (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_customiser_option_section",
    "arguments": {
      "customiser_id": 987654,
      "option_type": "font"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "resource_not_found",
        "title": "Resource not found",
        "detail": "The requested resource does not exist or does not belong to the authenticated store.",
        "recovery": "The identifier does not exist in this store. Use the matching list tool to rediscover a valid id."
      }
    }
  }
}