Partners

Vendor translations

Translate vendor names, slugs, descriptions, and SEO fields through the Store API.

Translate a vendor's name, slug, description, seo_title, and seo_description for an enabled non-default locale. GET returns stored translations and omits untranslated fields; hosted vendor pages show the base-language value for each omitted field. PUT changes only supplied fields, and an empty string clears a translation. The source field must contain text before it can be translated. is_outdated marks a translation whose source changed, but the stored translation remains in use until updated or cleared. Translated names and slugs must be unique within the locale; a translated slug changes the localized page path.

Get vendor translation

GET read_products + read_translations

Fetch one vendor translation.

Returns stored translations for one vendor and locale. Each returned field includes is_outdated. 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

Vendor 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 STORE_API_INVALID_VENDOR_ID

    Vendor ID is invalid.
  • 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

    Vendor does not exist in this store.

Set vendor translation

PUT write_products + write_translations

Set one vendor translation.

Only supplied fields change. Send an empty string to clear a field's translation. Fetch the translation to read saved values and metadata.

Path parameters

Name Type Description
id required integer

Vendor 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

Translated name, slug, description, seo_title, or seo_description values.

Example: {"name": "Fournitures Acme", "description": "Fournitures Acme distribue du matériel de plein air en gros."}

Errors

  • 400 STORE_API_INVALID_VENDOR_ID

    Vendor ID is invalid.
  • 400 STORE_API_INVALID_REQUEST_BODY

    Request body must be a JSON object containing only documented fields; error.details.field identifies an unknown field.
  • 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_FIELDS_REQUIRED

    Each vendor must include at least one translated field.
  • 400 TRANSLATION_FIELD_NOT_TRANSLATABLE

    Use only name, slug, description, seo_title, or seo_description.
  • 400 TRANSLATION_TOO_MANY_FIELDS

    The request exceeds the translation field limit.
  • 400 TRANSLATION_STAGING_INVALID_CONTROL_CHARS

    A translated value contains unsupported control characters.
  • 400 TRANSLATION_FIELD_VALUE_TOO_LONG

    A translated value exceeds the overall translation value limit.
  • 400 TRANSLATION_FIELD_EXCEEDS_BYTE_LIMIT

    A translated value exceeds the field's length limit.
  • 400 TRANSLATION_NO_SOURCE_TEXT

    The source field is empty; add source text before translating it.
  • 400 TRANSLATION_RESOURCE_ID_NOT_IN_STORE

    Vendor does not exist in this store.
  • 404 TRANSLATION_RESOURCE_NOT_FOUND

    Vendor no longer exists in this store.
  • 409 VENDOR_DUPLICATE

    Translated name or slug already belongs to another vendor.
  • 409 TRANSLATION_DUPLICATE_NAME_OR_SLUG

    Translated name or slug conflicted with another vendor during the write.
  • 503 CATALOG_NAMESPACE_BUSY

    Another write is claiming the same names or slugs (for example a large CSV import or a translation save). Nothing was changed; retry after a short delay.
  • 400 VENDOR_NAME_INVALID_CHARS

    Translated name contains unsupported control characters.
  • 400 VENDOR_NAME_TOO_LONG

    Translated name exceeds the maximum length.
  • 400 VENDOR_DESCRIPTION_INVALID_CHARS

    Translated description contains unsupported control characters.
  • 400 VENDOR_DESCRIPTION_TOO_LONG

    Translated description exceeds the maximum length.
  • 400 VENDOR_SEO_TITLE_INVALID_CHARS

    Translated SEO title contains unsupported control characters.
  • 400 VENDOR_SEO_TITLE_TOO_LONG

    Translated SEO title exceeds the maximum length.
  • 400 VENDOR_SEO_DESCRIPTION_INVALID_CHARS

    Translated SEO description contains unsupported control characters.
  • 400 VENDOR_SEO_DESCRIPTION_TOO_LONG

    Translated SEO description exceeds the maximum length.
  • 400 VENDOR_SLUG_INVALID_FORMAT

    Translated slug has an invalid format.
  • 400 VENDOR_SLUG_TOO_LONG

    Translated slug exceeds the maximum length.

