Location translations

Translate a pickup location's name, pickup instructions, and pickup hours through the Store API.

Get location translation

GET read_locations + read_translations

Fetch one location's translation.

Returns the stored translations of name, pickup_instructions and pickup_hours for one location in the selected locale, with is_outdated. Shoppers see these when they choose the location for pickup in that language; an untranslated field shows the original. 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 string

Location id.

Example: d6a26466-7903-4e2f-8fd7-7c59f3c8cd9a
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_LOCATION_ID

    Location 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

    Location does not exist in this store.

Set location translation

PUT write_locations + write_translations

Set one location's translation.

Translatable fields are name, pickup_instructions and pickup_hours. Set a field to an empty string to remove its translation. Fires locations/translations/update or locations/translations/delete; translation writes do not fire locations/update. A write waits at most 2 seconds for other translation writes of the same item or of a clashing name or slug (for example a translation CSV import writing the same language); writes of other items, types and languages never wait. A row or call that fails with TRANSLATION_WRITE_BUSY (HTTP 503) saved nothing: send it again after error.details.retry_after_seconds (the call's Retry-After header says the same). Every row or call either saved or reports an error; none is left in an unknown state.

Path parameters

Name Type Description
id required string

Location id.

Example: d6a26466-7903-4e2f-8fd7-7c59f3c8cd9a
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: name, pickup_instructions, pickup_hours.

Example: {"name": "Entrepôt principal", "pickup_hours": "Lun–Sam 10:00–20:00"}

Errors

  • 400 STORE_API_INVALID_LOCATION_ID

    Location 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 row must contain at least one translated field.

  • 400 TRANSLATION_FIELD_NOT_TRANSLATABLE

    A field is not translatable for locations; only name, pickup_instructions and pickup_hours are.

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

    Location does not exist in this store.

  • 503 TRANSLATION_WRITE_BUSY

    Other translation writes held the item or a clashing name or slug for more than 2 seconds; nothing was saved. Send the request again after error.details.retry_after_seconds (also the Retry-After header).

  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).

  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

Batch get location translations

GET read_locations + read_translations

Fetch location translations in batch.

Returns a resources entry keyed by location:{id} for each requested location. A location 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 location IDs.

Example: d6a26466-7903-4e2f-8fd7-7c59f3c8cd9a

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_RESOURCE_ID_REQUIRED

    At least one location ID is required.

  • 400 TRANSLATION_INVALID_RESOURCE_ID

    A location ID is invalid.

  • 400 TRANSLATION_RESOURCE_ID_NOT_IN_STORE

    A location does not exist in this store.

  • 400 TRANSLATION_TOO_MANY_RESOURCES

    The request exceeds the translation batch resource limit.

Batch set location translations

PUT write_locations + write_translations

Set location translations for any languages in one call.

Each row is one location in one language: id, locale (any enabled non-default store locale) and fields. Rows for several languages can be mixed in one call; send at most 100 rows (one row = one location in one locale) and at most one row per location and locale. Each row is saved on its own: a failing row never stops the others. Empty values clear the matching field translation; omitted fields keep their translation. Every row is validated exactly like the single translation endpoint. The response has totals (rows, saved, failed) and one results entry per row in request order: {id, locale, status} with status saved or failed. A failed row carries the full error (code, message, details); its codes are the single endpoint's codes plus TRANSLATION_ROW_DUPLICATE. A saved rich-text row whose unsafe markup was removed lists warnings. A top-level code and message give the outcome: TRANSLATIONS_SAVED (200, every row saved), TRANSLATIONS_PARTIALLY_SAVED (200, success: true; the message counts saved and failed rows and names the failure reasons, e.g. "2 saved, 1 failed. No source text found for the requested fields (description).") TRANSLATIONS_NOT_SAVED_RETRY (503 with a Retry-After header, success: false; no row saved because every row failed only with TRANSLATION_WRITE_BUSY, so the same call can be sent again after error.details.retry_after_seconds) or TRANSLATIONS_NOT_SAVED (422, success: false; no row saved and at least one row failed for another reason). Both carry the same totals and results in error.details. With an Idempotency-Key, repeating the same request re-applies nothing that already saved and retries the failed rows. A write waits at most 2 seconds for other translation writes of the same item or of a clashing name or slug (for example a translation CSV import writing the same language); writes of other items, types and languages never wait. A row or call that fails with TRANSLATION_WRITE_BUSY (HTTP 503) saved nothing: send it again after error.details.retry_after_seconds (the call's Retry-After header says the same). Every row or call either saved or reports an error; none is left in an unknown state.

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>

