Get location translation
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. |
locale
required
|
string |
Enabled non-default store locale. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
400STORE_API_INVALID_LOCATION_IDLocation ID is invalid.
-
400TRANSLATION_LOCALE_NOT_ENABLEDLocale is not enabled for this store.
-
400TRANSLATION_DEFAULT_LOCALE_FORBIDDENTranslations cannot target the store's default locale.
-
400TRANSLATION_RESOURCE_ID_NOT_IN_STORELocation does not exist in this store.
Set location translation
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. |
locale
required
|
string |
Enabled non-default store locale. |
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: |
Errors
-
400STORE_API_INVALID_LOCATION_IDLocation ID is invalid.
-
400STORE_API_INVALID_REQUEST_BODYRequest body must be a JSON object containing only documented fields; error.details.field identifies an unknown field.
-
400TRANSLATION_LOCALE_NOT_ENABLEDLocale is not enabled for this store.
-
400TRANSLATION_DEFAULT_LOCALE_FORBIDDENTranslations cannot target the store's default locale.
-
400TRANSLATION_FIELDS_REQUIREDEach row must contain at least one translated field.
-
400TRANSLATION_FIELD_NOT_TRANSLATABLEA field is not translatable for locations; only
name,pickup_instructionsandpickup_hoursare. -
400TRANSLATION_TOO_MANY_FIELDSThe request exceeds the translation field limit.
-
400TRANSLATION_STAGING_INVALID_CONTROL_CHARSA translated value contains unsupported control characters.
-
400TRANSLATION_FIELD_VALUE_TOO_LONGA translated value exceeds the overall translation value limit.
-
400TRANSLATION_FIELD_EXCEEDS_BYTE_LIMITA translated value exceeds the field's length limit.
-
400TRANSLATION_RESOURCE_ID_NOT_IN_STORELocation does not exist in this store.
-
503TRANSLATION_WRITE_BUSYOther 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 theRetry-Afterheader). -
400STORE_API_BODY_PROPERTY_UNKNOWNThe body has a property this request does not accept. The message and
error.details.propertieslist the allowed and required properties (nestedfor each object or list of objects). -
400STORE_API_BODY_PROPERTY_INVALIDA body property has the wrong type (
error.details.expected_type). The message anderror.details.propertieslist the allowed and required properties.
Batch get location 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. |
Query parameters
| Name | Type | Description |
|---|---|---|
ids
required
|
string |
Comma-separated location IDs. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
400TRANSLATION_LOCALE_NOT_ENABLEDLocale is not enabled for this store.
-
400TRANSLATION_DEFAULT_LOCALE_FORBIDDENTranslations cannot target the store's default locale.
-
400TRANSLATION_RESOURCE_ID_REQUIREDAt least one location ID is required.
-
400TRANSLATION_INVALID_RESOURCE_IDA location ID is invalid.
-
400TRANSLATION_RESOURCE_ID_NOT_IN_STOREA location does not exist in this store.
-
400TRANSLATION_TOO_MANY_RESOURCESThe request exceeds the translation batch resource limit.
Batch set location 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 |
Errors
-
401UNAUTHORIZEDAuthorization header missing, malformed, or token invalid/expired.
-
402SUBSCRIPTION_REQUIREDThe store does not have an active or trialing subscription.
-
403STORE_API_SCOPE_REQUIREDToken is valid but lacks the required scope for this call.
-
429RATE_LIMITEDThe token's request allowance is exhausted. Retry after the Retry-After header.
-
400STORE_API_INVALID_REQUEST_BODYThe body is not valid JSON or a row has an unknown key or a wrongly typed value.
-
400TRANSLATION_NO_WRITES_PROVIDEDtranslations is empty.
-
400TRANSLATION_TOO_MANY_ROWSMore than 100 rows; nothing is written.
-
503TRANSLATIONS_NOT_SAVED_RETRYNo row saved and every row failed only with
TRANSLATION_WRITE_BUSY: send the same request again aftererror.details.retry_after_seconds(also theRetry-Afterheader).error.detailsalso hastotalsand oneresultsentry per row with its error. -
422TRANSLATIONS_NOT_SAVEDNo row saved and at least one row failed with an error that sending again will not fix;
error.detailshastotalsand oneresultsentry per row with its error. -
400STORE_API_BODY_PROPERTY_UNKNOWNThe body has a property this request does not accept. The message and
error.details.propertieslist the allowed and required properties (nestedfor each object or list of objects). -
400STORE_API_BODY_PROPERTY_INVALIDA body property has the wrong type (
error.details.expected_type). The message anderror.details.propertieslist 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
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
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 |