Customisers
cancel_customiser_language_translation
destructive writeCancel customiser language translation
Stop a running AI translation, usually so the language can be published or deleted, after the merchant has agreed to it.
Overview
Stops the queued or running AI translation that is writing a customiser language draft copy. The translation is marked cancelled and a language in the translating status returns to draft. Draft values already written are kept. A cancelled translation cannot be resumed through this connector: a new translation can only be started in the merchant admin. Cancelling unblocks a publish or a delete refused with ai_translation_in_progress. It is refused with ai_translation_not_cancellable when no translation is queued or running. The call requires confirm true and changes nothing without it; dry_run true checks the cancel without stopping anything. 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 queued or running AI translation; the ai_translation member of get_customiser_language shows its status.
- The merchant explicit agreement, sent as confirm true.
- A merchant has connected this store and approved the customisers:write scope.
Side effects
- Marks the running AI translation cancelled and stops its remaining work. It cannot be resumed.
- Returns a language in the translating status to draft. Draft values already written are kept.
- Clears the customiser cached storefront configuration and runs the language sync.
- 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 running AI translation stops and cannot be resumed through this connector. Without it the call returns a confirmation_required error and changes nothing.
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 cancel is checked against the state of the latest AI translation 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 cancel, whose ai_translation status is cancelled. A dry run returns the cancel verdict instead and stops nothing.
The language after the cancel. 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 cancel verdict.
True when this call replayed a previously recorded response for the same idempotency_key instead of applying the write again.
Error cases
Read reason. no_translation: the language never had one. not_running: the most recent translation already finished, failed or was cancelled.
Send confirm true once the merchant has agreed to stop the translation. Nothing was cancelled.
The language changed after the recorded cancel. Issue a new key and re-check the language before writing again.
The connection was approved without customisers:write.
No customiser with that id, or no language with that code on it.
The translation changed state while the cancel ran. Read the language again.
Stop a running translation the merchant asked to cancel
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "cancel_customiser_language_translation",
"arguments": {
"customiser_id": 42,
"language_code": "fr",
"confirm": true,
"idempotency_key": "f2a3b4c5-d6e7-4f89-90a1-b2c3d4e5f607"
}
}
}{
"jsonrpc": "2.0",
"id": 1,
"result": {
"structuredContent": {
"request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
"store": {
"id": 12,
"name": "Demo Signs"
},
"customiser_id": 42,
"language": {
"language_code": "fr",
"source_language_code": "en",
"display_name": "French",
"status": "draft",
"is_default": false,
"is_authoring": false,
"translation_summary": {
"key_count": 184,
"required_key_count": 96,
"translated_key_count": 40,
"retired_key_count": 0,
"missing_required_key_count": 70,
"publishable": false
},
"ai_translation": {
"object": "language_ai_translation",
"status": "cancelled",
"cancellable": false,
"chunks_total": 4,
"keys_targeted": 184,
"error_summary": null,
"started_at": "2026-05-04T09:20:00Z",
"finished_at": "2026-05-04T09:30:00Z",
"created_at": "2026-05-04T09:19:58Z",
"updated_at": "2026-05-04T09:30:00Z"
},
"published_at": null,
"updated_at": "2026-05-04T09:30:00Z"
},
"idempotent_replay": false
}
}
}No translation is running (error)
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "cancel_customiser_language_translation",
"arguments": {
"customiser_id": 42,
"language_code": "fr",
"dry_run": true
}
}
}{
"jsonrpc": "2.0",
"id": 1,
"result": {
"isError": true,
"structuredContent": {
"error": {
"code": "ai_translation_not_cancellable",
"title": "AI translation not cancellable",
"detail": "The language's most recent AI translation is completed, so there is nothing to cancel. Only a queued or running translation can be cancelled; a finished one is already in its final state.",
"recovery": "There is no queued or running AI translation to cancel. Read reason, and read the language ai_translation to see the state of its latest translation.",
"reason": "not_running"
}
}
}
}