Tool reference

Twelve v1 tools: nine reads, two draft writes, one publish. Names are versioned (_v1) and stable.

Vocabulary: master & projection.

Tool names use Peak PIM's internal words. A master is the canonical item every store inherits (a product, collection, variant, metafield definition, or media file). A projection is one store's version of that item — the values that store actually publishes. A channel is a connected Shopify store, so channel_id means store id.

Tool	Scope	What it does
`list_products_v1`	read	Lean product rows with paging/search/sort
`list_collections_v1`	read	Lean collection rows
`list_variants_v1`	read	Lean variant rows
`list_masters_v1`	read	Power-read: full-detail items of any type
`get_master_v1`	read	One item by id
`get_master_with_projections_v1`	read	One item plus its per-store versions
`get_master_related_v1`	read	One item plus related entities
`list_projections_v1`	read	Per-store versions, filterable
`get_projection_v1`	read	One per-store version by id
`update_master_attributes_v1`	write	Patch an item's draft fields
`update_projection_attributes_v1`	write	Patch a store version's draft fields
`publish_master_v1`	publish	Publish an item live to Shopify

Read tools pim:read

list_products_v1 · list_collections_v1 · list_variants_v1

List entities of one type as lean rows — the fast way to browse. All arguments are optional:

Argument	Type	Description
`channel_id`	string	Restrict to a single store.
`page`	integer	1-based page number.
`page_size`	integer	Rows per page; values above 100 are clamped with a visible note.
`search`	string	Free-text search.
`sort` / `sort_source` / `order`	string	Sort field, sort source (`master` = canonical item, `projection` = per-store version), and `asc`/`desc`.
`exclude_default_variants`	boolean	Hide auto-created default variants (variants only, but accepted everywhere).

list_masters_v1

The power-read: full-detail items of any type — products, collections, variants, metafield definitions, media — with more filters. Prefer the lean list tools above for simple browsing; use this when you need full attribute detail or the extra filters.

Argument	Type	Description
`type`	string	Item type filter (product, collection, variant, metafield definition, media).
`channel_id`	string	Store filter.
`parent_master_id`	string	Children of this parent item — e.g. the variants of a product.
`filter`	string	Server-side filter expression.
`page` / `page_size` / `search`		As above.

get_master_v1

Get a single item by id (required). Ids from another account answer "not found".

get_master_with_projections_v1

Get an item plus its per-store versions — one per connected store. The one-call way to compare what each store publishes. Argument: id (required).

list_projections_v1

List per-store versions directly, optionally filtered by master_id (versions of one item), channel_id (one store), and/or type.

get_projection_v1

Get one per-store version by its id (required).

Write tools pim:write

Both writes edit drafts inside Peak PIM. Nothing reaches Shopify until something publishes.

update_master_attributes_v1

Partially update an item's canonical fields.

Argument	Type	Description
`id`	string, required	Item id.
`changes`	object, required	Field key → new value upserts. An empty value clears the field's value but keeps the field.
`revision`	integer	Optimistic concurrency: pass the item's current draft revision; a stale non-zero value is rejected with 409. Omit or 0 for last-write-wins.

Option-model keys (a product's option structure) are rejected with 400 — options can't be edited through this tool.

update_projection_attributes_v1

Partially update a per-store version's fields. Arguments: id (required) and changes (required), as above. Per-store versions have no revision check; a change producing a duplicate variant option tuple is rejected with 409.

Publish tool pim:publish

publish_master_v1

Publish an item live to Shopify through Peak PIM's publish orchestration — the same one the app uses: variant cascade, media sync, and collection-membership sync included.

Argument	Type	Description
`id`	string, required	Item id.
`channel_ids`	string[]	Restrict the publish to these store ids (validated against the account). Omit to publish to every store the item has a per-store version on.

Behavior to expect:

Partial failure is possible. A completed orchestration can still fail on some stores or variants: the result carries ok: false with per-store errors and per-variant variant_results, and the text is prefixed with a [partial failure] note. Already-published stores are live; failed ones are not.
Timeouts don't mean failure. The call allows 120 s; if it still times out, the server-side publish may complete anyway — re-read the item and check its publish state.

Errors an assistant will see

Situation	Result
Tool outside the granted tier	403 permission error with re-authorization guidance.
Id from another account, or nonexistent	"Not found" — the two are indistinguishable.
Write during import/refresh reconciliation	423 — the account is locked until reconciliation is finalized in the app.
Stale `revision` / duplicate option tuple	409 conflict — re-read, then retry with fresh state.
Malformed arguments	A tool error with the reason and `retry_available: true` — fix the arguments and call again.