Partners

Page translations

Read and write localized page fields through the Store API.

Get page translation

GET read_pages + read_translations

Fetch one page translation.

Returns stored translated Page fields for one locale, including whether the translation is out of date. 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 uuid

Page id.

Example: 5ff7d4ea-3250-4a4d-9d26-07f64d917d31
locale required string

Enabled non-default store locale.

Example: fr

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 STORE_API_INVALID_PAGE_ID

    Page id is not a valid UUID.
  • 400 TRANSLATION_LOCALE_REQUIRED

    Locale is required.
  • 400 TRANSLATION_LOCALE_NOT_ENABLED

    Locale is not enabled for this store.
  • 400 TRANSLATION_DEFAULT_LOCALE_FORBIDDEN

    Translations cannot target the store's default locale.
  • 400 TRANSLATION_RESOURCE_ID_NOT_IN_STORE

    Page does not exist in this store.

Set page translation

PUT write_pages + write_translations

Set one page translation.

Writes translated Page fields for one locale. Empty values clear the matching field translation.

Path parameters

Name Type Description
id required uuid

Page id.

Example: 5ff7d4ea-3250-4a4d-9d26-07f64d917d31
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": "À propos", "slug": "a-propos"}

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    Request body is not valid JSON.
  • 400 STORE_API_INVALID_PAGE_ID

    Page id is not a valid UUID.
  • 400 TRANSLATION_LOCALE_REQUIRED

    Locale is required.
  • 400 TRANSLATION_LOCALE_NOT_ENABLED

    Locale is not enabled for this store.
  • 400 TRANSLATION_DEFAULT_LOCALE_FORBIDDEN

    Translations cannot target the store's default locale.
  • 400 TRANSLATION_RESOURCE_ID_NOT_IN_STORE

    Page does not exist in this store.
  • 400 TRANSLATION_FIELD_NOT_TRANSLATABLE

    Field is not translatable for Pages.
  • 400 TRANSLATION_FIELDS_REQUIRED

    At least one translated field is required.
  • 400 TRANSLATION_FIELD_VALUE_TOO_LONG

    A translated value exceeds its field limit.
  • 400 TRANSLATION_NO_SOURCE_TEXT

    A non-empty translation requires source text for that field.
  • 409 TRANSLATION_DUPLICATE_NAME_OR_SLUG

    Translated title or slug conflicts with another page.
  • 400 PAGE_SLUG_INVALID_FORMAT

    Translated slug is not valid for Page URLs.

Batch get page translations

GET read_pages + read_translations

Fetch page translations in batch.

Returns translated Page fields for multiple page 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 Page ids.

Example: 5ff7d4ea-3250-4a4d-9d26-07f64d917d31,3a588f80-fd8c-4d46-af1b-00a1c4a7f85a

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 TRANSLATION_LOCALE_REQUIRED

    Locale is required.
  • 400 TRANSLATION_LOCALE_NOT_ENABLED

    Locale is not enabled for this store.
  • 400 TRANSLATION_DEFAULT_LOCALE_FORBIDDEN

    Translations cannot target the store's default locale.
  • 400 TRANSLATION_RESOURCE_ID_NOT_IN_STORE

    Page does not exist in this store.
  • 400 TRANSLATION_TOO_MANY_RESOURCES

    The request exceeds the translation batch resource cap.
  • 400 STORE_API_INVALID_PAGE_ID

    One page id is not a valid UUID.

Batch set page translations

PUT write_pages + write_translations

Set page translations in batch.

Writes translated Page fields for multiple page 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": "5ff7d4ea-3250-4a4d-9d26-07f64d917d31", "fields": {"title": "À propos"}}]

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    Request body is not valid JSON.
  • 400 STORE_API_INVALID_PAGE_ID

    One page id is not a valid UUID.
  • 400 TRANSLATION_TOO_MANY_FIELDS

    The request exceeds the translation batch field cap.
  • 400 TRANSLATION_NO_WRITES_PROVIDED

    No translation writes were provided.
  • 400 TRANSLATION_LOCALE_REQUIRED

    Locale is required.
  • 400 TRANSLATION_LOCALE_NOT_ENABLED

    Locale is not enabled for this store.
  • 400 TRANSLATION_DEFAULT_LOCALE_FORBIDDEN

    Translations cannot target the store's default locale.
  • 400 TRANSLATION_RESOURCE_ID_NOT_IN_STORE

    Page does not exist in this store.
  • 400 TRANSLATION_FIELD_NOT_TRANSLATABLE

    Field is not translatable for Pages.
  • 400 TRANSLATION_FIELDS_REQUIRED

    At least one translated field is required.
  • 400 TRANSLATION_FIELD_VALUE_TOO_LONG

    A translated value exceeds its field limit.
  • 400 TRANSLATION_NO_SOURCE_TEXT

    A non-empty translation requires source text for that field.
  • 409 TRANSLATION_DUPLICATE_NAME_OR_SLUG

    Translated title or slug conflicts with another page.
  • 400 PAGE_SLUG_INVALID_FORMAT

    Translated slug is not valid for Page URLs.

