Customisers
set_authoring_customiser_language
destructive writeSet authoring customiser language
Change which language the merchant writes the customiser text in, after the merchant has agreed to it.
Overview
Makes one customiser language the authoring language, the language whose copy owns the option, selection, setting, letter-part and form text; the other languages are then translated from it. The language must be published with a current published value for every required key, otherwise the call is refused with language_not_authorable, and no AI translation may be running on the customiser. The change can replace draft values the language holds for that text and clear optional text it has no value for: run dry_run true first, which reports replaced_draft_count, cleared_optional_count and a plan_token, and tell the merchant. Then apply with that plan_token and confirm true; if the language changed since the dry run the call is refused with stale_revision and changes nothing. It requires the customisers:write scope and an idempotency_key.
Permission
Requires thecustomisers:writepermission. A connection without it answersinsufficient_scopenaming the permission to approve.
Annotations
Prerequisites
- A customiser id from list_customisers and a language code from list_customiser_languages.
- A published language whose required published copy is complete; publish_customiser_language publishes it.
- A dry run, whose counts the merchant has seen, and its plan_token.
- The merchant explicit agreement, sent as confirm true.
- A merchant has connected this store and approved the customisers:write scope.
Side effects
- Makes this language the authoring language and removes the flag from the previous one.
- Replaces the draft values of the owned text with the published values, and clears optional owned text the language has no value for.
- Clears the customiser cached storefront configuration and runs the language sync.
- 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 BCP 47 language tag the language is addressed by, such as fr or pt-BR, from list_customiser_languages.
Must be true to apply the change, because the owned text is then written in this language, and its draft and missing optional copy of that text is replaced or cleared. Without it the call returns a confirmation_required error and changes nothing.
The plan_token the dry run returned. It binds the change to the counts the merchant saw. Required unless dry_run is true; on a dry run it is checked instead.
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 change, with its replaced_draft_count and cleared_optional_count, 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 language record after the change. A dry run returns the verdict, with replaced_draft_count, cleared_optional_count and plan_token, and changes nothing.
The language after the change. 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 verdict, with replaced_draft_count, cleared_optional_count and plan_token.
True when this call replayed a previously recorded response for the same idempotency_key instead of applying the write again.
Error cases
An AI translation is running on the customiser. Wait for it to finish, or cancel it with cancel_customiser_language_translation.
Send confirm true once the merchant has agreed to the change. Nothing changed.
The connection was approved without customisers:write.
Read reason. not_published: publish the language first. incomplete_published_translations: write and publish its missing required copy first. no_authoring_language: the customiser has no authoring language to hand over from.
The store option-write budget is spent. Wait retry_after seconds.
No customiser with that id, or no language with that code on it.
The language changed after the dry run. Run dry_run true again, show the merchant the new counts, and send the new plan_token.
Check the change first
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "set_authoring_customiser_language",
"arguments": {
"customiser_id": 42,
"language_code": "fr",
"dry_run": true
}
}
}{
"jsonrpc": "2.0",
"id": 1,
"result": {
"structuredContent": {
"request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
"store": {
"id": 12,
"name": "Demo Signs"
},
"customiser_id": 42,
"dry_run": true,
"valid": true,
"verdict": {
"operation": "set_authoring",
"customiser_id": 42,
"language_code": "fr",
"replaced_draft_count": 3,
"cleared_optional_count": 1,
"plan_token": "9c1e4f0b2a7d4e8f9a6b3c5d7e1f2a4b6c8d0e2f4a6b8c0d2e4f6a8b0c2d4e6f"
}
}
}
}A draft language cannot be the authoring language (error)
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "set_authoring_customiser_language",
"arguments": {
"customiser_id": 42,
"language_code": "de",
"dry_run": true
}
}
}{
"jsonrpc": "2.0",
"id": 1,
"result": {
"isError": true,
"structuredContent": {
"error": {
"code": "language_not_authorable",
"title": "Language not eligible to be the authoring language",
"detail": "The authoring language owns the option, selection, setting, letter-part and form text, so it must be published with a current value for each required key. Publish this language first, then retry.",
"recovery": "Read reason. For not_published, publish the language first. For incomplete_published_translations, write and publish its missing required copy first. For no_authoring_language, the customiser has no authoring language to hand over from. Then retry.",
"reason": "not_published"
}
}
}
}