Partners

Product translations

Read and write localized product fields through the Store API.

Get product translation

GET read_products + read_translations

Fetch one product translation.

Returns stored translated Product fields for one locale, including whether the translation is out of date. Allowed fields come from contract.translation.fields. Fields without a translation in this locale are omitted from the response. An omitted field is not empty: shoppers see the store's base-language value, which the resource's own GET endpoint returns.

Path parameters

Name Type Description
id required integer

Product id.

Example: 7
locale required string

Enabled non-default store locale.

Example: fr

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 TRANSLATION_INVALID_LOCALE

    The locale is not enabled for the store.
  • 400 TRANSLATION_FIELD_NOT_ALLOWED

    A field key is not in contract.translation.fields.
  • 401 UNAUTHORIZED

    Missing or invalid token.
  • 403 STORE_API_SCOPE_REQUIRED

    The token lacks a required product or translation scope.
  • 404 NOT_FOUND

    Product, variant, or locale not found.

Set product translation

PUT write_products + write_translations

Set one product translation.

Writes translated Product fields for one locale. Empty values clear the matching field translation. Validation (rune-count limits per field) is the same the admin translation editor runs.

Path parameters

Name Type Description
id required integer

Product id.

Example: 7
locale required string

Enabled non-default store locale.

Example: fr

Headers

Name Type Description
Authorization required string

Bearer Store API token.
Idempotency-Key string

Optional key for this translation write. Reuse it only with the same payload when repeating the request.

Body parameters

Name Type Description
translations required object

Field-keyed translation values. Allowed fields come from contract.translation.fields.

Example: {"title": "T-shirt en coton bio", "seo_title": "T-shirt bio"}

Errors

  • 400 TRANSLATION_INVALID_LOCALE

    The locale is not enabled for the store.
  • 400 TRANSLATION_FIELD_NOT_ALLOWED

    A field key is not in contract.translation.fields.
  • 401 UNAUTHORIZED

    Missing or invalid token.
  • 403 STORE_API_SCOPE_REQUIRED

    The token lacks a required product or translation scope.
  • 404 NOT_FOUND

    Product, variant, or locale not found.

Batch get product translations

GET read_products + read_translations

Fetch product translations in batch.

Returns translated Product fields for multiple product ids in one locale. Fields without a translation in this locale are omitted from the response. An omitted field is not empty: shoppers see the store's base-language value, which the resource's own GET endpoint returns.

Path parameters

Name Type Description
locale required string

Enabled non-default store locale.

Example: fr

Query parameters

Name Type Description
ids required string

Comma-separated product ids.

Example: 1,2,3

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 TRANSLATION_INVALID_LOCALE

    The locale is not enabled for the store.
  • 400 TRANSLATION_FIELD_NOT_ALLOWED

    A field key is not in contract.translation.fields.
  • 401 UNAUTHORIZED

    Missing or invalid token.
  • 403 STORE_API_SCOPE_REQUIRED

    The token lacks a required product or translation scope.
  • 404 NOT_FOUND

    Product, variant, or locale not found.

Batch set product translations

PUT write_products + write_translations

Set product translations in batch.

Writes translated Product fields for multiple product ids in one locale. Either every row is written or, if any row is invalid, none are.

Path parameters

Name Type Description
locale required string

Enabled non-default store locale.

Example: fr

Headers

Name Type Description
Authorization required string

Bearer Store API token.
Idempotency-Key string

Optional key for this translation write. Reuse it only with the same payload when repeating the request.

Body parameters

Name Type Description
translations required array<object>

Rows with id and fields. Allowed field keys come from contract.translation.fields.

Example: [{"id": 7, "fields": {"title": "T-shirt en coton bio"}}]

Errors

  • 400 TRANSLATION_INVALID_LOCALE

    The locale is not enabled for the store.
  • 400 TRANSLATION_FIELD_NOT_ALLOWED

    A field key is not in contract.translation.fields.
  • 401 UNAUTHORIZED

    Missing or invalid token.
  • 403 STORE_API_SCOPE_REQUIRED

    The token lacks a required product or translation scope.
  • 404 NOT_FOUND

    Product, variant, or locale not found.

Get variant translation

GET read_products + read_translations

Fetch one variant translation.

Returns the stored translated variant title for one locale. Fields without a translation in this locale are omitted from the response. An omitted field is not empty: shoppers see the store's base-language value, which the resource's own GET endpoint returns.

Path parameters

Name Type Description
id required integer

Product ID.
variantId required integer

Variant ID.
locale required string

