Partners

List-page SEO translations

Read and write localized list-page seo fields through the Store API.

Translate seo_title, seo_description, social_title, and social_description for an enabled language other than the store's source language. Images and robots settings are shared across languages. Supply strings; an empty string clears a translation. Omitted fields remain unchanged.

Save source text before adding its translation. Source edits mark translations outdated but keep serving them until replaced or removed. A missing translation falls back to the source field. Reads and writes require the corresponding resource and translation scopes shown on each endpoint.

Get list-page SEO translation

GET read_products + read_translations

Get translated SEO for one list page and locale.

The locale must be enabled and cannot be the store's default language.

Path parameters

Name Type Description
pageType required string

Catalog list page.

Example: brand_list
locale required string

Enabled non-default store locale.

Example: fr

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.
  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.
  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.
  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.
  • 400 STORE_API_INVALID_REQUEST_BODY

    The body has an invalid shape. Translation values must be strings.
  • 400 PAGE_SEO_PAGE_TYPE_INVALID

    The requested list page type is not supported.
  • 400 TRANSLATION_LOCALE_REQUIRED

    A locale is required.
  • 400 TRANSLATION_LOCALE_NOT_ENABLED

    The locale is not enabled for this store.
  • 400 TRANSLATION_DEFAULT_LOCALE_FORBIDDEN

    The source language cannot be a translation target.
  • 400 TRANSLATION_FIELD_NOT_TRANSLATABLE

    Only the four SEO and social text fields can be translated.
  • 400 TRANSLATION_FIELDS_REQUIRED

    Provide at least one field.
  • 400 TRANSLATION_NO_SOURCE_TEXT

    Save source text before adding its translation.
  • 404 TRANSLATION_RESOURCE_NOT_FOUND

    Save source SEO before writing translations for this page.
  • 409 TRANSLATION_MUTATION_CONFLICT

    The idempotency key was already used for another translation change.
  • 400 PAGE_SEO_META_TITLE_INVALID_CHARS

    A translated title contains unsupported characters.
  • 400 PAGE_SEO_META_TITLE_TOO_LONG

    A translated title exceeds its limit.
  • 400 PAGE_SEO_META_DESCRIPTION_INVALID_CHARS

    A translated description contains unsupported characters.
  • 400 PAGE_SEO_META_DESCRIPTION_TOO_LONG

    A translated description exceeds its limit.

Set list-page SEO translation

PUT write_products + write_translations

Set or clear translated SEO fields for one list page.

Empty field values clear only that locale's translation. Writes are atomic.

Path parameters

Name Type Description
pageType required string

Catalog list page.

Example: brand_list
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 translations.

Example: {"seo_title":"Marques","seo_description":"Découvrez toutes nos marques."}

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.
  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.
  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.
  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.
  • 400 STORE_API_INVALID_REQUEST_BODY

    The body has an invalid shape. Translation values must be strings.
  • 400 PAGE_SEO_PAGE_TYPE_INVALID

    The requested list page type is not supported.
  • 400 TRANSLATION_LOCALE_REQUIRED

    A locale is required.
  • 400 TRANSLATION_LOCALE_NOT_ENABLED

    The locale is not enabled for this store.
  • 400 TRANSLATION_DEFAULT_LOCALE_FORBIDDEN

    The source language cannot be a translation target.
  • 400 TRANSLATION_FIELD_NOT_TRANSLATABLE

    Only the four SEO and social text fields can be translated.
  • 400 TRANSLATION_FIELDS_REQUIRED

    Provide at least one field.
  • 400 TRANSLATION_NO_SOURCE_TEXT

    Save source text before adding its translation.
  • 404 TRANSLATION_RESOURCE_NOT_FOUND

    Save source SEO before writing translations for this page.
  • 409 TRANSLATION_MUTATION_CONFLICT

    The idempotency key was already used for another translation change.
  • 400 PAGE_SEO_META_TITLE_INVALID_CHARS

    A translated title contains unsupported characters.
  • 400 PAGE_SEO_META_TITLE_TOO_LONG

    A translated title exceeds its limit.
  • 400 PAGE_SEO_META_DESCRIPTION_INVALID_CHARS

    A translated description contains unsupported characters.
  • 400 PAGE_SEO_META_DESCRIPTION_TOO_LONG

    A translated description exceeds its limit.

