Customisers

list_customiser_options

read

List customiser options

Copy page

Discover what a customiser offers in one option family, and obtain the record ids the option read and write tools take.

Overview

Lists the records in one option family of one customiser: the colours, fonts, sizes, materials, backboards, mountings, letter types, presets or other choices a shopper picks from. The family is chosen with the option_type argument, and exactly one family is read per call. Results are paginated, carry the field names the public API publishes, and are always limited to the connected Store. 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 customiser id from list_customisers.
letter_type_id for the letter_part and letter_part_colour families, and letter_part as well for letter_part_colour.
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 to read. Exactly one family is read per call; the value maps to the same per-family boundary the public API enforces.

One of: backboard, backlight, colour, extra, font, form, icon, jacket, letter_type, letter_part, letter_part_colour, material, mounting, mounting_colour, preset, size, support_finish, legacy_fixed_height_size

letter_type_idinteger

The letter type that owns the records, required for the letter_part and letter_part_colour families and rejected for every other family.

letter_partstring

The letter part whose colours to read, required for the letter_part_colour family. Which parts a letter type offers is that letter type own letter_parts list.

One of: face, back, side, top, bottom, left, right, halo, trim, tube

limitinteger

How many records to return per page, between 1 and 100. Defaults to 20. The letter_part family accepts no page size.

cursorstring

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

Result

Up to `limit` records of the requested family in the order the storefront presents them, plus the cursor for the next page. The letter_part family is a complete catalogue of one letter type and returns every record in one page.

request_idstringalways present

storeobjectalways present

store.idintegeralways present

store.namestringalways present

customiser_idintegeralways present

The customiser the records belong to.

option_typestringalways present

The family that was read.

optionsarray of objectalways present

The page of records, in the order the storefront presents them. Members are the family own public API fields; get_customiser_option returns the same record with its image slots resolved.

paginationobjectalways present

pagination.has_morebooleanalways present

pagination.next_cursorstring or null

Error cases

insufficient_scope

The connection was approved without customisers:read.

invalid_cursor

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

resource_not_found

No customiser or letter type with that id belongs to this store.

unknown_parameter

limit and cursor were sent to the letter_part family, which returns one complete page and accepts neither.

validation_failed

option_type was omitted or is not a family name, or a nested family was called without letter_type_id or letter_part.

First page of a customiser colours

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_customiser_options",
    "arguments": {
      "customiser_id": 42,
      "option_type": "colour",
      "limit": 1
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "customiser_id": 42,
      "option_type": "colour",
      "options": [
        {
          "id": 7,
          "name": "Warm White",
          "colour_type": "single",
          "hexcode": "#FFEEDD",
          "sort_order": 1,
          "base_price": 0,
          "currency": "USD"
        }
      ],
      "pagination": {
        "has_more": true,
        "next_cursor": "eyJpZCI6N30"
      }
    }
  }
}

A nested family called without its letter type (error)

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "validation_failed",
        "title": "Validation failed",
        "detail": "The letter type id field is required.",
        "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": "/letter_type_id"
      }
    }
  }
}