Getting started
Peak PIM Public API
The versioned, supported surface third-party systems program against. Read your whole catalog — products, variants, collections, media files, linked stores, and publish state — plus markets, definitions, translations, sales channels, and drops, with plain HTTPS and JSON.
| Base URL | https://api.peak-pim.com |
|---|---|
| Version | /api/v1 — additive after the documented private-beta exception (the promise) |
| Authentication | Authorization: Bearer pk_live_… API key (details) |
| Format | JSON over HTTPS; every failure uses one typed error envelope |
| Rate limits | 120 requests/minute per key, 240/minute per account (details) |
| Machine spec | OpenAPI 3.1 document |
The 2026-07-31 operations surface shipped the first POST endpoints:
data-health scans and remediation batches
(pim:write). A fourth write,
POST /api/v1/data-health/unused-deletions, is documented but
RESERVED — it requires pim:delete, a scope no credential can be
granted today. Everything else remains a read behind pim:read,
and further writes will arrive additively within v1.
The data model in one minute
A Peak PIM account owns a catalog shared by one or more linked Shopify stores. The core entities are products, variants, collections, and media files, living on stores — the Shopify stores linked to the account.
Every entity's values exist twice: the canonical values that every
store inherits, and one store version per store that can override
them. GET /api/v1/products/{id} returns the canonical side;
GET /api/v1/products/{id}/stores/{store_id} returns what one store
actually publishes.
Values are carried as attributes: flexible
{key, value, type} triples, on the entity and on each store version.
Relationships come as id arrays — a product's variant_ids and
media_ids, a variant's product_id.
Publish state
Peak PIM tracks where every draft stands with Shopify. Entities and store versions both carry:
pending_publish— there are draft changes not yet pushed to the store(s).last_publish_status— one ofnever_published,pending,published,failed.draft_revision— the entity's revision counter, the optimistic-concurrency handle a write sends back to prove it read the current state.
Endpoint families
Catalog entities share one uniform read family — list, detail, store versions, one store's version. Around it sits the operations surface: the schema, localization, channel, scheduling, and quality layers of the same catalog.
Products
List, read, and compare products — canonical values, variants and media, per-store publish state.
CatalogVariants
Variants with their parent product, SKU search, and their own store versions.
CatalogCollections
Collections with canonical values and one version per store.
CatalogMedia
Media files, named by filename, searchable by filename, tags, or alt text.
CatalogStores
The account's linked Shopify stores — the bounded list every store_id comes from.
Markets
Each market's per-store records, currencies, and the catalogs with their price-list and publication handles.
OperationsMetafield definitions
The custom-field schema layer to read before writing values, filterable by owner type.
OperationsMetaobject definitions
The account's structured content types, their field structure, and their entries.
OperationsTranslations
Translated values per locale and store for products and collections.
OperationsSales channels
Live Shopify channel membership per store — the only reads that can answer 502.
Drops
Scheduled change windows, account-wide or narrowed to one entity.
OperationsData health
Cached catalog-quality state, issue lists, and the first writes: scans and remediation batches.
The endpoint index lists every path with its method, scope, and summary on one page.
How the surface behaves
- Pagination & filtering — cursor pages with
next_cursor, bounded lists, the one page-numbered exception,updated_since/status/search, and ETag conditional reads. - Errors — one envelope everywhere; branch on
code, never onmessage. - Rate limits — per-key and per-account minute budgets with self-describing headers.
- Versioning — the compatibility promise, its private-beta exception, and how future breaking changes ship.