BCP-47 locale code, e.g. fr or pt-BR.

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 TRANSLATION_INVALID_LOCALE

    The locale is not enabled for the store.
  • 400 TRANSLATION_FIELD_NOT_ALLOWED

    A field key is not in contract.translation.fields.
  • 401 UNAUTHORIZED

    Missing or invalid token.
  • 403 STORE_API_SCOPE_REQUIRED

    The token lacks a required product or translation scope.
  • 404 NOT_FOUND

    Product, variant, or locale not found.

Set variant translation

PUT write_products + write_translations

Set one variant translation.

Writes the translated variant title for one locale. An empty value clears it.

Path parameters

Name Type Description
id required integer

Product ID.
variantId required integer

Variant ID.
locale required string

BCP-47 locale code, e.g. fr or pt-BR.

Headers

Name Type Description
Authorization required string

Bearer Store API token.
Idempotency-Key string

Optional key for this translation write. Reuse it only with the same payload when repeating the request.

Body parameters

Name Type Description
translations required object

Field-keyed translation values; variants translate title.

Example: {"title": "Rouge / M"}

Errors

  • 400 TRANSLATION_INVALID_LOCALE

    The locale is not enabled for the store.
  • 400 TRANSLATION_FIELD_NOT_ALLOWED

    A field key is not in contract.translation.fields.
  • 401 UNAUTHORIZED

    Missing or invalid token.
  • 403 STORE_API_SCOPE_REQUIRED

    The token lacks a required product or translation scope.
  • 404 NOT_FOUND

    Product, variant, or locale not found.

Get product metafield translation

GET read_products + read_translations

Fetch one translated product metafield value.

Resolves the definition by namespace and key through the calling app's access boundary, then returns its stored value translation for one locale. The definition must be translatable and visible to the calling app. Fields without a translation in this locale are omitted from the response. An omitted field is not empty: shoppers see the store's base-language value, which the resource's own GET endpoint returns.

Path parameters

Name Type Description
id required integer

Product ID.

Example: 7
namespace required string

Metafield definition namespace.

Example: details
key required string

Metafield definition key.

Example: material
locale required string

Enabled non-default store locale.

Example: fr

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 TRANSLATION_INVALID_LOCALE

    The locale is not enabled for the store.
  • 400 TRANSLATION_FIELD_NOT_ALLOWED

    A field key is not in contract.translation.fields.
  • 401 UNAUTHORIZED

    Missing or invalid token.
  • 403 STORE_API_SCOPE_REQUIRED

    The token lacks a required product or translation scope.
  • 404 NOT_FOUND

    Product, variant, or locale not found.

Set product metafield translation

PUT write_products + write_translations

Set one translated product metafield value.

Writes or clears the value translation after rechecking definition ownership, app access, translatability, value type, and the Product owner in this store. Send an explicit string in value; omit neither the field nor its value, and do not send null. An empty string clears the translation. For list.string, send a JSON-encoded string array with one translated item for each source item, in the same order.

Path parameters

Name Type Description
id required integer

Product ID.

Example: 7
namespace required string

Metafield definition namespace.

Example: details
key required string

Metafield definition key.

Example: material
locale required string

Enabled non-default store locale.

Example: fr

Headers

Name Type Description
Authorization required string

Bearer Store API token.
Idempotency-Key string

Optional key for this translation write. Reuse it only with the same payload when repeating the request.

Body parameters

Name Type Description
value required string

Translated metafield value. An empty value clears the stored translation.

Example: Organic cotton

Errors

  • 400 TRANSLATION_INVALID_LOCALE

    The locale is not enabled for the store.
  • 400 TRANSLATION_FIELD_NOT_ALLOWED

    A field key is not in contract.translation.fields.
  • 401 UNAUTHORIZED

    Missing or invalid token.
  • 403 STORE_API_SCOPE_REQUIRED

    The token lacks a required product or translation scope.
  • 404 NOT_FOUND

    Product, variant, or locale not found.
  • 400 TRANSLATION_LIST_LENGTH_MISMATCH

    The translated list must have the same number of items as the source list.

Get variant metafield translation

GET read_products + read_translations

Fetch one translated variant metafield value.

Validates that the variant belongs to the Product in the path, resolves the definition through the calling app's access boundary, and returns its stored value translation for one locale. Fields without a translation in this locale are omitted from the response. An omitted field is not empty: shoppers see the store's base-language value, which the resource's own GET endpoint returns.

Path parameters

Name Type Description
id required integer

Product ID.

Example: 7
variantId required integer

Variant ID.

Example: 12
namespace required string

