Customisers

get_customiser_option

read

Get customiser option

Copy page

Read the current values of one option record before patching it, and see which of its asset slots are filled.

Overview

Reads one record of one customiser option family in full: every configured field for its family, and the asset slots it owns with their current public URLs. This is the call to make before an update, because the update tool takes a merge patch and needs the current values. 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 record id from list_customiser_options.
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 the record belongs to.

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

option_idinteger or stringrequired

The record identifier from list_customiser_options: an integer for every family except letter_part, which is addressed by its catalogue name such as face or halo.

letter_type_idinteger

The letter type that owns the record, required for the letter_part and letter_part_colour families.

letter_partstring

The letter part that owns the colour, required for the letter_part_colour family.

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

Result

One option record and its filled asset slots. Bounded to one record; no nested collections beyond the record own fields.

request_idstringalways present

storeobjectalways present

store.idintegeralways present

store.namestringalways present

customiser_idintegeralways present

option_typestringalways present

optionobjectalways present

The record, with the field names the public API publishes for its family.

imagesarray of objectalways present

The record filled asset slots. A slot the family offers but nothing is stored in is omitted, so an empty list means the record carries no assets.

images[].slotstringalways present

images[].urlstringalways present

Error cases

insufficient_scope

The connection was approved without customisers:read.

resource_not_found

No record with that id exists in that family of that customiser. Call list_customiser_options to rediscover a valid id.

validation_failed

option_type is not a family name, option_id is the wrong kind of identifier for that family, or a nested family was called without letter_type_id or letter_part.

Read one colour

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "customiser_id": 42,
      "option_type": "colour",
      "option": {
        "id": 7,
        "name": "Warm White",
        "colour_type": "single",
        "hexcode": "#FFEEDD",
        "sort_order": 1,
        "base_price": 0,
        "currency": "USD",
        "image_url": "https://assets.signcustomiser.com/colours/7.png"
      },
      "images": [
        {
          "slot": "image",
          "url": "https://assets.signcustomiser.com/colours/7.png"
        }
      ]
    }
  }
}

A letter part addressed with an integer (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_customiser_option",
    "arguments": {
      "customiser_id": 42,
      "option_type": "letter_part",
      "letter_type_id": 18,
      "option_id": 4
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "validation_failed",
        "title": "Validation failed",
        "detail": "The selected option id is invalid.",
        "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": "/option_id",
        "allowed_values": [
          "face",
          "back",
          "side",
          "top",
          "bottom",
          "left",
          "right",
          "halo",
          "trim",
          "tube"
        ]
      }
    }
  }
}