Customiser backlights

Update a backlight

Copy page

Applies an RFC 7396 JSON Merge Patch to one backlight: properties omitted from the body are unchanged, and null clears a nullable property (description, hexcode, multi_colour_hexcodes, min_width_cm, min_height_cm). Arrays are replaced wholesale.

PATCH/api/v3/customisers/{customiser_id}/backlights/{backlight_id}

Update a backlight

Applies an RFC 7396 JSON Merge Patch to one backlight: properties omitted from the body are unchanged, and `null` clears a nullable property (`description`, `hexcode`, `multi_colour_hexcodes`, `min_width_cm`, `min_height_cm`). Arrays are replaced wholesale. Read-only and unknown fields are rejected — sending one at all is a 422, whatever its value. An empty object `{}` is a valid no-op. The patched result must still be renderable: clearing the last hex value of a `single` backlight, or switching to `multi`/`flow` without hex values, is a 422 `colour_value_required`, and switching to the `custom_texture` finish is refused with a 422 `texture_image_required` unless the backlight already carries a texture image. Requires `customisers:write`. 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 a backlight

Overview

Read-only and unknown fields are rejected — sending one at all is a 422, whatever its value. An empty object {} is a valid no-op. The patched result must still be renderable: clearing the last hex value of a single backlight, or switching to multi/flow without hex values, is a 422 colour_value_required, and switching to the custom_texture finish is refused with a 422 texture_image_required unless the backlight already carries a texture image. Requires customisers:write. 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 theAuthorization header.

Required scope: customisers:write

Path parameters

customiser_idstringpathrequired

The customiser id.

Example: 1

backlight_idstringpathrequired

The backlight id.

Example: 14

Request body

colour_typestringbody

texturestringbody

min_size_rulestringbody

price_multiplier_targetstringbody

namestringbody

descriptionstringbody

hexcodestringbody

multi_colour_hexcodesarraybody

base_priceintegerbody

price_multipliernumberbody

Request body example

{
  "colour_type": "single",
  "texture": "flat",
  "min_size_rule": "any",
  "price_multiplier_target": "base_letter_price",
  "name": "Warm White Glow",
  "description": "A soft warm glow",
  "hexcode": "#FFEEDD",
  "multi_colour_hexcodes": [
    "#FF0000",
    "#00FF00"
  ],
  "base_price": 500,
  "price_multiplier": 1.2
}

Update a backlight

curl https://web.signcustomiser.com/api/v3/customisers/1/backlights/14 \
  --request PATCH \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "colour_type": "single",
  "texture": "flat",
  "min_size_rule": "any",
  "price_multiplier_target": "base_letter_price",
  "name": "Warm White Glow",
  "description": "A soft warm glow",
  "hexcode": "#FFEEDD",
  "multi_colour_hexcodes": [
    "#FF0000",
    "#00FF00"
  ],
  "base_price": 500,
  "price_multiplier": 1.2
}'

{
  "data": {
    "object": "backlight",
    "id": 14,
    "customiser_id": 42,
    "name": "Warm White Glow",
    "description": "A soft warm glow",
    "colour_type": "single",
    "hexcode": "#FFEEDD",
    "multi_colour_hexcodes": null,
    "texture": "flat",
    "min_width_cm": null,
    "min_height_cm": null,
    "min_size_rule": "any",
    "base_price": 500,
    "currency": "USD",
    "price_multiplier": 1,
    "price_multiplier_target": "base_letter_price",
    "sort_order": 1,
    "image_url": null,
    "example_image_url": null,
    "texture_image_url": null,
    "created_at": "2026-08-13T00:00:00Z",
    "updated_at": "2026-08-13T00:05:00Z"
  },
  "links": {
    "self": "https://web.signcustomiser.com/api/v3/customisers/42/backlights/14",
    "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": "/sort_order",
      "code": "prohibited",
      "detail": "The sort order 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"
}