# POST 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.

- Source URL: https://www.signcustomiser.com/help/api/v3-post-create-a-letter-part-colour-selection/
- Markdown URL: https://www.signcustomiser.com/help/api/v3-post-create-a-letter-part-colour-selection.md
- Group: Customiser letter parts
- Method: POST
- Path: /api/v3/customisers/{customiser_id}/letter-types/{letter_type_id}/letter-parts
- Auth: Bearer token
- Required scopes: `customisers:write`

## Path parameters

- customiser_id (string, required): The customiser id. Example: 1
- letter_type_id (string, required): The letter type id. Example: 7

## Body parameters

- letter_part (string, optional): No description provided.
- name (string, optional): No description provided.
- description (string, optional): No description provided.
- optional (boolean, optional): No description provided.
- optional_default_none (boolean, optional): No description provided.
- lightsource (boolean, optional): No description provided.
- custom_image (boolean, optional): No description provided.
- show_default_upload_image (boolean, optional): No description provided.
- show_in_text_editor (boolean, optional): No description provided.
- text_enabled (boolean, optional): No description provided.

## Request body example

```json
{
  "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
}
```

## cURL example

```bash
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
}'
```

## Response examples

### 201 POST 201 example 1

```json
{
  "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"
  }
}
```

### 400 Missing idempotency key

```json
{
  "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"
}
```

### 401 Missing API key

```json
{
  "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"
}
```

### 403 Insufficient scope

```json
{
  "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"
}
```

### 404 Unknown letter type

```json
{
  "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"
}
```

### 409 Idempotency conflict

```json
{
  "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"
}
```

### 413 Request body too large

```json
{
  "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"
}
```

### 422 Letter part already created

```json
{
  "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"
}
```

### 429 Option write budget exhausted

```json
{
  "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"
}
```