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. Create products and variants, edit their fields and metafields, then publish to the stores you choose.

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 of never_published, pending, published, failed.
• draft_revision — the canonical entity’s integer revision; send it as PATCH revision, including zero when returned.
• revision — a product or variant store version’s opaque string token; copy it from the store read for store PATCH.

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.

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 on message.
• 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.