Catalog

Collections

Collections follow the same shape as every catalog entity: canonical values every store inherits, one store version per store that can override them, and the same four reads. If a collection uses images, they appear as media_ids in gallery order.

List collections

GET/api/v1/collectionspim:read

One cursor page of the account's collections, ordered oldest change first so a poller can walk the whole list and stop when next_cursor is null.

Query parameters

Parameter	Type	Description
`limit`	integer	Rows per page. Default 50, maximum 250; a value above the maximum is clamped and a non-numeric value falls back to the default.
`cursor`	string	The `next_cursor` of the previous page. Opaque — do not build or parse one. A cursor from a different list is rejected with `validation_failed`.
`updated_since`	RFC3339 date-time	Only collections whose own canonical record changed at or after this time. Store-version edits do not widen it. A non-RFC3339 value is rejected with `validation_failed`.
`status`	enum	Publish-state filter: `never_published`, `pending`, `published`, `failed`.
`search`	string	Free-text match on the collection's name or store title.

Response

The uniform list-item shape: id, type (here collection), title, draft_revision, pending_publish, last_publish_status, and store_ids, with next_cursor as the paging handle.

# Collections whose last publish failed
curl -s "https://api.peak-pim.com/api/v1/collections?status=failed&limit=250" \
  -H "Authorization: Bearer pk_live_..."

{
  "data": [
    {
      "id": "a3b4c5d6-e7f8-4901-a2b3-c4d5e6f70812",
      "type": "collection",
      "title": "Summer Trail",
      "draft_revision": 3,
      "pending_publish": true,
      "last_publish_status": "failed",
      "store_ids": ["9b2f6c1a-7d3e-4f80-b1c5-6a4e8d2b9c30"]
    }
  ],
  "next_cursor": null
}

Get a collection

GET/api/v1/collections/{id}pim:read

One collection's canonical values and where it stands with each store it lives on. An unknown id — including another account's or an id of a different kind of entity — answers 404 not_found.

Field	Type	Description
`id`, `type`, `title`	—	As on the list row; `type` is `collection`.
`attributes`	array	The canonical values every store inherits, as `{key, value, type}` triples (all strings).
`draft_revision`	integer	The optimistic-concurrency handle a later write sends back to prove it read the current state.
`pending_publish`, `last_publish_status`	—	As on the list row.
`media_ids`	uuid[]	The media files the collection uses, in gallery order, across every store.
`stores[]`	array	Publish state per store: `store_id`, `store_domain`, `pending_publish`, `last_publish_status`. Publish state only — the store's values live on the store subresources below.

{
  "id": "a3b4c5d6-e7f8-4901-a2b3-c4d5e6f70812",
  "type": "collection",
  "title": "Summer Trail",
  "attributes": [
    { "key": "handle", "value": "summer-trail", "type": "single_line_text_field" },
    { "key": "description", "value": "Lightweight gear for hot-weather trails.", "type": "multi_line_text_field" }
  ],
  "draft_revision": 3,
  "pending_publish": true,
  "last_publish_status": "failed",
  "media_ids": ["1f2e3d4c-5b6a-4798-8172-635a4b3c2d1e"],
  "stores": [
    {
      "store_id": "9b2f6c1a-7d3e-4f80-b1c5-6a4e8d2b9c30",
      "store_domain": "acme.myshopify.com",
      "pending_publish": true,
      "last_publish_status": "failed"
    }
  ]
}

Collections carry no product list here.

The collection entity exposes no membership field on this surface — variant_ids is a product field. To ask which collections a product belongs to, the MCP entity reads return an item's linked collections and products.

List a collection's store versions

GET/api/v1/collections/{id}/storespim:read

Every store version of the collection. Bounded by the account's stores, so the whole list is returned and next_cursor is always null. Each item carries store_id, store_domain, attributes, pending_publish, and last_publish_status.

{
  "data": [
    {
      "store_id": "9b2f6c1a-7d3e-4f80-b1c5-6a4e8d2b9c30",
      "store_domain": "acme.myshopify.com",
      "attributes": [
        { "key": "title", "value": "Summer Trail Essentials", "type": "single_line_text_field" }
      ],
      "pending_publish": true,
      "last_publish_status": "failed"
    }
  ],
  "next_cursor": null
}

Get one store's version

GET/api/v1/collections/{id}/stores/{store_id}pim:read

One store's version of the collection: the values that store publishes, which may differ from every other store's. store_id comes from GET /api/v1/stores. A collection with no version on the requested store answers 404 not_found.

curl -s "https://api.peak-pim.com/api/v1/collections/a3b4c5d6-e7f8-4901-a2b3-c4d5e6f70812/stores/9b2f6c1a-7d3e-4f80-b1c5-6a4e8d2b9c30" \
  -H "Authorization: Bearer pk_live_..."

Subresources

Collections carry three more reads, documented on their own pages:

Endpoint	Returns	Docs
`GET /api/v1/collections/{id}/translations`	Every locale the collection is translated into, with the translated values per store.	Translations
`GET /api/v1/collections/{id}/sales-channels?store_id=…`	The Shopify sales channels the collection is published to on one store. Reaches Shopify live, so it can answer `502`.	Sales channels
`GET /api/v1/collections/{id}/drops`	The drops that will change this collection, each narrowed to the changes that touch it.	Drops