Customiser letter parts

Update a letter-part colour selection

Copy page

Applies an RFC 7396 JSON Merge Patch to one letter-part colour selection: properties omitted from the body are unchanged, and null clears a nullable property (name, description, optional_label). Read-only and unknown fields are rejected — letter_part among them, because the path already carries it and a part cannot be renamed.

PATCH/api/v3/customisers/{customiser_id}/letter-types/{letter_type_id}/letter-parts/{letter_part}

Update a letter-part colour selection

Applies an RFC 7396 JSON Merge Patch to one letter-part colour selection: properties omitted from the body are unchanged, and `null` clears a nullable property (`name`, `description`, `optional_label`). Read-only and unknown fields are rejected — `letter_part` among them, because the path already carries it and a part cannot be renamed. An empty object `{}` is a valid no-op. The lightbox text and border rules apply here exactly as they do on the create. Requires `customisers:write`. An `Idempotency-Key` is optional here: sending one makes the update safe to retry. 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 letter-part colour selection

Overview

An empty object {} is a valid no-op. The lightbox text and border rules apply here exactly as they do on the create. Requires customisers:write. An Idempotency-Key is optional here: sending one makes the update safe to retry. 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

letter_type_idstringpathrequired

The letter type id.

Example: 7

letter_partstringpathrequired

The letter part.

Example: face

Request body

namestringbody

optionalbooleanbody

optional_labelstringbody

optional_default_nonebooleanbody

lightsourcebooleanbody

custom_imagebooleanbody

show_default_upload_imagebooleanbody

show_in_text_editorbooleanbody

text_enabledbooleanbody

Request body example

{
  "name": "Face colour",
  "optional": true,
  "optional_label": "No face colour",
  "optional_default_none": false,
  "lightsource": true,
  "custom_image": false,
  "show_default_upload_image": true,
  "show_in_text_editor": true,
  "text_enabled": false
}

Update a letter-part colour selection

curl https://web.signcustomiser.com/api/v3/customisers/1/letter-types/7/letter-parts/face \
  --request PATCH \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Face colour",
  "optional": true,
  "optional_label": "No face colour",
  "optional_default_none": false,
  "lightsource": true,
  "custom_image": false,
  "show_default_upload_image": true,
  "show_in_text_editor": true,
  "text_enabled": false
}'

{
  "data": {
    "object": "letter_part_colour_selection",
    "customiser_id": 42,
    "letter_type_id": 7,
    "letter_part": "face",
    "name": "Face colour",
    "description": null,
    "optional": true,
    "optional_label": "No face colour",
    "optional_default_none": false,
    "lightsource": true,
    "custom_image": false,
    "show_default_upload_image": true,
    "show_in_text_editor": true,
    "text_enabled": false,
    "default_upload_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/letter-types/7/letter-parts/face",
    "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/customer_text_not_supported",
  "title": "Customer text not supported",
  "status": 422,
  "code": "customer_text_not_supported",
  "detail": "Customer text renders on the front face of a rectangle or cylinder lightbox only.",
  "errors": [
    {
      "pointer": "/text_enabled",
      "code": "customer_text_not_supported",
      "detail": "This letter part cannot carry customer text."
    }
  ],
  "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"
}