Customisers

delete_customiser_language

destructive write

Delete customiser language

Copy page

Remove a language from a customiser after the merchant has agreed to it.

Overview

Deletes one customiser language and every translation it holds. There is no restore, and a published language leaves the live storefront, so the call requires confirm true and changes nothing without it. The default language, the only published language and the authoring language cannot be deleted, and a language with an AI translation still running is refused until it finishes or is cancelled. Calling with dry_run true first returns the same verdict without deleting 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

readOnlyHintfalse

destructiveHinttrue

idempotentHinttrue

openWorldHinttrue

Prerequisites

A customiser id from list_customisers and a language code from list_customiser_languages.
The merchant explicit agreement, sent as confirm true.
A merchant has connected this store and approved the customisers:write scope.

Side effects

Deletes the language and every translation row it holds permanently.
Removes the language from the live storefront if it was published.
Clears the customiser cached storefront configuration and runs the language sync.
Claims the idempotency_key for at least 24 hours.

Arguments

customiser_idintegerrequired

The customiser id, from list_customisers.

language_codestringrequired

The BCP 47 language tag the language is addressed by, such as fr or pt-BR, from list_customiser_languages.

confirmbooleanrequired unless dry_run is true

Must be true to apply the change, because the language and every translation it holds are removed permanently, and a published language leaves the storefront. Without it the call returns a confirmation_required error and changes nothing.

idempotency_keystringrequired unless dry_run is true

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.

dry_runboolean

When true, the deletion is checked against the default, authoring and published-language rules, any running AI translation, and the records that reference the language 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 deleted language code and the language record as it was immediately before deletion. A dry run returns the delete verdict instead and deletes nothing.

request_idstringalways present

storeobjectalways present

store.idintegeralways present

store.namestringalways present

customiser_idintegeralways present

language_codestringalways present

The language code that was addressed.

deletedboolean

True when the language was deleted. Absent on a dry run, where nothing is deleted.

languageobject

The language as it was immediately before deletion, so the caller can report what it removed. Absent on a dry run.

language.language_codestringalways present

language.source_language_codestring or null

language.display_namestring or null

language.statusstringalways present

language.is_defaultbooleanalways present

language.is_authoringbooleanalways present

language.translation_summaryobject or null

language.ai_translationobject or null

language.published_atstring or null

language.updated_atstring or null

dry_runboolean

Present and true only when dry_run was requested.

validboolean

Present only on a dry run, and always true: a failing dry run returns a tool error instead.

verdictobject

Present only on a dry run: the delete verdict.

idempotent_replayboolean

True when this call replayed a previously recorded response for the same idempotency_key instead of applying the write again.

Error cases

ai_translation_in_progress

An AI translation is still writing this language. Wait for it to finish, or stop it with cancel_customiser_language_translation, then retry.

confirmation_required

Send confirm true once the merchant has agreed to the deletion. Nothing was deleted.

idempotency_subject_changed

The language changed after the recorded deletion. Issue a new key and re-check the language before writing again.

insufficient_scope

The connection was approved without customisers:write.

language_not_deletable

Read reason. default_language or sole_published_language: publish another language and make it the default first. authoring_language: the authoring language cannot be deleted.

resource_in_use

Other records still reference the language; referenced_by names them.

resource_not_found

No customiser with that id, or no language with that code on it.

Delete a draft language the merchant confirmed

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "delete_customiser_language",
    "arguments": {
      "customiser_id": 42,
      "language_code": "fr",
      "confirm": true,
      "idempotency_key": "c9d0e1f2-a3b4-4c56-8d78-e9f0a1b2c3d4"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "customiser_id": 42,
      "language_code": "fr",
      "deleted": true,
      "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": 12,
          "retired_key_count": 0,
          "missing_required_key_count": 84,
          "publishable": false
        },
        "ai_translation": null,
        "published_at": null,
        "updated_at": "2026-05-04T09:11:20Z"
      },
      "idempotent_replay": false
    }
  }
}

Without confirmation nothing is deleted (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "delete_customiser_language",
    "arguments": {
      "customiser_id": 42,
      "language_code": "fr",
      "confirm": false,
      "idempotency_key": "c9d0e1f2-a3b4-4c56-8d78-e9f0a1b2c3d4"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "confirmation_required",
        "title": "Confirmation required",
        "detail": "Deleting language fr removes it and every translation it holds permanently, and takes it off the storefront if it is published.",
        "recovery": "This operation changes something consequential. Send confirm: true once the merchant has agreed to it.",
        "parameter": "confirm",
        "allowed_values": [
          "true"
        ]
      }
    }
  }
}

The default language cannot be deleted (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "delete_customiser_language",
    "arguments": {
      "customiser_id": 42,
      "language_code": "en",
      "dry_run": true
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "language_not_deletable",
        "title": "Language not deletable",
        "detail": "A customiser must always keep one published default language, because it is the copy the storefront falls back to. Publish another language and make it the default before removing this one.",
        "recovery": "Read reason. For default_language or sole_published_language, publish another language and make it the default first. For authoring_language, the language owns the option and form text and cannot be deleted.",
        "reason": "default_language"
      }
    }
  }
}