Resources

Changelog

Every change to the published API contract and the MCP connector, newest first. Within v1, changes are additive only — clients must ignore response fields they do not recognize. A breaking change would ship as v2 with a Deprecation/Sunset window on v1, except for the explicit private-beta correction recorded below.

2026-10-27 — Product and variant writes and publication

API-key integrations can now create products, create variants, update canonical and store values including metafields, and publish to explicitly selected stores. Drafts require pim:write; publication requires pim:publish.

PATCH requires the revision from a preceding read: an integer for canonical entities, an opaque string for store versions. Publish returns 202 with an operation; GET /api/v1/publish-operations/{operation_id} reports the outcomes for 24 hours. Variant publication keeps the parent-publication confirmation step. See the complete workflow.

2026-10-09 — Discounts (private beta, feature-gated)

New Discounts endpoint family and 13 MCP tools, for accounts with the Discounts feature (every other account gets 404). The MCP catalog is now 118 tools (75 reads, 32 write-tier tools, 11 publish-tier).

• Reads (pim:read) — the cursor list and detail, configuration CSV export, and GET /api/v1/discount-operations/{operation_id} for the outcome of a queued store write (readable for 24 hours).
• Draft writes (pim:write) — the first public entity writes: create, campaign and store PATCH, add a store, and duplicate. Nothing reaches Shopify until published. Writes carry the body revision; a stale one answers 409 conflict with current_revision.
• Store writes (pim:publish) — publish, activate, deactivate, recreate, and delete; each queues a background operation (202). Delete needs confirmed: true and explicit store_ids (an empty list is accepted only for a campaign with no store left, and removes it). It removes store discounts from Shopify and deletes no catalog entity; pim:delete stays never granted.
• MCP — see Discounts. delete_discount_v1 is the one removal tool; it is publish-tier and the in-app assistant waits for explicit confirmation before it runs.
• Additive error members — error.field_errors (422), error.current_revision (409), and error.missing_targets (409 when adding a store).

2026-09-24 — Documentation contract alignment

Documentation corrections to describe existing behavior; no runtime changes:

• MCP publication — single-item publish returns acceptance and an operation id. Follow progress and recap reads to establish store outcomes. The current tools cannot submit the parent-publication confirmation required for a variant whose product is absent from a target store; complete that first publication in the app.
• MCP permissions and limits — aligned all summaries with the 104-tool catalog, documented the two write-tier workflows that also publish, and described structured-result truncation and attachment limits.
• Public API — documented 409 publish_lock_conflict for remediation batches, corrected sales-channel error statuses, and clarified GET-only ETags and rate-limit accounting.

2026-09-07 — MCP connector: complete reads, publish control, creation, collection sources, media, translations, bulk edit

76 new tools, bringing the catalog to 104 (71 reads, 26 write-tier tools, 7 publish-tier). Same three consent tiers; still no delete tool. Existing tools are unchanged in shape; list_masters_v1, the three lean list tools, and get_master_translations_v1 gained arguments and fields additively.