Batch get vendor translations

GET read_products + read_translations

Fetch vendor translations in batch.

Returns one resources entry per requested vendor ID. A vendor without stored translations has an empty object. 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 vendor IDs.

Example: 7,11

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 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_INVALID_RESOURCE_ID

    A vendor ID is invalid.
  • 400 TRANSLATION_RESOURCE_ID_NOT_IN_STORE

    A vendor does not exist in this store.
  • 400 TRANSLATION_TOO_MANY_RESOURCES

    The request exceeds the translation batch resource limit.

Batch set vendor translations

PUT write_products + write_translations

Set vendor translations in batch.

Sets translations for multiple vendors in one locale. The whole request succeeds or fails together; if any row is invalid, none are saved.

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 fields are name, slug, description, seo_title, and seo_description.

Example: [{"id": 7, "fields": {"name": "Fournitures Acme"}}]

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    Request body must be a JSON object containing only documented fields; error.details.field identifies an unknown field.
  • 400 TRANSLATION_NO_WRITES_PROVIDED

    At least one vendor translation row is required.
  • 400 TRANSLATION_INVALID_RESOURCE_ID

    A vendor ID is invalid.
  • 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_FIELDS_REQUIRED

    Each vendor must include at least one translated field.
  • 400 TRANSLATION_FIELD_NOT_TRANSLATABLE

    Use only name, slug, description, seo_title, or seo_description.
  • 400 TRANSLATION_TOO_MANY_FIELDS

    The request exceeds the translation field limit.
  • 400 TRANSLATION_STAGING_INVALID_CONTROL_CHARS

    A translated value contains unsupported control characters.
  • 400 TRANSLATION_FIELD_VALUE_TOO_LONG

    A translated value exceeds the overall translation value limit.
  • 400 TRANSLATION_FIELD_EXCEEDS_BYTE_LIMIT

    A translated value exceeds the field's length limit.
  • 400 TRANSLATION_NO_SOURCE_TEXT

    The source field is empty; add source text before translating it.
  • 400 TRANSLATION_RESOURCE_ID_NOT_IN_STORE

    Vendor does not exist in this store.
  • 404 TRANSLATION_RESOURCE_NOT_FOUND

    Vendor no longer exists in this store.
  • 409 VENDOR_DUPLICATE

    Translated name or slug already belongs to another vendor.
  • 409 TRANSLATION_DUPLICATE_NAME_OR_SLUG

    Translated name or slug conflicted with another vendor during the write.
  • 503 CATALOG_NAMESPACE_BUSY

    Another write is claiming the same names or slugs (for example a large CSV import or a translation save). Nothing was changed; retry after a short delay.
  • 400 VENDOR_NAME_INVALID_CHARS

    Translated name contains unsupported control characters.
  • 400 VENDOR_NAME_TOO_LONG

    Translated name exceeds the maximum length.
  • 400 VENDOR_DESCRIPTION_INVALID_CHARS

    Translated description contains unsupported control characters.
  • 400 VENDOR_DESCRIPTION_TOO_LONG

    Translated description exceeds the maximum length.
  • 400 VENDOR_SEO_TITLE_INVALID_CHARS

    Translated SEO title contains unsupported control characters.
  • 400 VENDOR_SEO_TITLE_TOO_LONG

    Translated SEO title exceeds the maximum length.
  • 400 VENDOR_SEO_DESCRIPTION_INVALID_CHARS

    Translated SEO description contains unsupported control characters.
  • 400 VENDOR_SEO_DESCRIPTION_TOO_LONG

    Translated SEO description exceeds the maximum length.
  • 400 VENDOR_SLUG_INVALID_FORMAT

    Translated slug has an invalid format.
  • 400 VENDOR_SLUG_TOO_LONG

    Translated slug exceeds the maximum length.

Get a vendor metafield translation

GET read_products + read_translations

Get one vendor metafield translation.

Returns the stored translation for a translatable metafield the token can read, in an 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 integer

Vendor id.

Example: 7
namespace required string

Metafield definition namespace.

Example: details
key required string

Metafield definition key.

