Pricing
update_customiser_length_pricing
destructive writeUpdate customiser length pricing
Change the name, letter pricing, shipping settings or boundary rows of one length pricing.
Overview
Changes one length pricing of an advanced_letter or frame_fit customiser with a JSON merge patch: fields you omit stay as they are, shipping merges member by member, and sending rows replaces every boundary row. base_price and price_per_letter are integer minor units of the Store currency; dimensions accept centimetres or inch twins. The patch is judged against the state it would leave, so a change of shipping calculation or letter pricing method that the rows cannot carry is refused. Signs priced by this list use the new prices on the storefront. It requires the pricing:write scope, takes an optional idempotency_key for replay, and supports dry_run.
Permission
Requires thepricing:writepermission. A connection without it answersinsufficient_scopenaming the permission to approve.
Annotations
Prerequisites
- A customiser id from list_customisers and a length pricing id from list_customiser_length_pricings.
- The current price list from get_customiser_length_pricing, because rows is replaced whole.
- 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
- Changes what every sign priced by this list costs on the storefront.
- Clears the customiser cached storefront configuration.
- Spends one unit of the store option-write budget.
Arguments
The customiser id, from list_customisers.
The length pricing id, from list_customiser_length_pricings.
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.
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.
One of: material_length, fixed_letter
The shipping members to change. Members you omit are left as they are.
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.
Every boundary row of the price list. Sending rows replaces the whole set, and an empty list clears it. A row sent without price_per_letter_by_position keeps the schedule it already had; send null to clear one.
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
An optional client-generated key unique to this logical write, such as a UUID. Repeating the call with the same key and the same arguments replays the original result; the route does not require one.
When true, the patch is checked against the state it would leave 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 length pricing as it now stands, with every row. A dry run returns the update verdict instead and writes nothing.
The length pricing as it now stands, 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 update verdict.
Error cases
A centimetre field and its inch twin disagree. Send one of them.
The price list was deleted after the recorded update. Issue a new key and re-check the resource before writing again.
The connection was approved without pricing:write.
The customiser no longer prices by advanced_letter or frame_fit, so its length pricings cannot be changed.
The store option-write budget is spent. Wait retry_after seconds.
No length pricing with that id belongs to that customiser in this store.
The Store units or the rows changed after they were read. Read them again and rebuild the patch.
Remove the field named by pointer; it is not part of a length pricing.
A field is out of range, or a row would lack the dimension limits, divisor or rate the resulting settings need. The pointer and the row code name it.
Rename a price list
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "update_customiser_length_pricing",
"arguments": {
"customiser_id": 42,
"length_pricing_id": 9,
"name": "Trade"
}
}
}{
"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": "Trade",
"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": [],
"created_at": "2026-08-13T00:00:00Z",
"updated_at": "2026-08-13T00:05:00Z"
},
"idempotent_replay": false
}
}
}Volumetric shipping without a divisor (error)
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "update_customiser_length_pricing",
"arguments": {
"customiser_id": 42,
"length_pricing_id": 9,
"shipping": {
"calculation": "volumetric"
},
"dry_run": true
}
}
}{
"jsonrpc": "2.0",
"id": 1,
"result": {
"isError": true,
"structuredContent": {
"error": {
"code": "validation_failed",
"title": "Validation failed",
"detail": "Volumetric shipping divides the boxed volume by a divisor, so shipping.volumetric_divisor is required whenever the calculation is volumetric.",
"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": "/shipping/volumetric_divisor"
}
}
}
}