# PUT Replace customiser pricing

Replace the customiser's entire pricing configuration with the request body — the full canonical document, exactly as the read operation returns it (no envelope). This is an explicit full replacement: sizes and price lists omitted from the document are deleted (each carries its id — size_id, price_list_id — to update in place; omit the id to create a new record, and use a size client_key with row size_key references to link rows to sizes created in the same request). For partial updates prefer PATCH; to check a document without persisting anything use the validate operation. The read-only descriptor fields (object, customiser_id, pricing_model, pricing_model_display_name, currency) may be echoed back unchanged but can never be changed here — in particular the pricing model cannot be switched. Field semantics, units, and the per-model document shapes are documented on the read operation. Requires the `pricing:write` scope. A successful replacement immediately reprices the storefront: the customiser's cached configuration is invalidated and translated language content is resynchronised. Send an `Idempotency-Key` header (1-255 visible ASCII characters, e.g. a UUID) to make the write safe to retry: repeating the same key with the same body replays the original response (marked `Idempotency-Replay: true`) without executing again; the same key with a different body is a 409 problem with code `idempotency_key_conflict`; keys are retained for at least 24 hours and are scoped to your credential, the HTTP method, and the path. Validation failures are 422 problems: `validation_failed` lists every field error in `errors[]` with a JSON `pointer` and, for enum violations, the `allowed_values`; `unknown_field` means the document contains fields outside the schema (fix the pointers listed — nothing is ever silently ignored); `legacy_pricing_model` means the customiser still uses the retired fixed-height model. A 409 problem with code `resource_in_use` means the document omits sizes or price lists that fonts or settings still reference — keep them in the document or detach them first. A 400 problem means the body is not valid JSON or the `Idempotency-Key` header is malformed. 401/403/404/429 behave as on the read operation.

- Source URL: https://www.signcustomiser.com/help/api/v3-put-replace-customiser-pricing/
- Markdown URL: https://www.signcustomiser.com/help/api/v3-put-replace-customiser-pricing.md
- Group: Pricing
- Method: PUT
- Path: /api/v3/customisers/{customiser_id}/pricing
- Auth: Bearer token

## Path parameters

- customiser_id (string, required): The customiser id, from the list customisers operation. Example: 1

## Body parameters

- object (string, optional): No description provided.
- customiser_id (integer, optional): No description provided.
- pricing_model (string, optional): No description provided.
- pricing_model_display_name (string, optional): No description provided.
- currency (string, optional): No description provided.
- sizes (array, optional): No description provided.
- base_pricing (object, optional): No description provided.
- price_lists (array, optional): No description provided.
- sheet_pricing (object, optional): No description provided.

## Request body example

```json
{
  "object": "customiser_pricing",
  "customiser_id": 42,
  "pricing_model": "simple_letter",
  "pricing_model_display_name": "Simple Letter",
  "currency": "USD",
  "sizes": [
    {
      "size_id": 7,
      "client_key": "small",
      "name": "Small",
      "description": "Up to 50cm wide",
      "sort_order": 1,
      "char_limit": 20,
      "line_limit": 3,
      "min_char": 1,
      "width_cm": 50,
      "line_height_cm": 12,
      "sizing_strategy": "fixed_width",
      "height_measurement_mode": "line_height"
    }
  ],
  "base_pricing": {
    "mode": "included_in_price_lists",
    "rows": [
      {
        "size_id": 7,
        "base_price": {
          "line_1": 900,
          "line_2": 1000,
          "line_3": 1100
        }
      }
    ]
  },
  "price_lists": [
    {
      "price_list_id": 10,
      "name": "Standard",
      "shipping": [],
      "rows": [
        {
          "size_id": 7,
          "base_price": {
            "line_1": 1000,
            "line_2": 1200,
            "line_3": 1400
          },
          "letter_price": {
            "line_1": 100,
            "line_2": 120,
            "line_3": 140
          }
        }
      ]
    }
  ],
  "sheet_pricing": {
    "rows": [
      {
        "width_limit_cm": null,
        "height_limit_cm": null,
        "base_price": null,
        "price_per_sq_cm": null
      }
    ]
  }
}
```

## cURL example

