Catalog

Products

A product's values exist twice: the canonical values every store inherits, and one store version per store that can override them. These endpoints read and edit both, create products and publish drafts, and expose the product's relationships — its variants, its media files, and where it stands with each store.

List products

Query parameters

Response

# Everything that changed since July 1, biggest pages
curl -s "https://api.peak-pim.com/api/v1/products?limit=250&updated_since=2026-07-01T00:00:00Z" \
  -H "Authorization: Bearer pk_live_..."

{
  "data": [
    {
      "id": "5e0deff8-4b6f-4a24-9d6d-2f8c2f2a9a11",
      "type": "product",
      "title": "Trail Runner 2",
      "draft_revision": 14,
      "pending_publish": true,
      "last_publish_status": "published",
      "store_ids": ["9b2f6c1a-7d3e-4f80-b1c5-6a4e8d2b9c30"]
    }
  ],
  "next_cursor": "eyJvZmZzZXQiOjI1MH0"
}

Get a product

{
  "id": "5e0deff8-4b6f-4a24-9d6d-2f8c2f2a9a11",
  "type": "product",
  "title": "Trail Runner 2",
  "attributes": [
    { "key": "Vendor", "value": "Acme", "type": "single_line_text_field" },
    { "key": "Tags", "value": "trail,running", "type": "single_line_text_field" }
  ],
  "draft_revision": 14,
  "pending_publish": true,
  "last_publish_status": "published",
  "variant_ids": ["c7a1d2e3-5b6f-4890-a1b2-c3d4e5f60718"],
  "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": "published"
    }
  ]
}

List a product's store versions

{
  "data": [
    {
      "store_id": "9b2f6c1a-7d3e-4f80-b1c5-6a4e8d2b9c30",
      "store_domain": "acme.myshopify.com",
      "revision": "sv1_<opaque token from the API>",
      "attributes": [
        { "key": "Title", "value": "Trail Runner 2 — US Edition", "type": "single_line_text_field" }
      ],
      "pending_publish": false,
      "last_publish_status": "published"
    }
  ],
  "next_cursor": null
}

Get one store's version

curl -s "https://api.peak-pim.com/api/v1/products/5e0deff8-4b6f-4a24-9d6d-2f8c2f2a9a11/stores/9b2f6c1a-7d3e-4f80-b1c5-6a4e8d2b9c30" \
  -H "Authorization: Bearer pk_live_..."

Create a product

Create a product draft and its default variant on the explicitly selected stores. store_ids must contain at least one linked store, with no duplicates. Canonical attributes seed each store version; optional store_attributes overrides values by selected store ID. The whole creation succeeds or rolls back together. The response is 201 with the product in the same shape as the detail read.

curl -sS -X POST "https://api.peak-pim.com/api/v1/products" \
  -H "Authorization: Bearer $PEAK_PIM_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "attributes": [
    {
      "key": "Internal Name",
      "value": "Trail Runner 2",
      "type": "single_line_text_field"
    },
    {
      "key": "Title",
      "value": "Trail Runner 2",
      "type": "single_line_text_field"
    }
  ],
  "store_ids": [
    "9b2f6c1a-7d3e-4f80-b1c5-6a4e8d2b9c30"
  ],
  "store_attributes": {
    "9b2f6c1a-7d3e-4f80-b1c5-6a4e8d2b9c30": [
      {
        "key": "Title",
        "value": "Trail Runner 2 — EU",
        "type": "single_line_text_field"
      }
    ]
  }
}'

Creation saves drafts only. No change reaches Shopify until you publish. There are no idempotency keys: if a create response is lost, inspect the catalog before retrying to avoid creating a duplicate.

Starting a product with real variants

Declare initial option dimensions in the product’s store_attributes when creating it, then create the variants before publishing. For example, a selected store can receive these attributes alongside its Title:

[
  {"key": "Option 1 Name", "value": "Size", "type": "single_line_text_field"},
  {"key": "Option 1 Values", "value": "[\"S\",\"M\"]", "type": "list.single_line_text_field"}
]

Each variant then sets Option: Size on that store. Initial option positions must be consecutive (1–3), names unique and non-empty, and each dimension must declare values. Later option-dimension editing is outside these public endpoints.

Update canonical values

Read the entity first, then send its integer draft_revision as revision with a changes object. Zero is valid for a newly created or imported record. Attribute keys are case-sensitive: use Title, Vendor or SKU, exactly as returned. Only the named canonical fields change; existing store versions keep their own values. To change what Shopify receives, update the relevant store version below.

{
  "revision": 14,
  "changes": {
    "Title": "Trail Runner 3"
  }
}

Update one store’s values and metafields

Read the store version and copy its opaque string revision into the PATCH body. This token is specific to the entity and store, and differs from the canonical integer revision and the HTTP ETag. The response contains the updated store version and revision. A stale token saves nothing and returns 409 conflict with error.current_revision; read again before reapplying the intended edit.

{
  "revision": "<revision from this store read>",
  "changes": {
    "mf:custom.material": "Cotton"
  }
}

Metafields are ordinary attributes with keys mf:<namespace>.<key>. Read the account’s metafield definitions for the owner type and value type before writing. JSON, list and rich-text values are JSON encoded inside the value string. An empty string clears a value. Invalid typed values refuse the complete request; computed fields remain read-only. These endpoints change values, not metafield definitions.

Publish and follow the result

Name the target stores explicitly in a non-empty store_ids array. Every selected store must carry this product. Publishing a product also sends its eligible variants. The response is 202 with an operation; acceptance does not mean the changes are live.

{
  "store_ids": [
    "9b2f6c1a-7d3e-4f80-b1c5-6a4e8d2b9c30"
  ]
}

Poll with the returned operation ID while status is queued or running. Terminal statuses are completed, failed and canceled; inspect each store’s outcome. An operation can finish while some stores failed. Operation records remain readable for 24 hours; missing, expired, foreign-account, and other kinds of operation all return 404 not_found.

{
  "operation": {
    "id": "d5528b76-6bd1-41ea-9e37-b67ce290369a",
    "status": "completed",
    "store_ids": [
      "9b2f6c1a-7d3e-4f80-b1c5-6a4e8d2b9c30"
    ],
    "created_at": "2026-10-27T10:00:00Z",
    "finished_at": "2026-10-27T10:00:05Z",
    "counts": {
      "total": 1,
      "completed": 1,
      "succeeded": 1,
      "failed": 0
    },
    "entities": [
      {
        "entity_id": "5e0deff8-4b6f-4a24-9d6d-2f8c2f2a9a11",
        "entity_type": "product",
        "status": "ok",
        "stores": [
          {
            "store_id": "9b2f6c1a-7d3e-4f80-b1c5-6a4e8d2b9c30",
            "status": "ok"
          }
        ]
      }
    ]
  }
}

Variant parent confirmation

A variant whose parent product has not been created on Shopify may require 409 parent_publish_confirmation_required. Review the returned products, stores and variant counts: this action also publishes the parent and eligible sibling variants. Only after approving that scope, resend the same stores with parent_publish_confirmation: {"fingerprint": "<returned fingerprint>"}. An obsolete fingerprint produces a fresh challenge; it never silently widens the publication.

A 423 pim_locked means import or refresh reconciliation must finish first. A 409 publish_lock_conflict means a running operation owns records needed by this write. See Errors for recovery.

Subresources

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