Batch get list-page SEO translations

GET read_products + read_translations

Get translations for several catalog list pages.

Omit page_types to return brand_list, vendor_list, category_list, and collection_list. Otherwise pass a comma-separated subset; duplicates and unknown values are rejected.

Path parameters

Name Type Description
locale required string

Enabled non-default store locale.

Example: fr

Query parameters

Name Type Description
page_types string

Comma-separated list-page types.

Example: brand_list,collection_list

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.
  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.
  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.
  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.
  • 400 STORE_API_INVALID_REQUEST_BODY

    The body has an invalid shape. Translation values must be strings.
  • 400 PAGE_SEO_PAGE_TYPE_INVALID

    The requested list page type is not supported.
  • 400 TRANSLATION_LOCALE_REQUIRED

    A locale is required.
  • 400 TRANSLATION_LOCALE_NOT_ENABLED

    The locale is not enabled for this store.
  • 400 TRANSLATION_DEFAULT_LOCALE_FORBIDDEN

    The source language cannot be a translation target.
  • 400 TRANSLATION_FIELD_NOT_TRANSLATABLE

    Only the four SEO and social text fields can be translated.
  • 400 TRANSLATION_FIELDS_REQUIRED

    Provide at least one field.
  • 400 TRANSLATION_NO_SOURCE_TEXT

    Save source text before adding its translation.
  • 404 TRANSLATION_RESOURCE_NOT_FOUND

    Save source SEO before writing translations for this page.
  • 409 TRANSLATION_MUTATION_CONFLICT

    The idempotency key was already used for another translation change.
  • 400 PAGE_SEO_META_TITLE_INVALID_CHARS

    A translated title contains unsupported characters.
  • 400 PAGE_SEO_META_TITLE_TOO_LONG

    A translated title exceeds its limit.
  • 400 PAGE_SEO_META_DESCRIPTION_INVALID_CHARS

    A translated description contains unsupported characters.
  • 400 PAGE_SEO_META_DESCRIPTION_TOO_LONG

    A translated description exceeds its limit.

Batch set list-page SEO translations

PUT write_products + write_translations

Set translations for several catalog list pages atomically.

The request accepts at most one row for each supported page type. If any row is invalid, none are written.

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 shaped as {page_type, fields}.

Example: [{"page_type":"brand_list","fields":{"seo_title":"Marques"}}]

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.
  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.
  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.
  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.
  • 400 STORE_API_INVALID_REQUEST_BODY

    The body has an invalid shape. Translation values must be strings.
  • 400 PAGE_SEO_PAGE_TYPE_INVALID

    The requested list page type is not supported.
  • 400 TRANSLATION_LOCALE_REQUIRED

    A locale is required.
  • 400 TRANSLATION_LOCALE_NOT_ENABLED

    The locale is not enabled for this store.
  • 400 TRANSLATION_DEFAULT_LOCALE_FORBIDDEN

    The source language cannot be a translation target.
  • 400 TRANSLATION_FIELD_NOT_TRANSLATABLE

    Only the four SEO and social text fields can be translated.
  • 400 TRANSLATION_FIELDS_REQUIRED

    Provide at least one field.
  • 400 TRANSLATION_NO_SOURCE_TEXT

    Save source text before adding its translation.
  • 404 TRANSLATION_RESOURCE_NOT_FOUND

    Save source SEO before writing translations for this page.
  • 409 TRANSLATION_MUTATION_CONFLICT

    The idempotency key was already used for another translation change.
  • 400 PAGE_SEO_META_TITLE_INVALID_CHARS

    A translated title contains unsupported characters.
  • 400 PAGE_SEO_META_TITLE_TOO_LONG

    A translated title exceeds its limit.
  • 400 PAGE_SEO_META_DESCRIPTION_INVALID_CHARS

    A translated description contains unsupported characters.
  • 400 PAGE_SEO_META_DESCRIPTION_TOO_LONG

    A translated description exceeds its limit.

