Customiser icons

Update an icon

Copy page

Applies an RFC 7396 JSON Merge Patch to one icon: properties omitted from the body are unchanged, and null clears min_height_cm. Read-only and unknown fields are rejected.

PATCH/api/v3/customisers/{customiser_id}/icons/{icon_id}

Update an icon

Applies an RFC 7396 JSON Merge Patch to one icon: properties omitted from the body are unchanged, and `null` clears `min_height_cm`. Read-only and unknown fields are rejected. An empty object `{}` is a valid no-op. Requires `customisers:write`. Sending `svg` re-runs the whole server-side pass — sanitise, convert, rebuild the font — and replaces `rendered_svg` and the icon's code point. Renaming an icon or changing its minimum height does none of that, so it costs nothing and cannot fail on the converter. An `Idempotency-Key` is optional here: sending one makes the update safe to retry (an exact repeat replays the original response; the same key with a different body is a 409). The update clears the customiser's cached storefront configuration and runs the advisory language sync, and never regenerates Shopify products, product images, or the product cache.

Update an icon

Overview

An empty object {} is a valid no-op. Requires customisers:write. Sending svg re-runs the whole server-side pass — sanitise, convert, rebuild the font — and replaces rendered_svg and the icon's code point. Renaming an icon or changing its minimum height does none of that, so it costs nothing and cannot fail on the converter. An Idempotency-Key is optional here: sending one makes the update safe to retry (an exact repeat replays the original response; the same key with a different body is a 409). The update clears the customiser's cached storefront configuration and runs the advisory language sync, and never regenerates Shopify products, product images, or the product cache.

Authorisation

Bearer token required. Include it in the Authorization header.

Required scope: customisers:write

Path parameters

customiser_idstringpathrequired

The customiser id.

Example: 1

icon_idstringpathrequired

The icon id.

Example: 9

Request body

namestringbody

svgstringbody

min_height_cmintegerbody

Request body example

{
  "name": "Heart",
  "svg": "<svg viewBox=\"0 0 24 24\"><circle cx=\"12\" cy=\"12\" r=\"8\"/></svg>",
  "min_height_cm": 6
}

Update an icon

curl https://web.signcustomiser.com/api/v3/customisers/1/icons/9 \
  --request PATCH \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Heart",
  "svg": "<svg viewBox=\"0 0 24 24\"><circle cx=\"12\" cy=\"12\" r=\"8\"/></svg>",
  "min_height_cm": 6
}'

{
  "data": {
    "object": "icon",
    "id": 9,
    "customiser_id": 42,
    "name": "Heart",
    "svg": "<svg viewBox=\"0 0 24 24\"><circle cx=\"12\" cy=\"12\" r=\"8\"/></svg>",
    "rendered_svg": "<svg viewBox=\"0 0 24 24\"><circle cx=\"12\" cy=\"12\" r=\"8\"/></svg>",
    "min_height_cm": 6,
    "icon_font": {
      "glyph_code": "f101",
      "font_family": "icon-font-a1b2c3d4",
      "ttf_url": "https://cdn.signcustomiser.com/icon-fonts/icons.ttf"
    },
    "sort_order": 1,
    "created_at": "2026-08-13T00:00:00Z",
    "updated_at": "2026-08-13T00:05:00Z"
  },
  "links": {
    "self": "https://web.signcustomiser.com/api/v3/customisers/42/icons/9",
    "documentation": "https://www.signcustomiser.com/help/api/"
  },
  "meta": {
    "api_version": "v3",
    "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
  }
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/malformed_json",
  "title": "Malformed JSON",
  "status": 400,
  "code": "malformed_json",
  "detail": "The request body is not valid JSON: Syntax error.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/missing_api_key",
  "title": "Missing API key",
  "status": 401,
  "code": "missing_api_key",
  "detail": "Provide a store API key as a bearer token.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This operation requires the customisers:write scope.",
  "required_scopes": [
    "customisers:write"
  ],
  "granted_scopes": [
    "customisers:read"
  ],
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/resource_not_found",
  "title": "Resource not found",
  "status": 404,
  "code": "resource_not_found",
  "detail": "The requested resource does not exist or does not belong to the authenticated store.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/idempotency_key_conflict",
  "title": "Idempotency key conflict",
  "status": 409,
  "code": "idempotency_key_conflict",
  "detail": "This Idempotency-Key was already used for a different request body on this operation.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/request_too_large",
  "title": "Request too large",
  "status": 413,
  "code": "request_too_large",
  "detail": "The request body must not exceed 2 MiB.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/validation_failed",
  "title": "Validation failed",
  "status": 422,
  "code": "validation_failed",
  "detail": "The request payload failed validation.",
  "errors": [
    {
      "pointer": "/rendered_svg",
      "code": "prohibited",
      "detail": "The rendered_svg field is prohibited."
    }
  ],
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/rate_limited",
  "title": "Too many requests",
  "status": 429,
  "code": "rate_limited",
  "detail": "You have exceeded the request limit for this API key.",
  "retry_after": 37,
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/icon_conversion_failed",
  "title": "Icon conversion failed",
  "status": 502,
  "code": "icon_conversion_failed",
  "detail": "The icon converter could not prepare this drawing, so nothing was written.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}