Sign Customiser

Customiser colours

Attach a colour image

Copy page

Takes the raster image of a staged upload and puts it in one of the colour's three image slots, returning the colour with that slot's *_url pointing at the new file. Requires customisers:write and an Idempotency-Key.

PUT/api/v3/customisers/{customiser_id}/colours/{colour_id}/images/{image_slot}

Overview

Create the upload first with POST/api/v3/uploads — purpose option_image for image and example_image, option_texture_image for texture_image — send the bytes to the presigned target it returns, then send that upload's id here. An upload whose purpose is not the slot's answers 422 upload_purpose_mismatch. The upload is single use: attaching it a second time answers 409, and each slot needs its own upload. Only PNG, JPEG and WebP are accepted. SVG is refused when the upload is created, because the option-image path stores files as they arrive and does not sanitise them. The bytes are verified here, not at create: the object must exist, be within the purpose's cap, start with the magic bytes of the type it was declared as, and carry a readable image header. A file that fails leaves the upload rejected with the failure's code, and attaching it again replays that code — fix the file and create a new upload rather than retrying. Attaching to a slot that already holds an image replaces it. The previous file is deleted once the new one is committed, so any URL published for it stops resolving. Attaching to texture_image is what makes the custom_texture finish available: send the image here first, then set texture on the colour itself. The attach clears the customiser's cached storefront configuration and runs the advisory language sync. It 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

colour_idstringpathrequired

The colour id.

Example: 7

image_slotstringpathrequired

Which of the colour's images to write (closed set): the swatch a shopper picks from, the example photograph beside it, or the texture the custom_texture finish renders from.

Example: image

Request body

upload_idstringbody

Request body example

application/json
{
  "upload_id": "upl_9f2c4b7ad13e6058ba41cd"
}
Attach a colour image
curl https://web.signcustomiser.com/api/v3/customisers/1/colours/7/images/image \
  --request PUT \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "upload_id": "upl_9f2c4b7ad13e6058ba41cd"
}'
Response
{
  "data": {
    "object": "colour",
    "id": 7,
    "customiser_id": 42,
    "name": "Warm White",
    "description": null,
    "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": 0,
    "currency": "USD",
    "price_multiplier": 1,
    "price_multiplier_target": "base_letter_price",
    "sort_order": 1,
    "image_url": "https://cdn.example.com/files/2f1c9c0e-6a7b-4c1d-8e2f-3a4b5c6d7e8f.png",
    "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/colours/7/images/image",
    "documentation": "https://www.signcustomiser.com/help/api/"
  },
  "meta": {
    "api_version": "v3",
    "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
  }
}