Example: origin
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_VENDOR_ID

    Vendor id is not a positive integer.
  • 400 TRANSLATION_FIELD_NOT_TRANSLATABLE

    The definition is not translatable or its value type cannot be translated.
  • 400 TRANSLATION_LOCALE_REQUIRED

    Locale is missing.
  • 400 TRANSLATION_LOCALE_NOT_ENABLED

    Locale is not enabled for this store.
  • 400 TRANSLATION_DEFAULT_LOCALE_FORBIDDEN

    The default language stores source values and cannot be used as a translation locale.
  • 404 METAFIELD_DEFINITION_NOT_FOUND

    The namespace and key do not identify an accessible Vendor definition.
  • 404 VENDOR_NOT_FOUND

    Vendor does not exist in this store.

Set a vendor metafield translation

PUT write_products + write_translations

Set or clear one vendor metafield translation.

Sets this metafield's translation in an enabled non-default locale without changing the source value. value is required. Send an empty string to clear it. For list.string, send a JSON-encoded string array with one item per source item, in the same order.

Path parameters

Name Type Description
id required integer

Vendor id.

Example: 7
namespace required string

Metafield definition namespace.

Example: details
key required string

Metafield definition key.

Example: origin
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: Séoul

Errors

  • 400 STORE_API_INVALID_VENDOR_ID

    Vendor id is not a positive integer.
  • 400 TRANSLATION_FIELD_NOT_TRANSLATABLE

    The definition is not translatable or its value type cannot be translated.
  • 400 TRANSLATION_LOCALE_REQUIRED

    Locale is missing.
  • 400 TRANSLATION_LOCALE_NOT_ENABLED

    Locale is not enabled for this store.
  • 400 TRANSLATION_DEFAULT_LOCALE_FORBIDDEN

    The default language stores source values and cannot be used as a translation locale.
  • 404 METAFIELD_DEFINITION_NOT_FOUND

    The namespace and key do not identify an accessible Vendor definition.
  • 404 VENDOR_NOT_FOUND

    Vendor does not exist in this store.
  • 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 vendors. Update and clear events identify the locale and changed fields. One write can emit both events when it sets some fields and clears others.

Vendor translations updated

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

Fired when vendor translations are added or updated for a locale. The payload contains only the fields that changed. A write that updates some translated fields and clears others fires both translation events; translation writes do not fire vendors/update.

Payload fields

Field Type Description
vendor.id integer Always present

The stable vendor id.
vendor.name string Selectable in the Payload builder

The vendor name at the time the event was created.
vendor.slug string Selectable in the Payload builder

The vendor slug at the time the event was created.
vendor.description string Selectable in the Payload builder

The vendor description in the store's default language.
vendor.seo_title string Selectable in the Payload builder

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

The vendor page's SEO description in the store's default language.
vendor.image_id string Selectable in the Payload builder

The assigned Media-library image UUID, or null when no image is assigned.
vendor.image_url string Selectable in the Payload builder

The storefront URL for the assigned image, or an empty string.
vendor.image_cdn_url string Selectable in the Payload builder

The delivery URL for the assigned image, or an empty string.
vendor.product_count integer Selectable in the Payload builder

The number of products assigned to the vendor when the event was created.
vendor.template_handle string Selectable in the Payload builder

The storefront Vendor template assigned to the vendor.
vendor.created_at string Selectable in the Payload builder

When the vendor was created.
vendor.updated_at string Selectable in the Payload builder

When the vendor last changed.
vendor.translations_updated_at string Selectable in the Payload builder

When any vendor translation last changed, or null when none exist.
locale string Selectable in the Payload builder

The locale whose vendor or metafield translation changed.
translation.name string Selectable in the Payload builder

The translated vendor name; an empty string on the delete event means it was removed.
translation.slug string Selectable in the Payload builder

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

The translated vendor description; an empty string on the delete event means it was removed.
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.
updated_at string Selectable in the Payload builder

When this locale's translation last changed.

Vendor translations deleted

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

Fired when vendor translations are cleared for one or more fields in a locale, including during vendor deletion. A write that updates some translated fields and clears others fires both translation events; translation writes do not fire vendors/update.

Payload fields

Field Type Description
vendor.id integer Always present

