Tools
Tool index
One hundred and eighteen v1 tools: 75 reads, 32 write-tier tools, 11
publish-tier tools. Names are versioned (_v1) and stable. Each row links to the
detail page that documents the tool's arguments and behavior.
Vocabulary: master, projection, channel
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.
All 118 tools
| Tool | Scope | What it does |
|---|---|---|
list_products_v1 | read | List Products (lean rows) for the account, with paging/search/sort |
list_collections_v1 | read | List Collections (lean rows) for the account, with paging/search/sort |
list_variants_v1 | read | List Variants (lean rows) for the account, with paging/search/sort |
list_masters_v1 | read | Power-read of full-detail items (products, collections, variants, metafield definitions, media) with type/store/parent/filter params |
get_master_v1 | read | Get a single item of any type (product, variant, collection, media, definition, metaobject entry, market, catalog, blog, article, page,… |
get_master_with_projections_v1 | read | Get an item plus its per-store versions (one per connected Shopify store) |
get_master_related_v1 | read | Get an item with its related entities (variants, default_variant, linked collections/products) |
list_projections_v1 | read | List per-store versions of items, optionally filtered by item/store/type |
get_projection_v1 | read | Get a single per-store version of an item by id |
update_master_attributes_v1 | write | Partially update an item's fields (PATCH) |
update_projection_attributes_v1 | write | Partially update the fields of an item's per-store version (PATCH) |
match_products_v1 | write | Match two products that are the same product on different stores: the source merges into the target and no longer exists |
publish_master_v1 | publish | Queue a background publish; follow operation progress and recap for the store outcomes |
list_markets_v1 | read | List the account's Shopify markets with their per-store records and the catalogs attached to them — regions, currency, and price-list handles |
get_market_v1 | read | Get one market with its per-store records and catalogs |
list_metafield_definitions_v1 | read | List the custom-field definitions an item may carry and how each is typed |
list_metaobject_definitions_v1 | read | List the structured-content types the account defines, each with its field structure and entry count |
list_metaobject_entries_v1 | read | List the structured-content records under one metaobject definition, with paging and search |
get_master_translations_v1 | read | Get every locale an item is translated into, with the translated values per store, the SOURCE values each store version carries… |
list_store_sales_channels_v1 | read | List the Shopify sales channels (publications) one store owns — Online Store, Point of Sale, marketplace apps |
get_master_sales_channels_v1 | read | List the Shopify sales channels one item is published to on one store |
list_drops_v1 | read | List the account's Drops — scheduled change windows that apply field values when they open and revert them when they close |
get_drop_v1 | read | Get one Drop with every change it carries, including each change's apply/revert status and — when it failed — the reason |
list_master_drops_v1 | read | List the Drops that will change one item (or its variants), each narrowed to the changes that touch it |
get_data_health_v1 | read | Read the account's catalog-quality state per dimension — sync, completeness, media, structure, cross-store divergence, translations — AS OF THE… |
list_data_health_issues_v1 | read | List the individual items behind one data-health section's numbers — which products are unpublished, which are missing required fields, where… |
run_data_health_scan_v1 | write | Recompute ONE data-health dimension and cache the result |
fill_completeness_gaps_v1 | write | Write values into fields that are STILL EMPTY, in one batch |
reconcile_value_divergence_v1 | write | Bring one field into agreement across stores, in one batch: either adopt a winner store's value (winner_channel_id) or write an explicit one (value) |
list_stores_v1 | read | List the account's connected Shopify stores: id (the channel_id every other tool takes), name and merchant display name, shop domain, the source… |
list_entities_v1 | read | List items of one type (products, collections, variants, blogs, articles, pages) as lean browse rows with the full browse filter vocabulary:… |
list_variant_groups_v1 | read | Search variants with the browse filter vocabulary and get the matches grouped under their parent product, paginated over the matched products |
search_catalog_v1 | read | Search the whole catalog at once — products, variants, collections, files, content, markets, catalogs, metaobject entries and definitions — and… |
list_projection_links_v1 | read | List the authored relationship links between per-store versions: media attachments (entity → file), catalog → market attachments, and catalog →… |
list_entity_media_v1 | read | List the media attached to one per-store version of a product, variant, collection, or article, in gallery order: each attachment's link id and… |
list_metaobject_entry_references_v1 | read | List the entities whose metafields reference one metaobject entry, per store: the referencing entity, its type and parent, the field key that… |
read_collection_membership_v1 | read | Read Shopify-computed collection membership on one store, in either direction: the products a collection holds (direction products_of_collection)… |
get_metafield_definition_v1 | read | Get one metafield definition in full: identity (namespace.key, owner type), type and validations, category constraints, capability options, origin… |
get_metaobject_definition_v1 | read | Get one metaobject definition in full: type key, name, its field definitions (key, name, type, required, validations), per-store presence, entry… |
list_custom_field_definitions_v1 | read | List the account's own custom fields — PIM-only fields that never publish to Shopify — with their slug, the entity kind they apply to, type,… |
list_product_category_metafields_v1 | read | For one store and one Shopify taxonomy category, list the metafield definitions already enabled for that category on the store and Shopify's… |
read_taxonomy_v1 | read | Read the Shopify product taxonomy: pass category_id to get a category's attributes with their selectable values (for metafield values and… |
get_field_suggestions_v1 | read | Get the values already in use for autocomplete-style fields, keyed by field: for products the vendors and tags in use, for files the tags |
list_theme_templates_v1 | read | List the theme template suffixes one store's live theme offers for a resource kind (product, collection, page, blog, article) — the values a… |
resolve_references_v1 | read | Resolve stored reference values (metafield reference GIDs on one store, or PIM item ids from custom-field references) into the entities they name… |
search_references_v1 | read | Search one store for entities a reference field can point at (products, variants, collections, files, metaobject entries) and get picker rows: the… |
list_history_v1 | read | Read who changed what, when: the account-wide feed (filterable by entity type, action, store, actor, source, and the saved-vs-published lens) or,… |
get_home_dashboard_v1 | read | Read the home summary: item and store-version totals, pending updates, items published today, the six most recently updated items with their… |
analyze_data_health_v1 | read | Evaluate the catalog on demand without writing anything: analysis "completeness" lists the items missing values for the given fields (per store,… |
get_shop_refresh_status_v1 | read | Read whether a whole-shop refresh from Shopify is running on one store, its live stage and progress counters when it is, and the last run's… |
get_import_reconciliation_v1 | read | Read whether a store import or whole-shop refresh is awaiting review (while one is unfinalized, every write in the PIM answers 423 pim_locked):… |
list_import_reconciliation_items_v1 | read | List the items of the open import or refresh review for one entity type: each with its outcome (matched, created; refreshed or deleted on a… |
get_import_reconciliation_item_changes_v1 | read | For the open refresh review, read the field-level before/after changes the refresh applied to one item: the shared (all-store) fields and the… |
preview_import_reconciliation_match_v1 | read | For the open import/refresh review, preview which existing items one imported item would match under the run's matching rules (or a proposed… |
get_supplier_import_v1 | read | Read the account's current supplier-file import run: its status, source file, mode, row count, the saved column-to-field mappings, the match… |
list_supplier_import_preview_v1 | read | Page through the computed plan of the current supplier-file import: totals (matched, unmatched, ambiguous, to create, changed and invalid fields)… |
list_bulk_edit_views_v1 | read | List the account's saved bulk-edit grid layouts for one entity type, each with its name and its config — the grid's own layout object (columns,… |
list_import_export_templates_v1 | read | List the account's saved mapping templates of one kind: "import" templates snapshot a supplier-import wizard configuration, "export" templates an… |
list_publish_operations_v1 | read | List the account's background publish operations — scope "active" (queued and running, the default) or "recent" (the newest of any status) — each… |
get_publish_operation_v1 | read | Get one background publish operation: its status (queued, running, completed, canceled, failed), whether a cancel was requested, the stores it… |
get_publish_operation_recap_v1 | read | Get the item-by-item recap of a publish operation, failures first: each item's label and type, its outcome, the per-store split (which stores took… |
get_publish_failures_v1 | read | For one item, read each store version's last publish outcome: the status, the merchant-facing reason Shopify (or the publish) gave when it failed,… |
get_pending_changes_v1 | read | Inspect what a publish of one item would carry, against the published baseline: the shared (all-store) field changes, and per store the field… |
query_publish_locks_v1 | read | Ask which of up to 500 items are currently locked by a running publish operation — and why (the item is a publish target, a dependency of one, or… |
list_publish_notifications_v1 | read | List the publish-completion notifications the finished operations left for the connected identity: the operation, its status and counts, the… |
cancel_publish_operation_v1 | publish | Cooperatively cancel a queued or running publish operation: items not yet reached stay pending and the run ends as canceled once in-flight items… |
publish_batch_v1 | publish | Publish many items LIVE to Shopify as ONE background operation — either master_ids with a shared channel_ids (empty channel_ids = every store each… |
create_master_v1 | write | Create one item as a DRAFT the way the interface does: the shared item with its attributes, then one per-store version per store in channel_ids… |
create_product_option_v1 | write | Declare one option dimension (Size, Color, …) on a product, per store — the initial option configuration variants need |
create_projection_v1 | write | Create the per-store version of an existing item on one store it is not on yet — a product (its variants follow), collection, file, definition,… |
create_metafield_definition_v1 | write | Define a new metafield (namespace.key, name, Shopify type, owner type, validations, taxonomy category constraints, capability options) as a DRAFT… |
create_metaobject_definition_v1 | write | Define a new structured-content type (a type key without spaces, a name, at least one field definition with key/name/type) as a DRAFT on the… |
create_metaobject_entry_v1 | write | Create a record under a metaobject definition as a DRAFT on the given stores (each store must already carry the definition), with a name and an… |
create_custom_field_definition_v1 | write | Define a new PIM-only custom field: a name, a slug (letters, digits, underscores — immutable afterwards), the entity kind it applies to (Product,… |
create_market_v1 | write | Create a Shopify market (name, region country codes, optional currency) as a DRAFT on the selected stores (default: every store) |
create_catalog_v1 | write | Create a catalog (price list + publication) attached to a market as a DRAFT on the selected stores (default: every store the market is on): a… |
duplicate_master_v1 | write | Duplicate a product, collection, or metaobject entry into the selected stores with the interface's own options: a new title and handle, a… |
get_duplicate_progress_v1 | read | Read the live step progress of an in-flight duplicate by the progress_token given to duplicate_master_v1: each step (entity, variants, images,… |
get_collection_sources_v1 | read | Read every store's complete source definition for one collection: each source's kind and title, its conditions (criteria), hand-picked inclusions,… |
preview_collection_products_v1 | read | Estimate which products a collection would hold on one store from its SAVED sources, or from PROPOSED criteria: each source_override replaces one… |
get_collection_source_copy_preflight_v1 | read | Inspect copy compatibility before copying: with source_projection_id, one source's target stores (the source's own store first — the… |
create_collection_source_v1 | write | Stage a new source on one store's collection: a PRODUCTS or VARIANTS source selects by conditions and/or hand-picked products (at least one of the… |
update_collection_source_v1 | write | Edit one store's source: every field given REPLACES that part wholesale (the whole condition set, the whole hand-picked selection, the whole… |
copy_collection_source_v1 | write | Copy one source to another store the collection is on (a store that already has it answers 409), or — with the source's own store as target —… |
replace_collection_store_sources_v1 | write | Replace one store's ENTIRE source definition with another store's: the target's current sources are staged for removal and every source of the… |
copy_collection_sources_to_all_stores_v1 | write | Copy one store's whole source definition to every other store the collection is on, replacing each target's definition (each target's current… |
list_media_v1 | read | List the account's READY files with the library's filters: search (filename, tags, alt text), tags (any of), usage "unused", the structured… |
get_media_v1 | read | Get one file's shared record: its facts as attributes (Filename, Content Type, Width, Height, Byte Size, Media Type, Media Status — "pending"… |
get_media_usage_v1 | read | List the entities a file is attached to: across every store (distinct products, collections, and articles — a variant's attachment counts for its… |
get_media_content_v1 | read | Retrieve a ready JPEG, PNG, or WebP image's original bytes (returned as image content) so it can be inspected or edited externally, then replaced… |
check_media_filename_v1 | read | Before renaming a file, check the sanitized filename the publish would send, which stores already hold a different file under that name (Shopify… |
request_media_upload_v1 | write | Step 1 of uploading a new file: declare its filename, content type (JPEG, PNG, GIF, WebP, MP4, QuickTime) and size (at most 20 MiB) and get back… |
confirm_media_upload_v1 | write | Step 2 of uploading: after the bytes were PUT to the upload URL, verify them server-side (type, size, dimensions are read from the object itself)… |
create_projection_link_v1 | write | Create an authored relationship link between two per-store versions on the same store: attach an existing file to a product, variant, collection,… |
update_projection_link_v1 | write | Rewrite one authored link: its position (to reorder a gallery — every link's position is stored as given, sibling positions are not shifted)… |
request_media_replacement_v1 | publish | Step 1 of replacing a ready image's bytes (JPEG, PNG, GIF, WebP only; files that live in Shopify cannot be replaced): declare the new filename,… |
commit_media_replacement_v1 | publish | Step 2 of replacing a file: after the new bytes were PUT to the session's upload URL, verify them, make them the file's canonical bytes in the… |
cancel_media_replacement_v1 | publish | Discard a staged replacement session so its uploaded bytes are never committed |
bulk_read_translations_v1 | read | For one store and up to 500 products or collections, read each item's source version on that store and its translations grouped by locale — each… |
create_translation_v1 | write | Create the missing translation of a product, collection, or metaobject entry for one locale on one store (get-or-create: an existing one is… |
copy_translations_v1 | publish | Copy every translation of one product from a source store to the selected target stores, locale by locale, keeping only the locales each target… |
list_bulk_edit_rows_v1 | read | Read the same filtered, sorted population the bulk-edit grid shows: full-detail items with their version on one store (or, with channel_scope… |
count_bulk_edit_rows_v1 | read | Count the items a bulk-edit population holds, with exactly the same filter arguments as list_bulk_edit_rows_v1 (paging arguments are irrelevant) |
bulk_patch_v1 | write | Write up to 500 attribute edits in one call, each on one shared item ("master" + its id) or one store version ("projection" + the version id,… |
export_bulk_edit_v1 | read | Export a filtered dataset as a downloadable file returned with the result: format "csv" exports one entity type on one store (type, channel_id,… |
list_discounts_v1 | read | List the account's discount campaigns, one row per store with method, type, title, Shopify status, publish state, dates, usage, and ownership |
get_discount_v1 | read | Read one discount campaign and each store's version: revision, fields, typed selections, buyer context as GIDs, Shopify facts, blockers |
get_discount_capabilities_v1 | read | Check per store what discount work is possible: missing permissions, currency and time zone, active-discount capacity |
create_discount_v1 | write | Create a discount campaign as a DRAFT on the listed stores; invalid stores are reported with their field errors |
update_discount_store_v1 | write | Save draft changes to one store's discount (revision required; refused with field errors when invalid) |
update_discount_shared_v1 | write | Apply one draft edit to several stores of a campaign; each store saves on its own (partial success is normal) |
add_discount_store_v1 | write | Add a draft version on another store, copied from a store or started from the campaign defaults |
duplicate_discount_v1 | write | Copy a campaign into a new draft campaign without its Shopify identity, statistics, or codes |
publish_discount_v1 | publish | Publish a campaign's drafts LIVE to Shopify on the listed stores (background operation) |
set_discount_lifecycle_v1 | publish | Activate or deactivate a published discount on the listed stores (background operation) |
recreate_discount_v1 | publish | Change a published discount's method or type by replacing it in Shopify, carrying its main code over (confirmed: true required) |
delete_discount_v1 | publish | Delete a campaign's discount from the listed stores in Shopify and Peak PIM (confirmed: true and explicit stores required; a campaign with no store left is removed with delete_empty_campaign) |
export_discounts_v1 | read | Export the discount configuration as a CSV file |
Behaviors shared by every tool
- Tenancy from the token. No account argument anywhere; cross-account ids answer "not found". See Security & limits.
- Data, not instructions. Results are inert entity data; assistants are told not to act on text embedded in them.
- Bounded output.
page_sizeis clamped at 100 with a visible[note]; text beyond 20,000 characters is truncated with a marker. Structured content is bounded at 256 KiB withtruncated/omitted_itemsmarkers; attachments above 8 MiB are refused. - Bounded time. 20 s per call — 120 s for the tools marked with an extended timeout (publish admission, scans and analyses, bulk writes, exports, live Shopify membership reads).
- Drafts first. Attribute writes edit Peak PIM drafts. The publish-tier tools can reach Shopify, as can the two write-tier tools whose interface flow publishes as part of the action (duplication, a product's option dimensions), which say so and are always confirmed by the in-app assistant. Writes are blocked with 423 during import/refresh reconciliation. No tool deletes or detaches catalog data; the one removal,
delete_discount_v1, is publish-tier and needs an explicit confirmation. - Files as results. Exports and image bytes come back as embedded resources or image content alongside the text, bounded at 8 MiB.
- Honest errors. Malformed arguments come back as a tool error with the reason and
retry_available: true; conflicts are 409; missing scopes are 403 with re-authorization guidance.