Guides

Translations & markets

Localization has two halves in Peak PIM: translations — what an entity says in each locale, per store — and markets — where and in what currency each store sells, with the catalogs and price lists behind regional pricing. Both are reads today, on both surfaces.

Reading an entity's translations

GET/api/v1/products/{id}/translationspim:read

GET/api/v1/collections/{id}/translationspim:read

Translations exist for products and collections. The response has two parts: the catalog of translatable fields, and the translated values grouped by locale, then by store. It is bounded by locales × stores, so the whole set is returned and next_cursor is always null.

curl -s https://api.peak-pim.com/api/v1/products/0e8f.../translations \
  -H "Authorization: Bearer pk_live_..."

{"entity_id": "0e8f...", "entity_type": "product",
 "translatable_fields": [
   {"key": "title", "shopify_key": "title", "label": "Title"},
   {"key": "body_html", "shopify_key": "body_html", "label": "Description"}
 ],
 "locales": [
   {"locale": "de",
    "stores": [
      {"store_id": "c3d4...", "store_domain": "acme-de.myshopify.com",
       "values": [
         {"key": "title", "value": "Trailrunner 2 Laufschuh", "type": "text"}
       ],
       "pending_publish": false, "last_publish_status": "published"}
    ]},
   {"locale": "fr", "stores": [...]}
 ]}

translatable_fields is the catalog: key is the field a translated value is written under, shopify_key is the same field as Shopify names it, and reference (when present) is the source value the row translates when it is not on the entity itself.
Locales are BCP-47 codes; each locale groups per-store values, because two stores can carry different translations of the same field.
Each per-store group carries its own publish state — a translation can be drafted and unpublished like any other value.

Coverage questions — "which fields have no French value anywhere?" — are a diff of translatable_fields against the keys present under a locale. For a server-computed answer across the whole catalog, the data-health translations dimension lists untranslated entities per target language.

Reading markets

GET/api/v1/marketspim:read

GET/api/v1/markets/{id}pim:read

Every Shopify market in the account, with its per-store records and the catalogs attached to it — the region, currency, and price-list structure a pricing or localization integration reads before it writes store-local values. Bounded by the account, so next_cursor is always null.

curl -s https://api.peak-pim.com/api/v1/markets \
  -H "Authorization: Bearer pk_live_..."

{"data": [
  {"id": "2a9b...", "name": "Europe", "pending_publish": false,
   "stores": [
     {"store_id": "c3d4...", "store_domain": "acme-de.myshopify.com",
      "shopify_gid": "gid://shopify/Market/123", "name": "Europe",
      "regions": ["DE", "FR", "NL"], "currency": "EUR",
      "web_presences": [...],
      "pending_publish": false, "last_publish_status": "published"}
   ],
   "catalogs": [
     {"id": "7c0d...", "title": "EU wholesale", "slug": "eu-wholesale",
      "pending_publish": false,
      "stores": [
        {"store_id": "c3d4...", "store_domain": "acme-de.myshopify.com",
         "shopify_gid": "gid://shopify/CompanyLocationCatalog/456",
         "status": "ACTIVE", "currency": "EUR", "price_adjustment": "-10%",
         "auto_publish": true,
         "price_list_gid": "gid://shopify/PriceList/789",
         "publication_gid": "gid://shopify/Publication/321",
         "pending_publish": false, "last_publish_status": "published"}
      ]}
   ]}
], "next_cursor": null}

Piece	What it tells you
Market store record	One store's version of the market: the country/region codes it covers, its currency, its web presences as Shopify returned them, and publish state
Catalog	One catalog attached to the market, with its own per-store records
Catalog store record	The handles a pricing integration addresses Shopify by — `price_list_gid` and `publication_gid` — plus status, currency, price adjustment, and `auto_publish`

Markets follow the same two-level shape as everything else: an account-level record with pending_publish, and per-store records carrying the store-local state. If your integration writes prices to Shopify price lists, price_list_gid per store is the handle you need.

The MCP equivalents

Tool	Arguments	Answers
`get_master_translations_v1`	`id` required; `channel_id` to restrict to one store	Every locale an item is translated into, with per-store values and the translatable-fields catalog. Products and collections only
`list_markets_v1`	—	The markets with per-store records and attached catalogs — read this before reasoning about regional pricing or localization
`get_market_v1`	`id` required	One market with its per-store records and catalogs

Useful prompts for a read-tier assistant:

"Which fields of product Trail Runner 2 still have no German translation?"
"List my markets with their regions and currencies."

Translations reference and markets reference.
Data health — translation coverage as a scanned dimension.
Audit drift across stores — intentional localization vs accidental drift.

Translations & markets

Reading an entity's translations

Reading markets

The MCP equivalents

Related