Customisers
update_customiser_text_template
destructive writeUpdate customiser text template
Set up or change the fixed text fields of a customiser, or remove them.
Overview
Replaces a customiser text template (its fixed lines, and on cut-out metal with Frame Fit its graphic areas, production artwork, mounting holes and manufacturing rules) with a whole new document, or removes it when template is null. Template lengths are millimetres. Send the revision read from get_customiser with include text_template; a stale revision is refused. Production and graphic artwork come from import_customiser_text_template_artwork. It requires the customisers:write scope, takes an optional idempotency_key, supports dry_run, and a removal requires confirm: true.
Permission
Requires thecustomisers:writepermission. A connection without it answersinsufficient_scopenaming the permission to approve.
Annotations
Prerequisites
- A customiser id from list_customisers.
- The current text_template from get_customiser, for its revision and the document to change.
- A merchant has connected this store and approved the customisers:write scope.
Side effects
- Changes the customer customiser at once, and clears its cached configuration.
- Writes line labels, default wording and area descriptions in the authoring language.
Arguments
The customiser id, from list_customisers.
The template revision you read, or null when the customiser has none.
The whole template as get_customiser returns it in text_template.template, changed and without key and revision; null removes the template. New lines and areas send id null.
Must be true to apply the change, because removing the template takes the text fields off the customer customiser. Without it the call returns a confirmation_required error and changes nothing.
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 replacement or removal 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. A dry run does not require the confirm argument.
Result
The text template document as it now stands, the shape get_customiser returns in text_template. A dry run returns the validation verdict and writes nothing.
The text template document as it now stands. Absent on a dry run.
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 validation verdict.
The translation keys of the unpublished Languages drafts that this write replaced in the authoring language. This member is present only when the write replaced a draft. Tell the merchant that the replaced draft is gone.
True when this call replayed a previously recorded response for the same idempotency_key instead of applying the write again.
Error cases
Send confirm: true to remove the template.
The connection was approved without customisers:write.
The template changed after it was read. Read it again with get_customiser, reapply the change, and send its revision.
Text fields are not available for this Store.
Only LED neon and cut-out metal with Frame Fit carry text fields.
Add a width-based size on the Sizes page that the price list covers, then retry.
Remove the key named by pointer; read-only key and revision belong outside template.
A rule of the document is broken. Each error names the rule code and the pointer to fix.
Remove a template
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "update_customiser_text_template",
"arguments": {
"customiser_id": 42,
"revision": 3,
"template": null,
"confirm": true
}
}
}{
"jsonrpc": "2.0",
"id": 1,
"result": {
"structuredContent": {
"request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
"store": {
"id": 12,
"name": "Demo Signs"
},
"idempotent_replay": false,
"customiser_id": 42,
"text_template": {
"customiser_id": 42,
"availability": "available",
"sign_kind": "neon",
"template": null,
"offered_sizes": {
"presets": [
{
"size_id": 7,
"width_cm": 60,
"width_in": 23.6220472,
"authored_units": {
"width_cm": "centimetres"
}
}
],
"custom": null,
"custom_minimum_set": false,
"dropped": []
}
}
}
}
}A removal without confirmation changes nothing (error)
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "update_customiser_text_template",
"arguments": {
"customiser_id": 42,
"revision": 3,
"template": null
}
}
}{
"jsonrpc": "2.0",
"id": 1,
"result": {
"isError": true,
"structuredContent": {
"error": {
"code": "confirmation_required",
"title": "Confirmation required",
"detail": "Removing the text template takes its text fields off the customer customiser.",
"recovery": "This operation changes something consequential. Send confirm: true once the merchant has agreed to it.",
"parameter": "confirm",
"allowed_values": [
"true"
]
}
}
}
}