# POST Create a customiser

Creates a customiser from one of the store's prototypes. A prototype is a complete starting point — it fixes the sign category, the pricing model, the sizing strategy, the styling mode, and whether the AI sign designer is set up — and the create copies it together with a full set of demo options, sizes, fonts, price lists, forms, and labels for you to edit through the other operations. List the prototypes to see the ids, and pass one as `prototype`. The only other field is `name`; omit it and the customiser takes the prototype's own default name. Whether the new customiser is live is decided here, not asked for: `active` comes back true only when the store's plan still has room to put one more customiser live and includes this pricing model, and false otherwise. Building a customiser is always allowed, so a store at its limit gets a complete, editable, not-yet-live customiser rather than a refusal. Activate it later with the activate operation once there is room. The styling mode is the prototype's, narrowed to `single_style` when the plan does not include per-word styling, so read `selection_mode` back rather than assuming it. Requires the `customisers:write` scope and an `Idempotency-Key` header (1-255 visible ASCII characters, e.g. a UUID): repeating the same key with the same body replays the original response (marked `Idempotency-Replay: true`) instead of creating a second customiser, and the same key with a different body is a 409 problem with code `idempotency_key_conflict`. A 422 problem with code `validation_failed` and the error code `prototype_not_found` means no prototype has that id. Code `prototype_not_available` means the store's plan does not include it — `unavailable_reasons` says why. Code `pricing_model_deprecated` means the prototype is priced by a model that is no longer offered. A 400 problem means the body is not valid JSON or the `Idempotency-Key` header is missing or malformed. 401/403/429 behave as on the list operation, with `customisers:write` as the required scope.

- Source URL: https://www.signcustomiser.com/help/api/v3-post-create-a-customiser/
- Markdown URL: https://www.signcustomiser.com/help/api/v3-post-create-a-customiser.md
- Group: Customisers
- Method: POST
- Path: /api/v3/customisers
- Auth: Bearer token
- Required scopes: `customisers:write`

## Body parameters

- prototype (string, optional): No description provided.
- name (string, optional): No description provided.

## Request body example

```json
{
  "prototype": "neon-frame-fit",
  "name": "Neon sign builder"
}
```

## cURL example

```bash
curl https://web.signcustomiser.com/api/v3/customisers \
  --request POST \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "prototype": "neon-frame-fit",
  "name": "Neon sign builder"
}'
```

## Response examples

### 201 POST 201 example 1

```json
{
  "data": {
    "object": "customiser",
    "id": 42,
    "name": "Neon sign builder",
    "active": true,
    "pricing_model": "frame_fit",
    "pricing_model_display_name": "Frame Fit",
    "sign_category": "neon",
    "product_family": "neon",
    "selection_mode": "per_word",
    "created_at": "2026-08-14T00:00:00Z",
    "updated_at": "2026-08-14T00:00:00Z"
  },
  "links": {
    "self": "https://web.signcustomiser.com/api/v3/customisers/42",
    "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"
}
```

### 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"
}
```

### 422 Unknown prototype

```json
{
  "type": "https://www.signcustomiser.com/help/api/problems/validation_failed",
  "title": "Validation failed",
  "status": 422,
  "code": "validation_failed",
  "detail": "There is no prototype with id \"neon\".",
  "errors": [
    {
      "pointer": "/prototype",
      "code": "prototype_not_found",
      "detail": "The prototype \"neon\" does not exist."
    }
  ],
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}
```

### 422 Prototype not on the plan

```json
{
  "type": "https://www.signcustomiser.com/help/api/problems/prototype_not_available",
  "title": "Prototype not available",
  "status": 422,
  "code": "prototype_not_available",
  "detail": "The \"lightbox-frame-fit\" prototype is not available on this store's plan.",
  "errors": [
    {
      "pointer": "/prototype",
      "code": "prototype_not_available",
      "detail": "This prototype is not available on the store's plan."
    }
  ],
  "unavailable_reasons": [
    "lightbox"
  ],
  "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"
}
```