Sign Customiser

Navigation

Dark mode

Customisers

set_authoring_customiser_language

destructive write

Set authoring customiser language

Copy page

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

readOnlyHintfalse
destructiveHinttrue
idempotentHinttrue
openWorldHinttrue

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

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 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.

plan_tokenstringrequired unless dry_run is true

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.

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 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.

request_idstringalways present
storeobjectalways present
store.idintegeralways present
store.namestringalways present
customiser_idintegeralways present
languageobject

The language after the change. 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 verdict, with replaced_draft_count, cleared_optional_count and plan_token.

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 running on the customiser. Wait for it to finish, or cancel it with cancel_customiser_language_translation.

confirmation_required

Send confirm true once the merchant has agreed to the change. Nothing changed.

insufficient_scope

The connection was approved without customisers:write.

language_not_authorable

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.

rate_limited

The store option-write budget is spent. Wait retry_after seconds.

resource_not_found

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

stale_revision

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

tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "set_authoring_customiser_language",
    "arguments": {
      "customiser_id": 42,
      "language_code": "fr",
      "dry_run": true
    }
  }
}
result
{
  "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)

tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "set_authoring_customiser_language",
    "arguments": {
      "customiser_id": 42,
      "language_code": "de",
      "dry_run": true
    }
  }
}
result
{
  "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"
      }
    }
  }
}

Type a question and press Enter. Use the arrow keys to move between the results.