Pricing
create_customiser_length_pricing
destructive writeCreate customiser length pricing
Add a price list that an advanced_letter or frame_fit customiser can charge signs by.
Overview
Creates one length pricing on an advanced_letter or frame_fit customiser: a named price list of boundary rows by sign size. Only name is required. Each row needs base_price in integer minor units of the Store currency, the dimension limits its shipping calculation needs, and outside frame_fit the rate its letter pricing method charges by; dimensions accept centimetres or inch twins. A frame_fit customiser holds exactly one price list, which prices every sign, so a second create is refused. Another pricing model is refused with pricing_model_mismatch. It requires the pricing:write scope and an idempotency_key, and supports dry_run.
Permission
Requires thepricing:writepermission. A connection without it answersinsufficient_scopenaming the permission to approve.
Annotations
Prerequisites
- An advanced_letter or frame_fit customiser id from list_customisers.
- The Store unit_revision from get_store when sending inch twins.
- A merchant has connected this store and approved the pricing:write scope.
Side effects
- Creates one length pricing on one customiser. On a frame_fit customiser it becomes the price list every sign is priced by.
- Clears the customiser cached storefront configuration.
- Spends one unit of the store option-write budget.
- Claims the idempotency_key for at least 24 hours.
Arguments
The customiser id, from list_customisers.
The price list display name.
How letters are charged (closed set): every_letter_cost charges each letter the same, price_by_position charges by letter position from the per-position schedule. Defaults to every_letter_cost.
One of: every_letter_cost, price_by_position
What each row charges letters by (closed set): material_length charges price_per_cm of material, fixed_letter charges price_per_letter. Defaults to fixed_letter.
One of: material_length, fixed_letter
How the shipping dimensions of the finished sign are derived. Defaults to physical with add_weight_to_product false.
physical measures the sign; volumetric measures the box and needs volumetric_divisor (closed set).
One of: physical, volumetric
The divisor the boxed volume is divided by. Required when calculation is volumetric.
The divisor as the merchant authored it, in volumetric_divisor_unit.
The unit volumetric_divisor_authored is in.
One of: cm3_per_kg, in3_per_kg, cm3_per_lb, in3_per_lb
The divisor converted to cubic centimetres per kilogram. Must be greater than 0.
The unit the merchant authored the divisor in.
One of: cm3_per_kg, in3_per_kg, cm3_per_lb, in3_per_lb
Whether the calculated weight is written onto the created product.
The Store unit revision from get_store. The write is refused with stale_revision if the Store unit preferences changed after it was read.
The rows_revision from the last read of this price list. The write is refused with stale_revision if the rows changed after that read.
One boundary row per size band. Defaults to an empty list.
The stable row id from a previous read. Send it back to keep the row identity.
The flat amount a sign in this band costs, in integer minor units of the Store currency.
The amount each letter adds, in integer minor units. Required on a fixed_letter list outside frame_fit.
Only on a price_by_position fixed_letter list: 1 to 100 per-letter prices in integer minor units, the first entry being the first letter.
The amount each centimetre of material adds, in decimal major currency units. Required on a material_length list outside frame_fit.
The inch twin of price_per_cm, in decimal major currency units per inch.
A decimal major-currency rate: per square centimetre for physical shipping, per kilogram of volumetric weight for volumetric shipping.
The square-inch twin of price_per_sq_cm.
The per-pound twin of price_per_sq_cm on a volumetric list.
Whether price_per_sq_cm applies to physical area or volumetric weight (closed set).
One of: per_sq_cm, per_kg_volumetric
The ceiling the row computed price is capped at, as a multiple.
The widest sign this row covers, in centimetres.
The inch twin of width_limit_cm.
The tallest sign this row covers, in centimetres.
The inch twin of height_limit_cm.
The depth boundary this row covers, in centimetres.
The inch twin of length_limit_cm.
The fixed sign depth in centimetres for non-Lightbox volumetric shipping.
The inch twin of fixed_length_cm.
Adjusts the measured width before pricing, in centimetres.
The inch twin of width_modifier.
Adjusts the measured height before pricing, in centimetres.
The inch twin of height_modifier.
Lightbox-only extra parcel depth added for packaging, in centimetres.
The inch twin of length_modifier.
The unit the merchant authored each quantity in, keyed by its centimetre field name.
One of: centimetres, inches
One of: centimetres, inches
One of: centimetres, inches
One of: centimetres, inches
One of: centimetres, inches
One of: centimetres, inches
One of: centimetres, inches
One of: centimetres, inches
One of: centimetres, inches, kilograms, pounds
A client-generated key unique to this logical write, such as a UUID. Required: repeating the call with the same key and the same arguments replays the original result instead of writing twice, and the same key with different arguments is an idempotency_key_conflict.
When true, the price list is checked against the customiser pricing model and the shipping calculation is checked and nothing is written: the result is the same verdict the apply would have reached, and a problem the apply would have raised comes back as the same tool error. Defaults to false. A dry run claims no key.
Result
The created length pricing with every row, in the shape get_customiser_length_pricing returns. A dry run returns the create verdict instead and writes nothing.
The created length pricing with every row. Absent on a dry run.
One of: every_letter_cost, price_by_position
One of: material_length, fixed_letter
The ISO 4217 currency of every integer minor-unit amount on the record.
One of: per_sq_cm, per_kg_volumetric
True when this call replayed a previously recorded response for the same idempotency_key instead of applying the write again.
Present and true only when dry_run was requested.
Present only on a dry run, and always true: a failing dry run returns a tool error instead.
Present only on a dry run: the create verdict.
Error cases
A centimetre field and its inch twin disagree. Send one of them.
The created price list was later deleted. Issue a new key and re-check the resource before writing again.
The connection was approved without pricing:write.
The customiser does not price by advanced_letter or frame_fit, so a length pricing would never be used.
The store option-write budget is spent. Wait retry_after seconds.
No customiser with that id belongs to this store.
The Store units changed after unit_revision was read. Call get_store and rebuild the write.
Remove the field named by pointer; it is not part of a length pricing.
A field is missing or out of range, a row lacks the dimension limits or rate it needs, or a frame_fit customiser already has its one price list. The pointer and the row code name it.
Add a fixed-letter price list with one band
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "create_customiser_length_pricing",
"arguments": {
"customiser_id": 42,
"name": "Standard",
"rows": [
{
"base_price": 4500,
"width_limit_cm": 120,
"height_limit_cm": 60,
"price_per_letter": 600
}
],
"idempotency_key": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f"
}
}
}{
"jsonrpc": "2.0",
"id": 1,
"result": {
"structuredContent": {
"request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
"store": {
"id": 12,
"name": "Demo Signs"
},
"customiser_id": 42,
"length_pricing": {
"id": 9,
"customiser_id": 42,
"name": "Standard",
"letter_pricing_mode": "every_letter_cost",
"letter_pricing_method": "fixed_letter",
"shipping": {
"calculation": "physical",
"volumetric_divisor": null,
"add_weight_to_product": false
},
"currency": "USD",
"rows": [
{
"base_price": 4500,
"width_limit_cm": 120,
"height_limit_cm": 60,
"price_per_letter": 600
}
],
"created_at": "2026-08-13T00:00:00Z",
"updated_at": "2026-08-13T00:00:00Z"
},
"idempotent_replay": false
}
}
}A customiser that does not price by length (error)
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "create_customiser_length_pricing",
"arguments": {
"customiser_id": 43,
"name": "Standard",
"dry_run": true
}
}
}{
"jsonrpc": "2.0",
"id": 1,
"result": {
"isError": true,
"structuredContent": {
"error": {
"code": "pricing_model_mismatch",
"title": "Pricing model mismatch",
"detail": "A length pricing is used only by a customiser that prices by advanced_letter or frame_fit, and this customiser prices by simple_letter. Change the customiser's pricing model first, or write the price list it does use.",
"recovery": "The fields sent do not belong to this customiser pricing model. Read the customiser to see its pricing_model and send only the fields that model accepts."
}
}
}
}