Customiser languages

Publish a customiser language

Copy page

Promote the language draft copy to its published copy, which is what the storefront serves. Publishing is the only operation that changes what a shopper sees: writing draft values never does.

POST/api/v3/customisers/{customiser_id}/languages/{language_code}/publish

Publish a customiser language

Promote the language draft copy to its published copy, which is what the storefront serves. Publishing is the only operation that changes what a shopper sees: writing draft values never does. The gate is required copy. A 422 problem with code `language_publish_blocked` lists every required key whose draft value is still blank in `missing_keys`; write those, then retry. Stale values — copy whose source has changed since it was translated — do not block publishing: they publish, stay flagged as stale on the translations read, and remain reviewable. A 409 problem with code `ai_translation_in_progress` means an AI translation is still writing the draft; wait for it, or cancel it, then retry. Publishing the authoring language (`is_authoring: true`) also writes each changed option, selection, setting, letter-part and form value to its entity in the same transaction. The option, extra, settings and form reads then return the new text. A draft value can break the rules of its field, for example by being too long. The publish is then refused with a 422 `validation_failed` problem that names the key, and nothing is published. Publishing is idempotent in the domain sense as well as the protocol sense: publishing an already-published language re-promotes its current draft values, which is how a merchant pushes reviewed changes live. The write clears the customiser cached storefront configuration and runs the advisory language sync; it never regenerates your Shopify products, product images, or product cache. An `Idempotency-Key` header is required. Requires the `customisers:write` scope. A 400 problem means the `Idempotency-Key` header is missing or malformed. 401, 403, 404, and 429 problems behave as on the read operation, with `customisers:write` as the required scope.

Publish a customiser language

Overview

The gate is required copy. A 422 problem with code language_publish_blocked lists every required key whose draft value is still blank in missing_keys; write those, then retry. Stale values — copy whose source has changed since it was translated — do not block publishing: they publish, stay flagged as stale on the translations read, and remain reviewable. A 409 problem with code ai_translation_in_progress means an AI translation is still writing the draft; wait for it, or cancel it, then retry. Publishing the authoring language (is_authoring: true) also writes each changed option, selection, setting, letter-part and form value to its entity in the same transaction. The option, extra, settings and form reads then return the new text. A draft value can break the rules of its field, for example by being too long. The publish is then refused with a 422 validation_failed problem that names the key, and nothing is published. Publishing is idempotent in the domain sense as well as the protocol sense: publishing an already-published language re-promotes its current draft values, which is how a merchant pushes reviewed changes live. The write clears the customiser cached storefront configuration and runs the advisory language sync; it never regenerates your Shopify products, product images, or product cache. An Idempotency-Key header is required. Requires the customisers:write scope. A 400 problem means the Idempotency-Key header is missing or malformed. 401, 403, 404, and 429 problems behave as on the read operation, with customisers:write as the required scope.

Authorisation

Bearer token required. Include it in the Authorization header.

Required scope: customisers:write

Path parameters

customiser_idstringpathrequired

The customiser id, from the list customisers operation.

Example: 1

language_codestringpathrequired

The language tag, from the list customiser languages operation.

Example: fr

Publish a customiser language

curl https://web.signcustomiser.com/api/v3/customisers/1/languages/fr/publish \
  --request POST \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_TOKEN'

{
  "data": {
    "object": "customiser_language",
    "customiser_id": 42,
    "language_code": "fr",
    "source_language_code": "en",
    "display_name": "French",
    "status": "published",
    "is_default": false,
    "is_authoring": false,
    "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:12:31Z"
  },
  "links": {
    "self": "https://web.signcustomiser.com/api/v3/customisers/42/languages/fr/publish",
    "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, but the API key grants the following scopes: customisers:read. Create a key that includes the required scope in the merchant admin under Integrate → API Tokens.",
  "required_scopes": [
    "customisers:write"
  ],
  "granted_scopes": [
    "customisers:read"
  ],
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/resource_not_found",
  "title": "Resource not found",
  "status": 404,
  "code": "resource_not_found",
  "detail": "The requested resource does not exist or does not belong to the authenticated store.",
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}

{
  "type": "https://www.signcustomiser.com/help/api/problems/language_publish_blocked",
  "title": "Language publish blocked",
  "status": 422,
  "code": "language_publish_blocked",
  "detail": "This language cannot be published while required copy is still blank. Write a draft value for every key in missing_keys, then retry. Stale values do not block publishing.",
  "missing_keys": [
    "selection:12:title",
    "label:custom_sizing_title"
  ],
  "missing_key_count": 2,
  "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}