Getting started
Core concepts
Peak PIM keeps one canonical version of every product, variant, collection, and media file across all of a merchant's Shopify stores. Five ideas — canonical values, store versions, attributes, relationships, and publish state — explain almost everything both developer surfaces return.
One entity, two sets of values
Every entity's values exist twice: the canonical values every store inherits, and one store version per connected store that can override them. A product's canonical title might be "Trail Runner 2" while its German store's version overrides it with a localized one — every other store keeps inheriting the canonical value.
The REST API calls these the entity and its store versions. MCP tool names use the
internal words: master for the canonical item, projection for one
store's version, and channel for a connected store. Same concept everywhere —
get_master_with_projections_v1 answers exactly what
GET /api/v1/products/{id} plus GET /api/v1/products/{id}/stores
answer together.
Attributes: {key, value, type} triples
Values — canonical and store-local alike — are attributes: flat
{key, value, type} triples in which all three members are strings.
There is no nested document to diff; comparing two versions of an entity means
matching attributes by key and comparing value.
{"key": "title", "value": "Trail Runner 2", "type": "text"}
{"key": "vendor", "value": "Peak Outfitters", "type": "text"}
{"key": "price", "value": "129.00", "type": "text"}
The type string matters most for custom fields: a metafield value must
match the type its definition
declares.
Entity types and relationships
The catalog has four entity types — product, variant,
collection, media — plus stores. Relationships are id
references on the entity:
| Field | On | Meaning |
|---|---|---|
variant_ids | Products only | The product's variants |
product_id | Variants only | The product the variant belongs to |
media_ids | Everything except media files | The media files the entity uses, in gallery order, across every store |
Media files are named by filename — their title carries the filename,
and search matches filename, tags, or alt text.
Publish state
Peak PIM edits are drafts until published, so every entity and every store version reports where its draft stands with Shopify:
| Field | Type | Meaning |
|---|---|---|
pending_publish | boolean | Draft changes exist that have not been pushed yet |
last_publish_status | enum | never_published · pending · published · failed |
draft_revision | integer, entities only | The optimistic-concurrency handle a write sends back to prove it read the current state |
The last_publish_status values are identical to the status
list filter's, so a value read from a response can be fed straight back into the
filter — the pattern behind
publish monitoring.
Publish state is where the entity stands with Peak PIM's stores. Shopify's own product status (active/draft/archived) is a per-store attribute value, not this field.
Stores and channels
A store is one linked Shopify store of the account: {id, domain, name},
listed by GET /api/v1/stores. Every store-scoped answer — store versions,
per-store publish state, sales channels, market records — is keyed by that
store_id. In MCP vocabulary the same thing is a channel and the
argument is channel_id.
An entity's detail response carries a stores[] array with publish state
per store it lives on — state only. The store's values live on the store
subresources (/stores and /stores/{store_id}).
The operations layer
On top of the catalog sit the operational surfaces — same account, same stores, same publish-state vocabulary:
- Definitions are the schema layer. Metafield definitions describe the custom fields an entity may carry and how each is typed; metaobject definitions describe structured content types with their field structure and entry counts. Read them before writing values. Guide.
- Translations are grouped by locale, then store. An entity's translations read returns the catalog of translatable fields plus, per locale, the translated values each store carries. Guide.
- Markets carry catalogs and price lists. Each Shopify market has per-store records (regions, currency, web presences) and attached catalogs with the price-list and publication handles a pricing integration addresses Shopify by. Guide.
- Drops are scheduled field changes. A drop is a named change window that applies field values when it opens and reverts them when it closes, tracking apply/revert status per change. Guide.
- Data health is a scan → issues → remediation loop. Scans compute catalog-quality dimensions and cache the results; issue lists name the entities behind the numbers; remediation batches fix them as drafts. Guide.