Up to 100 rows shaped as {id, locale, fields}. Allowed field keys are name, pickup_instructions and pickup_hours.

Example: [{"fields":{"name":"Entrepôt principal"},"id":"d6a26466-7903-4e2f-8fd7-7c59f3c8cd9a","locale":"fr"},{"fields":{"name":"Entrepôt principal"},"id":"d6a26466-7903-4e2f-8fd7-7c59f3c8cd9a","locale":"de"},{"fields":{"name":"Entrepôt principal"},"id":"d6a26466-7903-4e2f-8fd7-7c59f3c8cd9a","locale":"pt-BR"}]

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 is not valid JSON or a row has an unknown key or a wrongly typed value.

  • 400 TRANSLATION_NO_WRITES_PROVIDED

    translations is empty.

  • 400 TRANSLATION_TOO_MANY_ROWS

    More than 100 rows; nothing is written.

  • 503 TRANSLATIONS_NOT_SAVED_RETRY

    No row saved and every row failed only with TRANSLATION_WRITE_BUSY: send the same request again after error.details.retry_after_seconds (also the Retry-After header). error.details also has totals and one results entry per row with its error.

  • 422 TRANSLATIONS_NOT_SAVED

    No row saved and at least one row failed with an error that sending again will not fix; error.details has totals and one results entry per row with its error.

  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).

  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

Webhook events#

Subscribe to these events when your integration mirrors localized locations. Update and clear events identify the locale and changed fields. One write can emit both events when it sets some fields and clears others. No event announces that translations became outdated. A translation is outdated (is_outdated: true) once its source field changes, and the location update event reports that change, so after an update that changes a translated field, treat that field's stored translations in every locale as outdated until they are updated or cleared.

Location translations updated

EVENT locations/translations/update App scope: read_locations, read_translations Staff permission: locations:read

Fired when a location's translations (name, pickup instructions, pickup hours) 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 locations/update.

Payload fields

Field Type Description
location.id string Always present
location.name string Always present
location.slug string Always present
location.app_id string Always present
location.is_app_managed boolean Always present
location.is_primary boolean Always present
location.is_active boolean Always present
location.fulfills_online_orders boolean Always present
location.fulfillment_priority integer Always present
location.address_line1 string Always present
location.address_line2 string Always present
location.city string Always present
location.state_province string Always present
location.state_province_display string Always present
location.postal_code string Always present
location.country_code string Always present
location.phone string Always present
location.offers_pickup boolean Always present
location.pickup_ready_in string Always present
location.pickup_instructions string Always present
location.pickup_hours string Always present
location.pickup_stocked_only boolean Always present
location.ships_to_countries array Always present
location.previous_app_id string Always present
location.previous_app_name string Always present
location.previous_app_released_at string Always present
location.created_at string Always present
location.updated_at string Always present
locale string Always present
translation.name string Selectable in the Payload builder
translation.pickup_instructions string Selectable in the Payload builder
translation.pickup_hours string Selectable in the Payload builder
updated_at string Always present

Location translations deleted

EVENT locations/translations/delete App scope: read_locations, read_translations Staff permission: locations:read

Fired when a location's translations are cleared for one or more fields in a locale. Deleting a location also sends one event per locale it had translations in, with each translated field empty.

Payload fields

Field Type Description
location.id string Always present
location.name string Always present
location.slug string Always present
location.app_id string Always present
location.is_app_managed boolean Always present
location.is_primary boolean Always present
location.is_active boolean Always present
location.fulfills_online_orders boolean Always present
location.fulfillment_priority integer Always present
location.address_line1 string Always present
location.address_line2 string Always present
location.city string Always present
location.state_province string Always present
location.state_province_display string Always present
location.postal_code string Always present
location.country_code string Always present
location.phone string Always present
location.offers_pickup boolean Always present
location.pickup_ready_in string Always present
location.pickup_instructions string Always present
location.pickup_hours string Always present
location.pickup_stocked_only boolean Always present
location.ships_to_countries array Always present
location.previous_app_id string Always present
location.previous_app_name string Always present
location.previous_app_released_at string Always present
location.created_at string Always present
location.updated_at string Always present
locale string Always present
translation.name string Selectable in the Payload builder
translation.pickup_instructions string Selectable in the Payload builder
translation.pickup_hours string Selectable in the Payload builder
updated_at string Always present