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 — the connector's write tier edits drafts, and its publish tier pushes items live to Shopify through the server-side orchestration. Full write and publish are available on MCP today.
- 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 has a delete tool or a
grantable delete permission.
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 only (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 | Not yet | Yes — publish_master_v1 (publish tier) |
| Delete | No — the one documented delete route is reserved and unreachable | No — no delete tool, no delete permission |
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 28 tools: 12 entity tools (reads, draft writes, publish) and 16 operations tools covering markets, definitions, translations, sales channels, drops, and data health.
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.