Customiser settings

Update customiser settings

Copy page

Partially update the customiser's settings with a JSON Merge Patch (RFC 7396) of the document the read operation returns: the request body is a JSON object containing only the properties to change.

PATCH/api/v3/customisers/{customiser_id}/settings

Update customiser settings

Partially update the customiser's settings with a JSON Merge Patch (RFC 7396) of the document the read operation returns: the request body is a JSON object containing only the properties to change. Properties omitted from the patch are unchanged, a null value clears a property that can hold null, `selection_order` replaces wholesale (send every step to reorder one), and an empty object `{}` is a valid no-op. Every property the read publishes is patchable except the read-only descriptors (`object`, `customiser_id`, `currency`, `updated_at`), and a property this resource does not define is refused with a JSON Pointer rather than ignored, so a typo can never silently change meaning. Requires the `customisers:write` scope. A successful update immediately changes the storefront: the customiser's cached configuration is invalidated and translated language content is resynchronised. It never regenerates your Shopify products, product images, or product cache. Send an `Idempotency-Key` header (1-255 visible ASCII characters, e.g. a UUID) to make the write safe to retry: repeating the same key with the same body replays the original response (marked `Idempotency-Replay: true`) without executing again; the same key with a different body is a 409 problem with code `idempotency_key_conflict`. The header is optional here, as on the option families' update operations. Validation failures are 422 problems: `validation_failed` lists every field error in `errors[]` with a JSON `pointer` and, for closed-set violations, the `allowed_values`; `unknown_field` means the body names properties outside the document. The sign minimum, initial, and maximum dimensions are checked against the document the patch would leave behind, so clearing one end of a range is refused exactly as an impossible value is. `icon_font_tier_id` and `icon_length_pricing_id` must name records of this customiser. A 400 problem means the body is not valid JSON or the `Idempotency-Key` header is malformed. 401/403/404/429 behave as on the read operation, with `customisers:write` as the required scope.

Update customiser settings

Overview

Properties omitted from the patch are unchanged, a null value clears a property that can hold null, selection_order replaces wholesale (send every step to reorder one), and an empty object {} is a valid no-op. Every property the read publishes is patchable except the read-only descriptors (object, customiser_id, currency, updated_at), and a property this resource does not define is refused with a JSON Pointer rather than ignored, so a typo can never silently change meaning. Requires the customisers:write scope. A successful update immediately changes the storefront: the customiser's cached configuration is invalidated and translated language content is resynchronised. It never regenerates your Shopify products, product images, or product cache. Send an Idempotency-Key header (1-255 visible ASCII characters, e.g. a UUID) to make the write safe to retry: repeating the same key with the same body replays the original response (marked Idempotency-Replay: true) without executing again; the same key with a different body is a 409 problem with code idempotency_key_conflict. The header is optional here, as on the option families' update operations. Validation failures are 422 problems: validation_failed lists every field error in errors[] with a JSON pointer and, for closed-set violations, the allowed_values; unknown_field means the body names properties outside the document. The sign minimum, initial, and maximum dimensions are checked against the document the patch would leave behind, so clearing one end of a range is refused exactly as an impossible value is. icon_font_tier_id and icon_length_pricing_id must name records of this customiser. A 400 problem means the body is not valid JSON or the Idempotency-Key header is malformed. 401/403/404/429 behave as on the read operation, with customisers:write as the required scope.

Authorisation

Bearer token required. Include it in theAuthorization header.

Required scope: customisers:write

Path parameters

customiser_idstringpathrequired

The customiser id, from the list customisers operation.

Example: 1

Request body

custom_sizingbooleanbody

multi_colourbooleanbody

text_editor_enabledbooleanbody

min_sign_width_cmintegerbody

max_sign_width_cmintegerbody

max_sign_charintegerbody

discount_amountintegerbody

custom_cssstringbody

selection_orderarraybody

Request body example

{
  "custom_sizing": true,
  "multi_colour": true,
  "text_editor_enabled": true,
  "min_sign_width_cm": 20,
  "max_sign_width_cm": 200,
  "max_sign_char": 40,
  "discount_amount": 500,
  "custom_css": ".sc-price { font-weight: 600; }",
  "selection_order": [
    {
      "family": "colour",
      "label": "Colour",
      "hidden": false
    }
  ]
}

Update customiser settings

curl https://web.signcustomiser.com/api/v3/customisers/1/settings \
  --request PATCH \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "custom_sizing": true,
  "multi_colour": true,
  "text_editor_enabled": true,
  "min_sign_width_cm": 20,
  "max_sign_width_cm": 200,
  "max_sign_char": 40,
  "discount_amount": 500,
  "custom_css": ".sc-price { font-weight: 600; }",
  "selection_order": [
    {
      "family": "colour",
      "label": "Colour",
      "hidden": false
    }
  ]
}'

