Pricing
preview_price
readPreview a price
Answer "what would this cost?" for one design, at the price the customiser itself would charge.
Overview
Quotes what one sign design would cost in the Store currency, without creating an order, a quote or anything else. Send the selections a shopper would have made — text, size, font, letter type, colours, backboard, mounting and any additional input options — and the customiser own price engine answers with the total in integer minor units. Advanced Letter and Frame Fit prices also need the design measured geometry, which this surface never derives, so send it in measurements. It requires the pricing:read scope, has no side effects and is safe to retry.
Permission
Requires thepricing:readpermission. A connection without it answersinsufficient_scopenaming the permission to approve.
Annotations
Prerequisites
- A customiser id from list_customisers.
- The option ids the design uses, from list_customiser_options for each family the price depends on.
- For Advanced Letter and Frame Fit pricing, and for an area-priced backboard, the measured width and height of the finished sign.
- A merchant has connected this store and approved the pricing:read scope.
Arguments
The customiser to quote against, from list_customisers.
The sign text. Newlines separate lines, and a line with no visible characters is not priced.
The chosen font. Simple and Advanced Letter pricing reach their price list through it, so both require it.
The chosen size. Simple Letter pricing prices per size and requires it.
The chosen letter type.
Every distinct colour applied to the design. A colour is charged once however many letters carry it.
The chosen backboard. An area-priced backboard charges area times rate, and then needs measurements.
The chosen backboard finish.
The chosen jacket.
The chosen mounting.
The chosen mounting colour.
The chosen backlight colour.
The chosen material.
The additional input options the shopper chose. Listing one is what selects it.
The additional input option.
The chosen value, for a select or image-select extra. Omit it for a checkbox: listing the extra is what charges it.
The design measured geometry. This surface never measures glyphs, so any dimension the price depends on is an input.
Final sign width in centimetres. Required by Advanced Letter and Frame Fit pricing, and by an area-priced backboard.
Final sign height in centimetres. Required wherever width_cm is.
Final sign depth in centimetres. Only volumetric shipping bands read it.
One measured material length per priced word, in reading order. Required by Advanced Letter price lists that charge per centimetre, which round each word separately.
Result
One quote: the customiser pricing model, the Store currency, and the total with its subtotal and discount, all in integer minor units, beside the letter and line counts the price was computed from.
The pricing model the quote was computed under.
One of: simple_letter, advanced_letter, frame_fit
The ISO 4217 currency every amount is expressed in, as integer minor units, or null when the Store has no valid currency configured.
The quoted total, in integer minor units.
The total before any discount.
What the customiser own discount rules took off.
The priced characters the quote counted.
The lines carrying visible characters.
Error cases
The connection was approved without pricing:read. A connection holding only customisers:read can read the customiser but not price a design against it.
No customiser with that id belongs to this store. Call list_customisers to rediscover a valid id.
An option id does not belong to this customiser. Read the family with list_customiser_options and send an id it returns.
The design uses a shape this quote does not compute: a Lightbox customiser, a size that prices a bordered sheet, or a layered backboard whose layers each carry a finish. Price it in the customiser instead.
The customiser is still on the deprecated Fixed Height pricing model, which this quote does not compute.
An argument was missing or malformed. A price that depends on the sign measured size names the missing member — measurements.width_cm, measurements.height_cm or measurements.material_lengths_cm — under the pointer of the error row.
Quote a five-letter Simple Letter sign
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "preview_price",
"arguments": {
"customiser_id": 74,
"text": "HELLO",
"font_id": 41,
"size_id": 210,
"colour_ids": [
1018
]
}
}
}{
"jsonrpc": "2.0",
"id": 1,
"result": {
"structuredContent": {
"request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
"store": {
"id": 12,
"name": "Demo Signs"
},
"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
}
}
}An Advanced Letter design sent without its measured width (error)
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "preview_price",
"arguments": {
"customiser_id": 74,
"text": "OPEN",
"font_id": 41
}
}
}{
"jsonrpc": "2.0",
"id": 1,
"result": {
"isError": true,
"structuredContent": {
"error": {
"code": "validation_failed",
"title": "Validation failed",
"detail": "This price depends on the sign's measured size, which this API never derives. Send measurements.width_cm.",
"recovery": "Correct every field listed in errors, using its pointer to locate the value and allowed_values where one is given, then call the tool again.",
"pointer": "/measurements/width_cm"
}
}
}
}