Metafield definition namespace.

Example: details
key required string

Metafield definition key.

Example: material
locale required string

Enabled non-default store locale.

Example: fr

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 TRANSLATION_INVALID_LOCALE

    The locale is not enabled for the store.
  • 400 TRANSLATION_FIELD_NOT_ALLOWED

    A field key is not in contract.translation.fields.
  • 401 UNAUTHORIZED

    Missing or invalid token.
  • 403 STORE_API_SCOPE_REQUIRED

    The token lacks a required product or translation scope.
  • 404 NOT_FOUND

    Product, variant, or locale not found.

Set variant metafield translation

PUT write_products + write_translations

Set one translated variant metafield value.

Writes or clears the value translation after validating the Product/Variant pair, definition ownership, app access, translatability, and value type. Send an explicit string in value; omit neither the field nor its value, and do not send null. An empty string clears the translation. For list.string, send a JSON-encoded string array with one translated item for each source item, in the same order.

Path parameters

Name Type Description
id required integer

Product ID.

Example: 7
variantId required integer

Variant ID.

Example: 12
namespace required string

Metafield definition namespace.

Example: details
key required string

Metafield definition key.

Example: material
locale required string

Enabled non-default store locale.

Example: fr

Headers

Name Type Description
Authorization required string

Bearer Store API token.
Idempotency-Key string

Optional key for this translation write. Reuse it only with the same payload when repeating the request.

Body parameters

Name Type Description
value required string

Translated metafield value. An empty value clears the stored translation.

Example: Large

Errors

  • 400 TRANSLATION_INVALID_LOCALE

    The locale is not enabled for the store.
  • 400 TRANSLATION_FIELD_NOT_ALLOWED

    A field key is not in contract.translation.fields.
  • 401 UNAUTHORIZED

    Missing or invalid token.
  • 403 STORE_API_SCOPE_REQUIRED

    The token lacks a required product or translation scope.
  • 404 NOT_FOUND

    Product, variant, or locale not found.
  • 400 TRANSLATION_LIST_LENGTH_MISMATCH

    The translated list must have the same number of items as the source list.

Webhook events#

Subscribe to these events when your integration mirrors localized products. Update and clear events identify the locale and changed fields. One write can emit both events when it sets some fields and clears others.

Product translations updated

EVENT products/translations/update App scope: read_products Staff permission: products:write

Fired when a product's translations are added or updated for a locale. Payload carries only the fields that changed.

Payload fields

Field Type Description
product.id integer Always present
product.title string Selectable in the Payload builder
product.slug string Selectable in the Payload builder
locale string Selectable in the Payload builder
translation.title string Selectable in the Payload builder
translation.slug string Selectable in the Payload builder
translation.description string Selectable in the Payload builder
translation.short_description string Selectable in the Payload builder
translation.seo_title string Selectable in the Payload builder
translation.seo_description string Selectable in the Payload builder
updated_at string Selectable in the Payload builder

Product translations deleted

EVENT products/translations/delete App scope: read_products Staff permission: products:write

Fired when a product's translations are cleared for one or more fields in a locale.

Payload fields

Field Type Description
product.id integer Always present
product.title string Selectable in the Payload builder
product.slug string Selectable in the Payload builder
locale string Selectable in the Payload builder
translation.title string Selectable in the Payload builder
translation.slug string Selectable in the Payload builder
translation.description string Selectable in the Payload builder
translation.short_description string Selectable in the Payload builder
translation.seo_title string Selectable in the Payload builder
translation.seo_description string Selectable in the Payload builder
updated_at string Selectable in the Payload builder

Variant translations updated

EVENT variants/translations/update App scope: read_products Staff permission: products:write

Fired when a variant's translations are added or updated for a locale. Payload carries only the fields that changed.

Payload fields

Field Type Description
variant.id integer Always present
variant.product_id integer Always present
variant.title string Selectable in the Payload builder
variant.sku string Selectable in the Payload builder
locale string Selectable in the Payload builder
translation.title string Selectable in the Payload builder
updated_at string Selectable in the Payload builder

Variant translations deleted

EVENT variants/translations/delete App scope: read_products Staff permission: products:write

Fired when a variant's translations are cleared for one or more fields in a locale.

Payload fields

Field Type Description
variant.id integer Always present
variant.product_id integer Always present
variant.title string Selectable in the Payload builder
variant.sku string Selectable in the Payload builder
locale string Selectable in the Payload builder
translation.title string Selectable in the Payload builder
updated_at string Selectable in the Payload builder

Last updated Oct 21, 2026