The stable vendor id.
vendor.name string Selectable in the Payload builder

The vendor name at the time the event was created.
vendor.slug string Selectable in the Payload builder

The vendor slug at the time the event was created.
vendor.description string Selectable in the Payload builder

The vendor description in the store's default language.
vendor.seo_title string Selectable in the Payload builder

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

The vendor page's SEO description in the store's default language.
vendor.image_id string Selectable in the Payload builder

The assigned Media-library image UUID, or null when no image is assigned.
vendor.image_url string Selectable in the Payload builder

The storefront URL for the assigned image, or an empty string.
vendor.image_cdn_url string Selectable in the Payload builder

The delivery URL for the assigned image, or an empty string.
vendor.product_count integer Selectable in the Payload builder

The number of products assigned to the vendor when the event was created.
vendor.template_handle string Selectable in the Payload builder

The storefront Vendor template assigned to the vendor.
vendor.created_at string Selectable in the Payload builder

When the vendor was created.
vendor.updated_at string Selectable in the Payload builder

When the vendor last changed.
vendor.translations_updated_at string Selectable in the Payload builder

When any vendor translation last changed, or null when none exist.
locale string Selectable in the Payload builder

The locale whose vendor or metafield translation changed.
translation.name string Selectable in the Payload builder

The translated vendor name; an empty string on the delete event means it was removed.
translation.slug string Selectable in the Payload builder

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

The translated vendor description; an empty string on the delete event means it was removed.
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.
updated_at string Selectable in the Payload builder

When this locale's translation last changed.

Vendor metafield translations updated

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

Fired after a vendor metafield translation is added or updated for a locale. The payload identifies the vendor, definition, locale, and translated value.

Payload fields

Field Type Description
metafield.vendor_id integer Always present

The stable id of the vendor that holds the translated value.
metafield.vendor_name string Selectable in the Payload builder

The vendor name when the event was created.
metafield.vendor_slug string Selectable in the Payload builder

The vendor slug when the event was created.
metafield.definition_id string Always present

The stable metafield definition UUID.
metafield.namespace string Selectable in the Payload builder

The definition namespace.
metafield.key string Selectable in the Payload builder

The definition key within its namespace.
metafield.name string Selectable in the Payload builder

The merchant-facing definition name.
metafield.type string Selectable in the Payload builder

The metafield value type.
metafield.app_id string Selectable in the Payload builder

The owning app id, or null for a merchant-owned definition.
metafield.app_access string Selectable in the Payload builder

Whether another authorized app may read the definition: private or shared.
metafield.merchant_access string Selectable in the Payload builder

How Store Admin can access an app-owned definition: hidden, read, or read_write.
locale string Selectable in the Payload builder

The locale whose vendor or metafield translation changed.
translation.value string Selectable in the Payload builder

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

When this locale's translation last changed.

Vendor metafield translations deleted

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

Fired after a vendor metafield translation is cleared, including during value or vendor deletion. The translated value is an empty string.

Payload fields

Field Type Description
metafield.vendor_id integer Always present

The stable id of the vendor that holds the translated value.
metafield.vendor_name string Selectable in the Payload builder

The vendor name when the event was created.
metafield.vendor_slug string Selectable in the Payload builder

The vendor slug when the event was created.
metafield.definition_id string Always present

The stable metafield definition UUID.
metafield.namespace string Selectable in the Payload builder

The definition namespace.
metafield.key string Selectable in the Payload builder

The definition key within its namespace.
metafield.name string Selectable in the Payload builder

The merchant-facing definition name.
metafield.type string Selectable in the Payload builder

The metafield value type.
metafield.app_id string Selectable in the Payload builder

The owning app id, or null for a merchant-owned definition.
metafield.app_access string Selectable in the Payload builder

Whether another authorized app may read the definition: private or shared.
metafield.merchant_access string Selectable in the Payload builder

How Store Admin can access an app-owned definition: hidden, read, or read_write.
locale string Selectable in the Payload builder

The locale whose vendor or metafield translation changed.
translation.value string Selectable in the Payload builder

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

When this locale's translation last changed.

Last updated Oct 21, 2026