Customiser letter parts

Create a letter-part colour selection

Copy page

Creates the colour selection for one part of a letter type. letter_part is the half of the identity the caller chooses, so it goes in the body here and nowhere else — every other operation carries it in the path. A part that already has a colour selection is refused with a 422 letter_part_taken; update it instead.

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

Create a letter-part colour selection

Creates the colour selection for one part of a letter type. `letter_part` is the half of the identity the caller chooses, so it goes in the body here and nowhere else — every other operation carries it in the path. A part that already has a colour selection is refused with a 422 `letter_part_taken`; update it instead. Two configurations are refused rather than quietly rewritten, which is what the merchant admin does: `text_enabled` may be set only on the front face of a rectangle or cylinder lightbox (422 `customer_text_not_supported`), and a lightbox border carries no optionality (422 `field_not_used_by_letter_part`). A create stores only the fields it names, so an omitted one takes the default the letter type's category expects. That also keeps a fresh part deletable: the guarded delete only removes a part whose configuration is untouched. `default_upload_image_url` is read-only until the upload surface ships. Creating the colour selection does not add the part to the letter type's `letter_parts`; patch the letter type for that. Requires `customisers:write` and an `Idempotency-Key`. The write clears the customiser's cached storefront configuration and runs the advisory language sync. It never regenerates Shopify products, product images, or the product cache. Option writes also spend one unit of a separate per-key option-write budget.

Create a letter-part colour selection

Overview

Two configurations are refused rather than quietly rewritten, which is what the merchant admin does: text_enabled may be set only on the front face of a rectangle or cylinder lightbox (422 customer_text_not_supported), and a lightbox border carries no optionality (422 field_not_used_by_letter_part). A create stores only the fields it names, so an omitted one takes the default the letter type's category expects. That also keeps a fresh part deletable: the guarded delete only removes a part whose configuration is untouched. default_upload_image_url is read-only until the upload surface ships. Creating the colour selection does not add the part to the letter type's letter_parts; patch the letter type for that. Requires customisers:write and an Idempotency-Key. The write clears the customiser's cached storefront configuration and runs the advisory language sync. It never regenerates Shopify products, product images, or the product cache. Option writes also spend one unit of a separate per-key option-write budget.

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

Request body

letter_partstringbody

namestringbody

descriptionstringbody

optionalbooleanbody

optional_default_nonebooleanbody

lightsourcebooleanbody

custom_imagebooleanbody

show_default_upload_imagebooleanbody

show_in_text_editorbooleanbody

text_enabledbooleanbody

Request body example

{
  "letter_part": "face",
  "name": "Face colour",
  "description": "The colour customers see lit",
  "optional": false,
  "optional_default_none": false,
  "lightsource": false,
  "custom_image": false,
  "show_default_upload_image": true,
  "show_in_text_editor": true,
  "text_enabled": false
}

Create a letter-part colour selection

curl https://web.signcustomiser.com/api/v3/customisers/1/letter-types/7/letter-parts \
  --request POST \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "letter_part": "face",
  "name": "Face colour",
  "description": "The colour customers see lit",
  "optional": false,
  "optional_default_none": false,
  "lightsource": false,
  "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": null,
    "description": null,
    "optional": null,
    "optional_label": null,
    "optional_default_none": false,
    "lightsource": false,
    "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:00: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/missing_idempotency_key",
  "title": "Missing idempotency key",
  "status": 400,
  "code": "missing_idempotency_key",
  "detail": "Provide an Idempotency-Key header for this write.",
  "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/letter_part_taken",
  "title": "Letter part already created",
  "status": 422,
  "code": "letter_part_taken",
  "detail": "This letter type already has a colour selection for the face letter part.",
  "errors": [
    {
      "pointer": "/letter_part",
      "code": "letter_part_taken",
      "detail": "The face letter part already has a colour selection on this letter type."
    }
  ],
  "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"
}