Get a page metafield translation

GET read_pages + read_translations

Fetch one translated page custom-data value.

Resolves the definition by namespace and key, verifies that it is translatable and visible to the token, then returns its value for the requested enabled non-default language. 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 uuid

Page id.

Example: 5ff7d4ea-3250-4a4d-9d26-07f64d917d31
namespace required string

Metafield definition namespace.

Example: details
key required string

Metafield definition key.

Example: subtitle
locale required string

Enabled non-default store locale.

Example: fr

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 STORE_API_INVALID_PAGE_ID

    Page ID must be a UUID.
  • 400 PRODUCT_METAFIELD_DEF_NOT_FOUND

    The namespace and key do not identify an accessible definition.
  • 403 METAFIELD_WRITE_APP_OWN_ONLY

    An app token can write only its own definitions.
  • 404 NOT_FOUND

    The page does not exist in this store.
  • 400 TRANSLATION_LOCALE_REQUIRED

    Locale is required.
  • 400 TRANSLATION_LOCALE_NOT_ENABLED

    Locale is not enabled for this store.
  • 400 TRANSLATION_DEFAULT_LOCALE_FORBIDDEN

    Translations cannot target the store's default locale.
  • 400 TRANSLATION_FIELD_NOT_TRANSLATABLE

    The metafield is not translatable.

Set a page metafield translation

PUT write_pages + write_translations

Set or clear one translated page custom-data value.

The definition must permit writes and translations. Send an empty value to clear this locale’s translation. 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 uuid

Page id.

Example: 5ff7d4ea-3250-4a4d-9d26-07f64d917d31
namespace required string

Metafield definition namespace.

Example: details
key required string

Metafield definition key.

Example: subtitle
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 value. Send an empty string to delete the stored translation for this locale.

Example: Notre histoire

Errors

  • 400 STORE_API_INVALID_PAGE_ID

    Page ID must be a UUID.
  • 400 PRODUCT_METAFIELD_DEF_NOT_FOUND

    The namespace and key do not identify an accessible definition.
  • 403 METAFIELD_WRITE_APP_OWN_ONLY

    An app token can write only its own definitions.
  • 404 NOT_FOUND

    The page does not exist in this store.
  • 400 TRANSLATION_LOCALE_REQUIRED

    Locale is required.
  • 400 TRANSLATION_LOCALE_NOT_ENABLED

    Locale is not enabled for this store.
  • 400 TRANSLATION_DEFAULT_LOCALE_FORBIDDEN

    Translations cannot target the store's default locale.
  • 400 TRANSLATION_FIELD_NOT_TRANSLATABLE

    The metafield is not translatable.
  • 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 pages. Update and clear events identify the locale and changed fields. One write can emit both events when it sets some fields and clears others.

Page translations updated

EVENT pages/translations/update App scope: read_pages Staff permission: pages:write

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

Payload fields

Field Type Description
page.id string Always present
page.title string Selectable in the Payload builder
page.slug string Selectable in the Payload builder
page.content string Selectable in the Payload builder
page.status string Selectable in the Payload builder
page.seo_title string Selectable in the Payload builder
page.seo_description string Selectable in the Payload builder
page.template_handle string Selectable in the Payload builder
page.created_at string Selectable in the Payload builder
page.updated_at 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.content 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

Page translations deleted

EVENT pages/translations/delete App scope: read_pages Staff permission: pages:write

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

Payload fields

Field Type Description
page.id string Always present
page.title string Selectable in the Payload builder
page.slug string Selectable in the Payload builder
page.content string Selectable in the Payload builder
page.status string Selectable in the Payload builder
page.seo_title string Selectable in the Payload builder
page.seo_description string Selectable in the Payload builder
page.template_handle string Selectable in the Payload builder
page.created_at string Selectable in the Payload builder
page.updated_at 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.content 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

Last updated Oct 21, 2026