{
  "data": {
    "object": "customiser_settings",
    "customiser_id": 42,
    "currency": "USD",
    "add_to_cart": true,
    "alignment": "show_alignment_options",
    "allow_unsupported_characters": true,
    "app_mode": "standard",
    "auto_process_ai_quotes": true,
    "auto_rotate_lightbox": true,
    "braille_dots_use_face_colour": true,
    "braille_table": "en-ueb-g1",
    "cart_action": "cart_page",
    "custom_css": ".sc-price { font-weight: 600; }",
    "custom_letter_height_input": true,
    "custom_letter_height_max_cm": 30,
    "custom_size_input": "when_selected",
    "custom_sizing": true,
    "custom_sizing_max_width_cm": 200,
    "custom_sizing_title": "Custom size",
    "desktop_option_order": "right",
    "desktop_show_sidebar_price": true,
    "disable_braille_untranslatable_popup": true,
    "disable_size_limit_popup": true,
    "discount_amount": 500,
    "discount_option": "none",
    "discount_percentage": 10,
    "drag_enabled": true,
    "etsy_listing_url": null,
    "etsy_show_price": true,
    "example_hover": true,
    "fixed_visualiser": true,
    "font_display": "dropdown",
    "font_scale": 1,
    "generate_ai": true,
    "generate_dxf": true,
    "generate_eps": true,
    "generate_svg": true,
    "glow_effect": "white_neon",
    "glow_switch": "glow_switch",
    "icon_font_tier_id": 3,
    "icon_length_pricing_id": null,
    "icon_min_height_cm": 5,
    "initial_sign_height_cm": 20,
    "initial_sign_length_cm": 60,
    "initial_sign_width_cm": 60,
    "letter_height_display": true,
    "local_cache_enabled": true,
    "manually_clear_loading": true,
    "max_sign_char": 40,
    "max_sign_height_cm": 90,
    "max_sign_length_cm": 300,
    "max_sign_lines": 3,
    "max_sign_width_cm": 200,
    "measurement_decimal": 1,
    "measurement_display": "both",
    "measurement_unit": "both",
    "min_sign_char": 1,
    "min_sign_height_cm": 10,
    "min_sign_length_cm": 10,
    "min_sign_width_cm": 20,
    "mobile_preview_height_percent": 45,
    "mobile_view": "stacked",
    "mounting_colour_location": "separate",
    "multi_colour": true,
    "multi_font": true,
    "part_measurement_display": "show",
    "prevent_size_up": true,
    "pricebox_position": "bottom",
    "recessed_borders": true,
    "rotate_enabled": true,
    "scale_enabled": true,
    "scale_text_with_size": true,
    "scrollable_mobile_options": true,
    "selection_order": [
      {
        "family": "size",
        "label": "Size",
        "hidden": false
      },
      {
        "family": "colour",
        "label": "Colour",
        "hidden": false
      }
    ],
    "share_location": "disabled",
    "show_currency": "show",
    "show_custom_size_button": true,
    "show_day_switch": true,
    "show_glow_switch": true,
    "show_initial_mobile_screen": true,
    "show_menu_steps": true,
    "show_menu_steps_first": true,
    "show_selection_numbers": true,
    "size_display": "all",
    "snap_to_grid_enabled": true,
    "snap_to_grid_size_px": 10,
    "support_colour_location": "separate",
    "taxable_product": true,
    "text_editor_enabled": true,
    "text_orientation_column_direction": "right_to_left",
    "text_orientation_default": "horizontal",
    "text_orientation_mode": "horizontal_only",
    "text_price_start": true,
    "ui_controls_location": "visualiser",
    "zoom_controls_display": "show",
    "updated_at": "2026-05-04T09:12:31Z"
  },
  "links": {
    "self": "https://web.signcustomiser.com/api/v3/customisers/42/settings",
    "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: Authorization: Bearer <api key>. Keys are created in the merchant admin under Integrate → API Tokens.",
  "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, but the API key grants the following scopes: customisers:read. Create a key that includes the required scope in the merchant admin under Integrate → API Tokens.",
  "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. An idempotency key identifies one exact request: retry the original body to replay its response, or send the new body with a fresh key.",
  "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. Correct the fields listed in errors and retry.",
  "errors": [
    {
      "pointer": "/measurement_unit",
      "code": "unsupported_value",
      "detail": "The selected measurement unit is invalid.",
      "allowed_values": [
        "both",
        "centimetres",
        "inches"
      ]
    }
  ],
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/unknown_field",
  "title": "Unknown field",
  "status": 422,
  "code": "unknown_field",
  "detail": "The request contains fields this operation does not define: /max_sign_size.",
  "errors": [
    {
      "pointer": "/max_sign_size",
      "code": "unknown_field",
      "detail": "The field \"max_sign_size\" is not supported by this operation."
    }
  ],
  "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. Wait 60 seconds, then retry.",
  "retry_after": 60,
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}