```bash
curl https://web.signcustomiser.com/api/v3/customisers/1/pricing \
  --request PUT \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "object": "customiser_pricing",
  "customiser_id": 42,
  "pricing_model": "simple_letter",
  "pricing_model_display_name": "Simple Letter",
  "currency": "USD",
  "sizes": [
    {
      "size_id": 7,
      "client_key": "small",
      "name": "Small",
      "description": "Up to 50cm wide",
      "sort_order": 1,
      "char_limit": 20,
      "line_limit": 3,
      "min_char": 1,
      "width_cm": 50,
      "line_height_cm": 12,
      "sizing_strategy": "fixed_width",
      "height_measurement_mode": "line_height"
    }
  ],
  "base_pricing": {
    "mode": "included_in_price_lists",
    "rows": [
      {
        "size_id": 7,
        "base_price": {
          "line_1": 900,
          "line_2": 1000,
          "line_3": 1100
        }
      }
    ]
  },
  "price_lists": [
    {
      "price_list_id": 10,
      "name": "Standard",
      "shipping": [],
      "rows": [
        {
          "size_id": 7,
          "base_price": {
            "line_1": 1000,
            "line_2": 1200,
            "line_3": 1400
          },
          "letter_price": {
            "line_1": 100,
            "line_2": 120,
            "line_3": 140
          }
        }
      ]
    }
  ],
  "sheet_pricing": {
    "rows": [
      {
        "width_limit_cm": null,
        "height_limit_cm": null,
        "base_price": null,
        "price_per_sq_cm": null
      }
    ]
  }
}'
```

## Response examples

### 200 Replaced document

```json
{
  "data": {
    "object": "customiser_pricing",
    "customiser_id": 42,
    "pricing_model": "simple_letter",
    "pricing_model_display_name": "Simple Letter",
    "currency": "USD",
    "sizes": [
      {
        "size_id": 7,
        "client_key": null,
        "name": "Small",
        "description": "Up to 50cm wide",
        "sort_order": 1,
        "char_limit": 20,
        "line_limit": 3,
        "min_char": 1,
        "width_cm": 50,
        "height_cm": null,
        "line_height_cm": 12,
        "width_multiplier": null,
        "length_cm": null,
        "sizing_strategy": "fixed_width",
        "height_measurement_mode": "line_height"
      }
    ],
    "base_pricing": {
      "mode": "included_in_price_lists",
      "rows": []
    },
    "price_lists": [
      {
        "price_list_id": 10,
        "name": "Standard",
        "rows": [
          {
            "size_id": 7,
            "size_key": null,
            "base_price": {
              "line_1": 1000,
              "line_2": 1200,
              "line_3": 1400
            },
            "letter_price": {
              "line_1": 100,
              "line_2": 120,
              "line_3": 140
            }
          }
        ]
      }
    ],
    "sheet_pricing": null
  },
  "links": {
    "self": "https://web.signcustomiser.com/api/v3/customisers/42/pricing",
    "documentation": "https://www.signcustomiser.com/help/api/"
  },
  "meta": {
    "api_version": "v3",
    "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
  }
}
```

### 400 Malformed JSON body

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

### 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: Authorization: Bearer <api key>. Keys are created in the merchant admin under Integrate → API Tokens.",
  "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 pricing:write scope, but the API key grants the following scopes: pricing:read. Create a key that includes the required scope in the merchant admin under Integrate → API Tokens.",
  "required_scopes": [
    "pricing:write"
  ],
  "granted_scopes": [
    "pricing:read"
  ],
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}
```

### 404 Unknown customiser

```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 Records still referenced

```json
{
  "type": "https://www.signcustomiser.com/help/api/problems/resource_in_use",
  "title": "Resource in use",
  "status": 409,
  "code": "resource_in_use",
  "detail": "The document omits sizes that fonts still reference, so the write would delete records in use. Keep those sizes in the document, or update the fonts that reference them first.",
  "errors": [
    {
      "pointer": "/sizes",
      "code": "resource_in_use",
      "detail": "The document omits sizes that fonts still reference, so the write would delete records in use. Keep those sizes in the document, or update the fonts that reference them first."
    }
  ],
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}
```

### 409 Idempotency key 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. An idempotency key identifies one exact request: retry the original body to replay its response, or send the new body with a fresh key.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}
```

### 422 Validation failed

```json
{
  "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": "/sizes/0/sizing_strategy",
      "code": "unsupported_value",
      "detail": "The selected sizes.0.sizing_strategy is invalid.",
      "allowed_values": [
        "fixed_width",
        "fixed_height"
      ]
    }
  ],
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}
```

### 422 Unknown field

```json
{
  "type": "https://www.signcustomiser.com/help/api/problems/unknown_field",
  "title": "Unknown field",
  "status": 422,
  "code": "unknown_field",
  "detail": "The document contains fields this resource does not define: /sheet_pricing/pricings. Unknown fields are rejected rather than ignored so a typo can never silently change meaning.",
  "errors": [
    {
      "pointer": "/sheet_pricing/pricings",
      "code": "unknown_field",
      "detail": "The field \"pricings\" is not part of the pricing document."
    }
  ],
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}
```

### 429 Rate limited

```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. Wait 60 seconds, then retry.",
  "retry_after": 60,
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}
```