Customiser pricing

Preview a price

Copy page

POST/api/v3/customisers/{customiser_id}/price-preview

Preview a price

Quote what a design would cost in this Store's currency, without creating anything. Send the selections a shopper would have made — text, size, font, letter type, colours, backboard, and any additional input options — and the quote comes back in integer minor units of the Store currency, exactly as the customiser would price the same design. Requires `pricing:read`. The operation persists nothing, takes no `Idempotency-Key`, and is safe to repeat. Measurements are inputs, never derived. Advanced Letter and Frame Fit prices depend on the finished sign's dimensions, and Advanced Letter price lists that charge per centimetre also depend on the measured material length of each word. Those numbers come from measuring the chosen font's glyph outlines, which happens in the customiser, so this operation takes them as `measurements` rather than guessing them. Omit one the price needs and the response is a 422 with code `validation_failed` naming the field. `measurements.material_lengths_cm` carries one length per priced word, in reading order: words are separated by single spaces, and a run of whitespace is not a word. The customiser charges each word separately and rounds each charge, so a single combined length would not always reach the same total. Some designs are refused rather than approximated. A customiser still on the deprecated Fixed Height pricing model answers 422 `unsupported_pricing_model`; a Lightbox customiser, a size that prices a bordered sheet, or a backboard built from layers each carrying its own finish, answers 422 `unsupported_design`. An option id that does not belong to this customiser answers 422 with `unknown_option` and the field's pointer — recover by reading the customiser's option lists (`GET /api/v3/customisers/{customiser_id}/colours` and its siblings). Replace the key after 401, grant `pricing:read` after 403, check the customiser id after 404, and retry a 429 after `retry_after` seconds.

Preview a price

Overview

Requires pricing:read. The operation persists nothing, takes no Idempotency-Key, and is safe to repeat. Measurements are inputs, never derived. Advanced Letter and Frame Fit prices depend on the finished sign's dimensions, and Advanced Letter price lists that charge per centimetre also depend on the measured material length of each word. Those numbers come from measuring the chosen font's glyph outlines, which happens in the customiser, so this operation takes them as measurements rather than guessing them. Omit one the price needs and the response is a 422 with code validation_failed naming the field. measurements.material_lengths_cm carries one length per priced word, in reading order: words are separated by single spaces, and a run of whitespace is not a word. The customiser charges each word separately and rounds each charge, so a single combined length would not always reach the same total. Some designs are refused rather than approximated. A customiser still on the deprecated Fixed Height pricing model answers 422 unsupported_pricing_model; a Lightbox customiser, a size that prices a bordered sheet, or a backboard built from layers each carrying its own finish, answers 422 unsupported_design. An option id that does not belong to this customiser answers 422 with unknown_option and the field's pointer — recover by reading the customiser's option lists (GET/api/v3/customisers/{customiser_id}/colours and its siblings). Replace the key after 401, grant pricing:read after 403, check the customiser id after 404, and retry a 429 after retry_after seconds.

Authorisation

Bearer token required. Include it in theAuthorization header.

Required scope: pricing:read

Path parameters

customiser_idstringpathrequired

The customiser to quote against.

Example: 1

Request body

textstringbody

font_idintegerbody

size_idintegerbody

letter_type_idintegerbody

colour_idsarraybody

backboard_idintegerbody

support_finish_idintegerbody

jacket_idintegerbody

mounting_idintegerbody

mounting_colour_idintegerbody

backlight_idintegerbody

material_idintegerbody

extrasarraybody

measurementsobjectbody

Request body example

{
  "text": "OPEN",
  "font_id": 41,
  "size_id": 210,
  "letter_type_id": 68,
  "colour_ids": [
    1018
  ],
  "backboard_id": 320,
  "support_finish_id": 512,
  "jacket_id": 88,
  "mounting_id": 91,
  "mounting_colour_id": 74,
  "backlight_id": 33,
  "material_id": 27,
  "extras": [
    {
      "extra_id": 12,
      "value": "matte"
    }
  ],
  "measurements": {
    "width_cm": 50,
    "height_cm": 25.4,
    "material_lengths_cm": [
      128.4
    ],
    "length_cm": 5
  }
}

Preview a price

curl https://web.signcustomiser.com/api/v3/customisers/1/price-preview \
  --request POST \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "text": "OPEN",
  "font_id": 41,
  "size_id": 210,
  "letter_type_id": 68,
  "colour_ids": [
    1018
  ],
  "backboard_id": 320,
  "support_finish_id": 512,
  "jacket_id": 88,
  "mounting_id": 91,
  "mounting_colour_id": 74,
  "backlight_id": 33,
  "material_id": 27,
  "extras": [
    {
      "extra_id": 12,
      "value": "matte"
    }
  ],
  "measurements": {
    "width_cm": 50,
    "height_cm": 25.4,
    "material_lengths_cm": [
      128.4
    ],
    "length_cm": 5
  }
}'

{
  "data": {
    "object": "price_preview",
    "customiser_id": 74,
    "pricing_model": "simple_letter",
    "pricing_model_display_name": "Simple Letter",
    "currency": "USD",
    "amount": 5900,
    "subtotal_amount": 5900,
    "discount_amount": 0,
    "letter_count": 5,
    "line_count": 1
  },
  "links": {
    "self": "https://web.signcustomiser.com/api/v3/customisers/74/price-preview",
    "documentation": "https://www.signcustomiser.com/help/api/"
  },
  "meta": {
    "api_version": "v3",
    "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 pricing:read scope.",
  "required_scopes": [
    "pricing:read"
  ],
  "granted_scopes": [],
  "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": "No customiser matches that id for this Store.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/validation_failed",
  "title": "Validation failed",
  "status": 422,
  "code": "validation_failed",
  "detail": "This price depends on the sign's measured size, which this API never derives. Send measurements.width_cm.",
  "errors": [
    {
      "pointer": "/measurements/width_cm",
      "code": "measurement_required",
      "detail": "This price depends on the sign's measured size, which this API never derives. Send measurements.width_cm."
    }
  ],
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/unsupported_design",
  "title": "Unsupported design",
  "status": 422,
  "code": "unsupported_design",
  "detail": "Lightbox customisers price their face colours through the letter-type colour sets, which this operation does not read yet.",
  "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": 60,
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}