Getting started
API or MCP?
Peak PIM has two developer surfaces reading the same catalog: a versioned REST API for your systems, and a remote MCP connector for your AI assistants. This page is the decision in one sitting — what each is for, how they authenticate, and what each can do today.
Same catalog underneath
Both surfaces answer from the same account, the same stores, and the same
data model: canonical values, store versions,
{key, value, type} attributes, and publish state. The difference is
the caller. The REST API is the versioned, supported contract
for code — stable shapes, cursor pagination, ETags, typed errors. The
MCP connector wraps the same data as tools an AI assistant
calls conversationally, behind an OAuth consent the merchant controls.
When to use the REST API
- Recurring syncs — mirror the catalog into an ERP, data warehouse, or storefront on a schedule. Cursor pagination,
updated_since, and ETags make a daily poll nearly free. - Backend integrations — anything running unattended where you want a fixed contract, deterministic errors, and a key you can rotate.
- Dashboards and monitors — publish-state alerting, drift reports, data-health remediation batches driven by your own scheduler.
When to use MCP
- Interactive catalog work — "find every variant missing a SKU", "where do titles differ across my stores?", answered in Claude, ChatGPT, or Cursor.
- Draft-then-publish workflows — attribute patches edit drafts, and publish-tier tools push items live through the server-side orchestration. Two write-tier creation workflows also publish: duplication and adding product options. See the consent tiers before granting write access.
- Agents you don't want holding a key — OAuth consent binds a connection to one account and one permission tier, revocable in the app at any time.
Authentication compared
| REST API | MCP connector | |
|---|---|---|
| Credential | pk_live_ API key, sent as Authorization: Bearer |
OAuth 2.1 — dynamic client registration, PKCE, refresh tokens; no key to copy around |
| Created by | A signed-in store user in Settings → API; shown once, stored hashed | A browser consent page opened when the connector is added; the signed-in account is the account the connection binds to |
| Permissions | Scopes on the key: pim:read, pim:write, pim:publish, pim:webhooks |
One of three consent tiers: read · read & write · read, write & publish |
| Publish authority | No publish endpoint published on v1 yet | pim:publish is grantable only through the consent flow |
| Revocation | Revoke the key; validation is a live lookup, so it fails on its next request | Settings → AI assistants (MCP); revocation also invalidates refresh tokens |
Credentials never cross over: an API key can only reach /api/v1 paths,
and only an API key can reach them. Neither surface can delete catalog data or grant
a delete permission; the one removal on either is a Shopify checkout discount, at
the publish tier with an explicit confirmation.
Capabilities compared
Today the two surfaces differ most in what they can change:
| Capability | REST API (v1) | MCP connector |
|---|---|---|
| Read the catalog (products, variants, collections, media, stores) | Yes | Yes |
| Read the operations layer (markets, definitions, translations, sales channels, drops, data health) | Yes | Yes |
| Edit draft values | Data-health remediation batches, and discount drafts for accounts with the Discounts feature (pim:write) | Yes — update_master_attributes_v1, update_projection_attributes_v1 (write tier) |
| Run data-health scans | Yes — POST /api/v1/data-health/scans (pim:write) | Yes — run_data_health_scan_v1 |
| Publish live to Shopify | Discounts only, for accounts with the Discounts feature (pim:publish) | Yes — publish_master_v1 (publish tier) |
| Delete | No catalog delete — the one documented delete route is reserved and unreachable (removing a store's discount from Shopify, POST /api/v1/discounts/{id}/delete, is pim:publish) | No catalog delete — no entity delete tool, no delete permission (the one removal is delete_discount_v1, which deletes store discounts from Shopify at the publish tier) |
Write and publish scopes already exist on API keys, and write endpoints will arrive additively within v1 — their error codes (conflict, pim_locked) are already published. The data-health POST endpoints are the first non-GET routes on v1.
Surface size
The REST API is the endpoint index plus the formal OpenAPI 3.1 spec. The MCP connector exposes 118 tools: the 12 core entity tools (reads, draft writes, publish), 16 operations tools (markets, definitions, translations, sales channels, drops, data health), and the 2026-09-07 groups — complete catalog reads, activity and operational state, publish monitoring and control, entity creation, collection sources, media, translation editing, bulk edit with export, and checkout discounts.
Using both
Most serious integrations end up with both: the REST API for the scheduled mirror and the monitors, MCP for the humans-plus-assistant work on top. Because the surfaces share ids and vocabulary, an entity id found by one is valid on the other.