Customiser colour scheme

Validate a customiser colour scheme update

Copy page

POST/api/v3/customisers/{customiser_id}/colour-scheme/validate-update

Validate a customiser colour scheme update

Dry-run a colour scheme merge patch without persisting anything. The request body is the same merge patch the update operation accepts, and on the failing paths the response is exactly what that update would produce: the identical 422 problem, because the same validation code path runs and only persistence is skipped. On a patch that would apply, the response is a 200 `colour_scheme_validation` confirmation. Nothing is written, no caches are touched, no idempotency key is consumed, and no activity is recorded, so the operation is always safe to repeat. The verdict is advisory: nothing binds it to a later update. Requires the `customisers:write` scope (it is the write's dry-run twin). A 400 problem means the body is not valid JSON; a 422 problem with code `invalid_document` means the body is not a JSON object. 401/403/404/429 behave as on the read operation, with `customisers:write` as the required scope.

Authorisation

Authorizationstring<bearer>required

The Authorization header expects a Bearer token. Generate one on the API keys page in your dashboard.

Path

customiser_idintegerrequired

The customiser id, from the list customisers operation.

Bodyapplication/json

{
  "background_colour": "#1f2937",
  "box_colour": "#1f2937",
  "box_text_colour": "#1f2937",
  "button_text_colour": "#1f2937",
  "control_bar_background_colour": "#1f2937",
  "control_bar_button_border_colour": "#1f2937",
  "control_bar_button_colour": "#1f2937",
  "control_bar_button_hover_colour": "#1f2937",
  "control_bar_icon_colour": "#1f2937",
  "discount_price_colour": "#1f2937",
  "form_error_colour": "#1f2937",
  "link_colour": "#1f2937",
  "main_discount_price_colour": "#1f2937",
  "main_price_colour": "#1f2937",
  "measurement_display_colour": "#1f2937",
  "modal_background_colour": "#1f2937",
  "modal_overlay_colour": "#1f2937",
  "modal_text_colour": "#1f2937",
  "outline_colour": "#1f2937",
  "pending_colour": "#1f2937",
  "price_colour": "#1f2937",
  "price_label_colour": "#1f2937",
  "primary_colour": "#1f2937",
  "save_form_background_colour": "#1f2937",
  "save_form_border_colour": "#1f2937",
  "save_form_button_colour": "#1f2937",
  "save_form_button_text_colour": "#1f2937",
  "save_form_heading_colour": "#1f2937",
  "save_form_text_colour": "#1f2937",
  "secondary_background_colour": "#1f2937",
  "secondary_colour": "#1f2937",
  "secondary_text_colour": "#1f2937",
  "selection_number_background_colour": "#1f2937",
  "selection_number_text_colour": "#1f2937",
  "success_colour": "#1f2937",
  "text_colour": "#1f2937",
  "text_input_background_colour": "#1f2937",
  "visualisation_background_colour": "#1f2937",
  "visualisation_text_colour": "#1f2937"
}

Validate a customiser colour scheme update

Overview

On a patch that would apply, the response is a 200 colour_scheme_validation confirmation. Nothing is written, no caches are touched, no idempotency key is consumed, and no activity is recorded, so the operation is always safe to repeat. The verdict is advisory: nothing binds it to a later update. Requires the customisers:write scope (it is the write's dry-run twin). A 400 problem means the body is not valid JSON; a 422 problem with code invalid_document means the body is not a JSON object. 401/403/404/429 behave as on the read operation, with customisers:write as the required scope.

Authorisation

Bearer token required. Include it in the Authorization header.

Required scope: customisers:write

Path parameters

customiser_idstringpathrequired

The customiser id, from the list customisers operation.

Example: 1

Request body

background_colourstringbody

box_colourstringbody

box_text_colourstringbody

button_text_colourstringbody

control_bar_background_colourstringbody

control_bar_button_border_colourstringbody

control_bar_button_colourstringbody

control_bar_button_hover_colourstringbody

control_bar_icon_colourstringbody

discount_price_colourstringbody

form_error_colourstringbody

link_colourstringbody

main_discount_price_colourstringbody

main_price_colourstringbody

measurement_display_colourstringbody

modal_background_colourstringbody

modal_overlay_colourstringbody

modal_text_colourstringbody

outline_colourstringbody

pending_colourstringbody

price_colourstringbody

price_label_colourstringbody

primary_colourstringbody

save_form_background_colourstringbody

save_form_border_colourstringbody

save_form_button_colourstringbody

save_form_button_text_colourstringbody

save_form_heading_colourstringbody

save_form_text_colourstringbody

secondary_background_colourstringbody

secondary_colourstringbody

secondary_text_colourstringbody

selection_number_background_colourstringbody

selection_number_text_colourstringbody

success_colourstringbody

text_colourstringbody

text_input_background_colourstringbody

visualisation_background_colourstringbody

visualisation_text_colourstringbody

Request body example

{
  "background_colour": "#1f2937",
  "box_colour": "#1f2937",
  "box_text_colour": "#1f2937",
  "button_text_colour": "#1f2937",
  "control_bar_background_colour": "#1f2937",
  "control_bar_button_border_colour": "#1f2937",
  "control_bar_button_colour": "#1f2937",
  "control_bar_button_hover_colour": "#1f2937",
  "control_bar_icon_colour": "#1f2937",
  "discount_price_colour": "#1f2937",
  "form_error_colour": "#1f2937",
  "link_colour": "#1f2937",
  "main_discount_price_colour": "#1f2937",
  "main_price_colour": "#1f2937",
  "measurement_display_colour": "#1f2937",
  "modal_background_colour": "#1f2937",
  "modal_overlay_colour": "#1f2937",
  "modal_text_colour": "#1f2937",
  "outline_colour": "#1f2937",
  "pending_colour": "#1f2937",
  "price_colour": "#1f2937",
  "price_label_colour": "#1f2937",
  "primary_colour": "#1f2937",
  "save_form_background_colour": "#1f2937",
  "save_form_border_colour": "#1f2937",
  "save_form_button_colour": "#1f2937",
  "save_form_button_text_colour": "#1f2937",
  "save_form_heading_colour": "#1f2937",
  "save_form_text_colour": "#1f2937",
  "secondary_background_colour": "#1f2937",
  "secondary_colour": "#1f2937",
  "secondary_text_colour": "#1f2937",
  "selection_number_background_colour": "#1f2937",
  "selection_number_text_colour": "#1f2937",
  "success_colour": "#1f2937",
  "text_colour": "#1f2937",
  "text_input_background_colour": "#1f2937",
  "visualisation_background_colour": "#1f2937",
  "visualisation_text_colour": "#1f2937"
}

Validate a customiser colour scheme update

curl https://web.signcustomiser.com/api/v3/customisers/1/colour-scheme/validate-update \
  --request POST \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "background_colour": "#1f2937",
  "box_colour": "#1f2937",
  "box_text_colour": "#1f2937",
  "button_text_colour": "#1f2937",
  "control_bar_background_colour": "#1f2937",
  "control_bar_button_border_colour": "#1f2937",
  "control_bar_button_colour": "#1f2937",
  "control_bar_button_hover_colour": "#1f2937",
  "control_bar_icon_colour": "#1f2937",
  "discount_price_colour": "#1f2937",
  "form_error_colour": "#1f2937",
  "link_colour": "#1f2937",
  "main_discount_price_colour": "#1f2937",
  "main_price_colour": "#1f2937",
  "measurement_display_colour": "#1f2937",
  "modal_background_colour": "#1f2937",
  "modal_overlay_colour": "#1f2937",
  "modal_text_colour": "#1f2937",
  "outline_colour": "#1f2937",
  "pending_colour": "#1f2937",
  "price_colour": "#1f2937",
  "price_label_colour": "#1f2937",
  "primary_colour": "#1f2937",
  "save_form_background_colour": "#1f2937",
  "save_form_border_colour": "#1f2937",
  "save_form_button_colour": "#1f2937",
  "save_form_button_text_colour": "#1f2937",
  "save_form_heading_colour": "#1f2937",
  "save_form_text_colour": "#1f2937",
  "secondary_background_colour": "#1f2937",
  "secondary_colour": "#1f2937",
  "secondary_text_colour": "#1f2937",
  "selection_number_background_colour": "#1f2937",
  "selection_number_text_colour": "#1f2937",
  "success_colour": "#1f2937",
  "text_colour": "#1f2937",
  "text_input_background_colour": "#1f2937",
  "visualisation_background_colour": "#1f2937",
  "visualisation_text_colour": "#1f2937"
}'

{
  "data": {
    "object": "colour_scheme_validation",
    "operation": "update",
    "customiser_id": 42,
    "valid": true
  },
  "links": {
    "self": "https://web.signcustomiser.com/api/v3/customisers/42/colour-scheme/validate-update",
    "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: Authorization: Bearer <api key>. Keys are created in the merchant admin under Integrate → API Tokens.",
  "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, but the API key grants the following scopes: customisers:read. Create a key that includes the required scope in the merchant admin under Integrate → API Tokens.",
  "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/validation_failed",
  "title": "Validation failed",
  "status": 422,
  "code": "validation_failed",
  "detail": "The request payload failed validation. Correct the fields listed in errors and retry.",
  "errors": [
    {
      "pointer": "/primary_colour",
      "code": "hex_color",
      "detail": "The primary colour field must be a valid hexadecimal color."
    }
  ],
  "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. Wait 60 seconds, then retry.",
  "retry_after": 60,
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}