Pricing

Replace customiser pricing

Copy page

Replace the customiser's entire pricing configuration with the request body — the full canonical document, exactly as the read operation returns it (no envelope).

PUT/api/v3/customisers/{customiser_id}/pricing

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.

Replace customiser pricing

Overview

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.

Authorisation

Bearer token required. Include it in theAuthorization header.

Required scope: pricing:write

Path parameters

customiser_idstringpathrequired

The customiser id, from the list customisers operation.

Example: 1

Request body

objectstringbody

customiser_idintegerbody

pricing_modelstringbody

pricing_model_display_namestringbody

currencystringbody

sizesarraybody

base_pricingobjectbody

price_listsarraybody

sheet_pricingobjectbody

Request body example

{
  "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": []
  },
  "price_lists": [
    {
      "price_list_id": 10,
      "name": "Standard",
      "letter_pricing_mode": "price_by_position",
      "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
          },
          "letter_price_by_position": {
            "line_1": [
              0,
              100
            ],
            "line_2": [
              0,
              120
            ],
            "line_3": [
              0,
              140
            ]
          }
        }
      ]
    }
  ],
  "sheet_pricing": {
    "rows": [
      {
        "width_limit_cm": 100,
        "height_limit_cm": 60,
        "base_price": 2000,
        "price_per_sq_cm": 1.5
      }
    ]
  }
}

Replace customiser pricing

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": []
  },
  "price_lists": [
    {
      "price_list_id": 10,
      "name": "Standard",
      "letter_pricing_mode": "price_by_position",
      "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
          },
          "letter_price_by_position": {
            "line_1": [
              0,
              100
            ],
            "line_2": [
              0,
              120
            ],
            "line_3": [
              0,
              140
            ]
          }
        }
      ]
    }
  ],
  "sheet_pricing": {
    "rows": [
      {
        "width_limit_cm": 100,
        "height_limit_cm": 60,
        "base_price": 2000,
        "price_per_sq_cm": 1.5
      }
    ]
  }
}'

{
  "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",
        "letter_pricing_mode": "price_by_position",
        "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
            },
            "letter_price_by_position": {
              "line_1": [
                0,
                100
              ],
              "line_2": [
                0,
                120
              ],
              "line_3": [
                0,
                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"
  }
}

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

{
  "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/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"
}

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

{
  "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": "/price_lists/0/letter_pricing_mode",
      "code": "unsupported_value",
      "detail": "The selected price_lists.0.letter_pricing_mode is invalid.",
      "allowed_values": [
        "every_letter_cost",
        "price_by_position"
      ]
    }
  ],
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

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

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