Customiser languages
Set the authoring language
Makes a published, complete language the customiser's authoring language, the one whose rows own the option, selection, setting, letter-part and form text, as the merchant admin's "Make primary language" does. The other languages' copy of that text is then translated from it.
Overview
The change can replace draft values the language
holds for that text with its published values, and clear optional text
it has no value for. So call the validate twin first: it reports
replaced_draft_count and cleared_optional_count and returns a
plan_token. Confirm the counts with the merchant, then send the token
here. If the language's copy changed since the check, so the counts would
now differ, the write is refused with 409 stale_revision and changes
nothing: validate again. Making the current authoring language authoring
again changes nothing.
Refusals: 422 language_not_authorable with reason not_published,
incomplete_published_translations or no_authoring_language; 409
ai_translation_in_progress while any AI translation runs on the
customiser; 409 stale_revision for a stale plan_token. Requires customisers:write and an Idempotency-Key. The
write clears the storefront cache and runs the language sync; it never
regenerates Shopify products.
Authorisation
Bearer token required. Include it in the Authorization header.
Required scope: customisers:write
Path parameters
The customiser id.
Example: 1
The language tag.
Example: fr
Request body
Request body example
{
"plan_token": "9c1e4f0b2a7d4e8f9a6b3c5d7e1f2a4b6c8d0e2f4a6b8c0d2e4f6a8b0c2d4e6f"
}curl https://web.signcustomiser.com/api/v3/customisers/1/languages/fr/authoring \
--request POST \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"plan_token": "9c1e4f0b2a7d4e8f9a6b3c5d7e1f2a4b6c8d0e2f4a6b8c0d2e4f6a8b0c2d4e6f"
}'{
"data": {
"object": "customiser_language",
"customiser_id": 42,
"language_code": "fr",
"source_language_code": "en",
"display_name": "French",
"status": "published",
"is_default": false,
"is_authoring": true,
"translation_summary": {
"key_count": 184,
"required_key_count": 96,
"translated_key_count": 184,
"retired_key_count": 0,
"missing_required_key_count": 0,
"publishable": true
},
"ai_translation": null,
"published_at": "2026-05-04T09:12:31Z",
"created_at": "2026-05-04T09:09:00Z",
"updated_at": "2026-05-04T09:14:02Z"
},
"links": {
"self": "https://web.signcustomiser.com/api/v3/customisers/42/languages/fr/authoring",
"documentation": "https://www.signcustomiser.com/help/api/"
},
"meta": {
"api_version": "v3",
"request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}
}{
"type": "https://www.signcustomiser.com/help/api/problems/insufficient_scope",
"title": "Insufficient scope",
"status": 403,
"code": "insufficient_scope",
"detail": "This operation requires the customisers:write scope.",
"required_scopes": [
"customisers:write"
],
"granted_scopes": [
"customisers:read"
],
"request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}{
"type": "https://www.signcustomiser.com/help/api/problems/stale_revision",
"title": "Stale revision",
"status": 409,
"code": "stale_revision",
"detail": "The language's copy changed after the plan_token was issued, so this change would now replace or clear different copy. Validate the change again and send the new plan_token.",
"errors": [
{
"pointer": "/plan_token",
"code": "stale_revision",
"detail": "The plan_token is stale."
}
],
"request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}{
"type": "https://www.signcustomiser.com/help/api/problems/language_not_authorable",
"title": "Language not eligible to be the authoring language",
"status": 422,
"code": "language_not_authorable",
"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.",
"reason": "not_published",
"request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}