Customiser materials

Update a material

Copy page

Applies an RFC 7396 JSON Merge Patch to one material: properties omitted from the body are unchanged, and null clears a nullable property (description, hexcode). Arrays are replaced wholesale, so sending excluded_backboard_ids replaces the whole exclusion list.

PATCH/api/v3/customisers/{customiser_id}/materials/{material_id}

Update a material

Applies an RFC 7396 JSON Merge Patch to one material: properties omitted from the body are unchanged, and `null` clears a nullable property (`description`, `hexcode`). Arrays are replaced wholesale, so sending `excluded_backboard_ids` replaces the whole exclusion list. Read-only and unknown fields are rejected. An empty object `{}` is a valid no-op. Requires `customisers:write`. An `Idempotency-Key` is optional here: sending one makes the update safe to retry (an exact repeat replays the original response; the same key with a different body is a 409). 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 material

Overview

Read-only and unknown fields are rejected. An empty object {} is a valid no-op. Requires customisers:write. An Idempotency-Key is optional here: sending one makes the update safe to retry (an exact repeat replays the original response; the same key with a different body is a 409). 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 the Authorization header.

Required scope: customisers:write

Path parameters

customiser_idstringpathrequired

The customiser id.

Example: 1

material_idstringpathrequired

The material id.

Example: 5

Request body

hexcodestringbody

namestringbody

descriptionstringbody

excluded_backboard_idsarraybody

excluded_mounting_idsarraybody

base_priceintegerbody

Request body example

{
  "hexcode": "#737373",
  "name": "Brushed Aluminium",
  "description": "3mm brushed aluminium face",
  "excluded_backboard_ids": [
    11
  ],
  "excluded_mounting_ids": [
    4
  ],
  "base_price": 500
}

Update a material

curl https://web.signcustomiser.com/api/v3/customisers/1/materials/5 \
  --request PATCH \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "hexcode": "#737373",
  "name": "Brushed Aluminium",
  "description": "3mm brushed aluminium face",
  "excluded_backboard_ids": [
    11
  ],
  "excluded_mounting_ids": [
    4
  ],
  "base_price": 500
}'

{
  "data": {
    "object": "material",
    "id": 5,
    "customiser_id": 42,
    "name": "Brushed Aluminium",
    "description": "3mm brushed aluminium face",
    "hexcode": "#737373",
    "excluded_backboard_ids": [
      11
    ],
    "excluded_mounting_ids": [],
    "base_price": 500,
    "currency": "USD",
    "price_multiplier": 1,
    "price_multiplier_target": "base_letter_price",
    "sort_order": 1,
    "image_url": null,
    "button_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/materials/5",
    "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/validation_failed",
  "title": "Validation failed",
  "status": 422,
  "code": "validation_failed",
  "detail": "The request payload failed validation.",
  "errors": [
    {
      "pointer": "/image_url",
      "code": "prohibited",
      "detail": "The image_url field is prohibited."
    }
  ],
  "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"
}