Webhook events#

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

List-page SEO translations updated

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

Fired when translated SEO fields are added or updated for the public brand, vendor, or category list page in a locale. The payload identifies the list with page_type and carries only the translated fields that changed.

Payload fields

Field Type Description
list_page_seo.id integer Always present

The stable storage id for this list-page SEO record.
list_page_seo.page_type string Always present

The public catalog list being described: brand_list, vendor_list, category_list, or collection_list.
list_page_seo.seo_title string Selectable in the Payload builder

The list page's SEO title in the store's default language.
list_page_seo.seo_description string Selectable in the Payload builder

The list page's SEO description in the store's default language.
list_page_seo.social_title string Selectable in the Payload builder

The default-language social sharing title override.
list_page_seo.social_description string Selectable in the Payload builder

The default-language social sharing description override.
list_page_seo.social_image_id string Selectable in the Payload builder

The assigned site-asset image id, or null when no override is assigned.
list_page_seo.robots_index boolean Selectable in the Payload builder

Whether search engines may index this list page.
list_page_seo.robots_follow boolean Selectable in the Payload builder

Whether search engines may follow links from this list page.
list_page_seo.updated_at string Selectable in the Payload builder

When the source list-page SEO settings last changed, in the store's timezone.
locale string Selectable in the Payload builder

The locale whose list-page SEO translation changed.
translation.seo_title string Selectable in the Payload builder

The translated SEO title; an empty string on the delete event means it was removed.
translation.seo_description string Selectable in the Payload builder

The translated SEO description; an empty string on the delete event means it was removed.
translation.social_title string Selectable in the Payload builder

The translated social title; an empty string on the delete event means it was removed.
translation.social_description string Selectable in the Payload builder

The translated social description; an empty string on the delete event means it was removed.
updated_at string Selectable in the Payload builder

When this locale's list-page SEO translation changed, in the store's timezone.

List-page SEO translations deleted

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

Fired when translated SEO fields are cleared for the public brand, vendor, or category list page in a locale. The payload identifies the list with page_type and carries the cleared fields as empty strings.

Payload fields

Field Type Description
list_page_seo.id integer Always present

The stable storage id for this list-page SEO record.
list_page_seo.page_type string Always present

The public catalog list being described: brand_list, vendor_list, category_list, or collection_list.
list_page_seo.seo_title string Selectable in the Payload builder

The list page's SEO title in the store's default language.
list_page_seo.seo_description string Selectable in the Payload builder

The list page's SEO description in the store's default language.
list_page_seo.social_title string Selectable in the Payload builder

The default-language social sharing title override.
list_page_seo.social_description string Selectable in the Payload builder

The default-language social sharing description override.
list_page_seo.social_image_id string Selectable in the Payload builder

The assigned site-asset image id, or null when no override is assigned.
list_page_seo.robots_index boolean Selectable in the Payload builder

Whether search engines may index this list page.
list_page_seo.robots_follow boolean Selectable in the Payload builder

Whether search engines may follow links from this list page.
list_page_seo.updated_at string Selectable in the Payload builder

When the source list-page SEO settings last changed, in the store's timezone.
locale string Selectable in the Payload builder

The locale whose list-page SEO translation changed.
translation.seo_title string Selectable in the Payload builder

The translated SEO title; an empty string on the delete event means it was removed.
translation.seo_description string Selectable in the Payload builder

The translated SEO description; an empty string on the delete event means it was removed.
translation.social_title string Selectable in the Payload builder

The translated social title; an empty string on the delete event means it was removed.
translation.social_description string Selectable in the Payload builder

The translated social description; an empty string on the delete event means it was removed.
updated_at string Selectable in the Payload builder

When this locale's list-page SEO translation changed, in the store's timezone.

Last updated Oct 12, 2026