Customisers

preview_customiser_icon

read

Preview customiser icon

Copy page

Check how a drawing will look as a customiser icon before creating the icon with create_customiser_option and option_type icon.

Overview

Shows what the icon converter makes of one SVG drawing for a customiser before an icon is created from it: the drawing is sanitised, converted by the icon service and sanitised again, and the answer is the SVG an icon create would store as rendered_svg. Nothing is saved. It requires the customisers:read scope and has its own per-connection rate limit, separate from the option-write budget.

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 single SVG document of at most 512 KiB.
A merchant has connected this store and approved the customisers:read scope.

Arguments

customiser_idintegerrequired

The customiser id, from list_customisers.

svgstringrequired

The drawing to preview, as one SVG document of at most 512 KiB. Scripts, event handlers and external references are removed before conversion.

Result

The customiser id and the converted SVG. The SVG is at most the size of the drawing the converter returns for one icon.

request_idstringalways present

storeobjectalways present

store.idintegeralways present

store.namestringalways present

customiser_idintegeralways present

svgstringalways present

The sanitised, converted drawing: what an icon create would store as rendered_svg.

Error cases

icon_conversion_failed

The icon service could not be reached or could not convert the drawing. Nothing was saved; call the tool again.

insufficient_scope

The connection was approved without customisers:read.

rate_limited

The icon preview limit for this connection is spent. Wait retry_after seconds.

resource_not_found

No customiser with that id exists in this store.

validation_failed

The svg argument is not one SVG document, or nothing is left of it once scripts, event handlers and external references are removed (error code invalid_svg on /svg). Send a plain vector drawing.

Preview a square icon

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "preview_customiser_icon",
    "arguments": {
      "customiser_id": 42,
      "svg": "<svg viewBox=\"0 0 24 24\"><path d=\"M4 4h16v16H4z\"/></svg>"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "customiser_id": 42,
      "svg": "<svg viewBox=\"0 0 24 24\"><path d=\"M4 4h16v16H4z\"/></svg>"
    }
  }
}

A drawing with nothing safe left in it (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "preview_customiser_icon",
    "arguments": {
      "customiser_id": 42,
      "svg": "<script>alert(1)</script>"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "validation_failed",
        "title": "Validation failed",
        "detail": "The icon SVG could not be sanitised safely: nothing was left of it once scripts, event handlers, and external references were removed. Send a plain vector drawing.",
        "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": "/svg"
      }
    }
  }
}