• Catalog reads — stores and account capabilities, every browsable entity type with the interface's filter vocabulary (store presence, structured conditions, pending/failed flags, per-store field values), grouped variant search, global search, relationships (links, entity media, metaobject-entry references), Shopify-computed collection membership (single and batched), the field-information layer (definition detail, category metafields, taxonomy, suggestions, theme templates, custom fields), and reference resolution across stores.
• Activity & operations — change history, the home dashboard, read-only completeness and divergence analyses, whole-shop refresh status, the import/refresh review surface, the supplier-import wizard's run and plan, saved bulk-edit views and import/export templates.
• Publish operations — list operations, progress and item outcomes, the recap of published changes and failures (including the relationship rows a collection's sources produce), per-store failure explanations and responsible fields, the new get_pending_changes_v1 (field and relationship changes still owed to Shopify, backed by the new GET /api/masters/{id}/pending-changes), publish locks, completion notifications; publish-tier cooperative cancel and publish_batch_v1.
• Creation — products, variants, collections, blogs, articles, pages (with per-store versions), option dimensions, store-specific versions, metafield/metaobject definitions, metaobject entries, custom-field definitions, markets and catalogs, duplication with progress.
• Collection sources — read each store's definition, preview membership from saved or proposed criteria, check copy compatibility; add, edit, copy, replace, and copy-to-all-stores. Source removal is deliberately excluded.
• Media — library browse with filters, file facts and readiness, usage, image bytes (returned as image content), filename checks; upload, attach, reorder; the publish-tier replacement workflow (stage, commit, cancel). File deletion and detachment are excluded.
• Translation editing — get_master_translations_v1 now carries source values and per-store locale coverage; bulk read, create a missing translation, copy translations between stores (publish-tier, since the copies are published).
• Bulk edit & export — the grid's population and count, general bulk patches with per-item outcomes, and CSV/XLSX exports returned as files (8 MiB bound).

Notes for integrators:

• Tool results may now carry embedded resources or image content next to the text (exports, image bytes); the text and structured content describe the file.
• Two write-tier tools reach Shopify because the interface's own flow does: duplicate_master_v1 publishes the copy, and create_product_option_v1 republishes already-published stores for the new dimension. Both are annotated open-world/destructive; the in-app assistant always confirms them.
• The publish-tier failure reasons (get_publish_failures_v1, recaps, notifications) carry the same merchant-facing wording the app shows.

2026-08-11 — Remove metaobject label translations (private-beta v1 exception)

Removed GET /api/v1/metaobject-definitions/{id}/translations. Metaobject definition display names and field labels are not translation resources in Peak PIM. The definition's translatable capability remains supported and continues to enable entry-value translation in Shopify Translate & Adapt. The get_master_translations_v1 MCP tool now supports products and collections only.

This is an explicit breaking-change exception while v1 remains in private beta. The original 2026-07-31 entry remains below as superseded release context. Product and collection translation reads are unchanged.

2026-07-31 — Public API: operations surface

Added. Reads require pim:read unless noted.

• Markets — GET /api/v1/markets, GET /api/v1/markets/{id}: each market with its per-store records (regions, currency, web presences) and attached catalogs, including the price-list and publication handles a pricing integration addresses Shopify by.
• Metafield and metaobject definitions — the schema layer to read before writing values: GET /api/v1/metafield-definitions (filterable by owner_type), GET /api/v1/metaobject-definitions with field structure and entry counts, plus /{id}/entries.
• Translations — GET /api/v1/products/{id}/translations, /api/v1/collections/{id}/translations, /api/v1/metaobject-definitions/{id}/translations — grouped by locale, then by store, with the catalog of translatable fields. The metaobject definition endpoint was removed on 2026-08-11 under the private-beta v1 exception above; it is retained here as superseded historical context.
• Sales channels — GET /api/v1/stores/{id}/sales-channels and /api/v1/{products,variants,collections}/{id}/sales-channels?store_id=. These query Shopify live — the only endpoints that can answer 502.
• Drops — scheduled field changes: GET /api/v1/drops, /api/v1/drops/{id}, and /api/v1/{products,variants,collections}/{id}/drops.
• Data health — GET /api/v1/data-health and /api/v1/data-health/issues (pim:read); POST /api/v1/data-health/scans, /completeness-fills, /divergence-reconciles (pim:write) — the first non-GET endpoints on v1; POST /api/v1/data-health/unused-deletions (pim:delete) documented but reserved.

Notes for integrators:

• The two remediation batches report partial success: a 200 means the batch ran, not that every operation succeeded — read results per operation. Both write drafts only; nothing reaches Shopify until an explicit publish.
• Both batches re-check the condition they are remediating immediately before writing, so a stale batch cannot clobber values filled since the last scan.
• Every list added here is bounded and returns the whole set with next_cursor: null — except GET /api/v1/data-health/issues, which is page-numbered (page, page_size, has_next) because a section is a live query over changing state.

2026-07-31 — MCP connector: operations tools

16 new tools, bringing the catalog to 28. Same consent tiers; reads need the read tier unless noted.

• Markets & definitions — list_markets_v1, get_market_v1, list_metafield_definitions_v1, list_metaobject_definitions_v1, list_metaobject_entries_v1.
• Translations & sales channels — get_master_translations_v1, list_store_sales_channels_v1, get_master_sales_channels_v1 (the sales-channel tools query Shopify live).
• Drops — list_drops_v1, get_drop_v1, list_master_drops_v1.
• Data health — get_data_health_v1, list_data_health_issues_v1, run_data_health_scan_v1, plus the write-tier remediation batches fill_completeness_gaps_v1 and reconcile_value_divergence_v1 (partial success; drafts only; re-check before write).

2026-07-28 — Public API: v1 read API

Added, all requiring the pim:read scope:

• GET /api/v1/products, /api/v1/variants, /api/v1/collections, /api/v1/media — cursor-paginated lists (limit default 50, max 250; opaque cursor), filterable by updated_since, status, and search.
• GET /api/v1/{resource}/{id} — one entity's canonical values, draft_revision, relationships (product_id, variant_ids, media_ids), and per-store publish state.
• GET /api/v1/{resource}/{id}/stores and GET /api/v1/{resource}/{id}/stores/{store_id} — the entity's store-local values, one item per store.
• GET /api/v1/stores — the account's linked Shopify stores.

Notes for integrators:

• updated_since matches an entity's own record recency. Editing one store's version of an entity does not widen it — re-read that entity's store versions when you need store-local changes.
• status is publish state (never_published, pending, published, failed), not Shopify's per-store product status.
• Every list response is {"data": [...], "next_cursor": ...}. The store-scoped lists are bounded by the account's stores and always return next_cursor: null.

Already live from the platform foundations, unchanged here: GET /api/v1/ping, pk_live_ bearer keys with scopes, the typed error envelope, the X-RateLimit-* headers and 429 budget, and ETag/If-None-Match on reads.

2026-07 — MCP connector: v1 tools

• Remote MCP endpoint at https://api.peak-pim.com/mcp (streamable HTTP) with OAuth 2.1: dynamic client registration, PKCE S256, refresh tokens, and a browser consent page with three permission tiers (read / read & write / read, write & publish).
• 12 versioned tools: list_products_v1, list_collections_v1, list_variants_v1, list_masters_v1, get_master_v1, get_master_with_projections_v1, get_master_related_v1, list_projections_v1, get_projection_v1, update_master_attributes_v1, update_projection_attributes_v1, publish_master_v1.
• Connection management (list / disconnect / revoke all) in Settings → AI assistants (MCP).