Customiser languages
Update language translations
Write draft values for the language. The body names the keys to change and
the value to give each of them; a key the body does not name keeps the value
it has, and draft_value: null clears one back to blank.
Overview
Nothing a shopper
sees changes: publishing the language is what promotes draft values to
published copy.
Only draft_value is writable. Every other property the read publishes is
server-owned — the catalogue supplies the key, the group, whether it is
required, and the source copy; a publish supplies the published values; the
sync supplies the staleness — so naming one is a 422 pointing at it rather
than a value silently dropped. A key may appear once; a second entry for the
same key is refused rather than resolved.
A 422 problem with code invalid_translation_key means the body names keys
this language cannot accept, with a pointer per offending entry and a
reason of unknown (the catalogue has never carried it) or retired (the
copy it translated is gone). A 422 validation_failed with a pointer at
/translations/{index}/draft_value means a value dropped a placeholder its
source copy requires — a value that loses {price} would render a broken
sentence in the storefront.
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. Send an Idempotency-Key header (1-255 visible
ASCII characters, e.g. a UUID) to make the write safe to retry: repeating the
same key with the same body replays the original response (marked
Idempotency-Replay: true) without executing again; the same key with a
different body is a 409 problem with code idempotency_key_conflict. The
header is optional here, as on every update operation. Requires the
customisers:write scope.
A 400 problem means the body is not valid JSON or the Idempotency-Key
header is malformed; a 422 problem with code unknown_field means the body
names properties this operation does not define. 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 theAuthorization header.
Required scope: customisers:write
Path parameters
The customiser id, from the list customisers operation.
Example: 1
The language tag, from the list customiser languages operation.
Example: fr
Request body
Request body example
{
"translations": [
{
"key": "selection:12:label",
"draft_value": "Couleur"
}
]
}curl https://web.signcustomiser.com/api/v3/customisers/1/languages/fr/translations \
--request PATCH \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"translations": [
{
"key": "selection:12:label",
"draft_value": "Couleur"
}
]
}'{
"data": {
"object": "customiser_language_translations_write_receipt",
"customiser_id": 42,
"language_code": "fr",
"written_key_count": 2,
"cleared_key_count": 1,
"missing_required_key_count": 82,
"publishable": false,
"keys": [
"selection:12:label",
"selection:13:label",
"settings:custom_sizing_title"
]
},
"links": {
"self": "https://web.signcustomiser.com/api/v3/customisers/42/languages/fr/translations",
"documentation": "https://www.signcustomiser.com/help/api/"
},
"meta": {
"api_version": "v3",
"request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}
}{
"type": "https://www.signcustomiser.com/help/api/problems/malformed_json",
"title": "Malformed JSON",
"status": 400,
"code": "malformed_json",
"detail": "The request body is not valid JSON: Syntax error.",
"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/invalid_translation_key",
"title": "Invalid translation key",
"status": 422,
"code": "invalid_translation_key",
"detail": "The write names translation keys this language cannot accept. Read the translations to see the keys it carries, then retry with only those.",
"errors": [
{
"pointer": "/translations/1/key",
"code": "invalid_translation_key",
"detail": "The translation key \"selection:99:label\" is retired: the copy it translated no longer exists."
}
],
"invalid_keys": [
{
"key": "selection:99:label",
"reason": "retired"
}
],
"request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t"
}