Peak PIMDevelopers

Operations

Metaobject definitions

The structured content types the account defines — each with its canonical field structure and its account-wide entry count — and the entries recorded under each definition.

List metaobject definitions

GET/api/v1/metaobject-definitionspim:read

The account's metaobject definitions. Bounded by the account, so the whole list is returned and next_cursor is always null. 

curl "https://api.peak-pim.com/api/v1/metaobject-definitions" \
  -H "Authorization: Bearer $PEAK_PIM_KEY"

Response — 200

{
  "data": [
    {
      "id": "9d4e2a7b-1c8f-4b6a-8e3d-5f2c9b1a7e40",
      "type": "size_guide",
      "name": "Size guide",
      "description": "Fit tables reused across product pages.",
      "display_name_key": "title",
      "fields": [
        { "key": "title", "name": "Title", "type": "single_line_text_field", "required": true },
        {
          "key": "table",
          "name": "Table",
          "description": "The fit table, as rich text.",
          "type": "rich_text_field",
          "required": false,
          "validations": []
        }
      ],
      "publishable": true,
      "entry_count": 12,
      "has_structure_conflict": false,
      "pending_publish": false,
      "last_publish_status": "published",
      "stores": [
        {
          "store_id": "1e8e4c2a-9f3b-4d7c-8a5e-6b2d9c1f7a30",
          "store_domain": "acme-eu.myshopify.com",
          "shopify_gid": "gid://shopify/MetaobjectDefinition/8837462",
          "name": "Size guide",
          "pending_publish": false
        }
      ]
    }
  ],
  "next_cursor": null
}

Get one metaobject definition

GET/api/v1/metaobject-definitions/{id}pim:read

One definition, as a single object with the same shape as a list item. 404 not_found for ids from another account or of a different kind of entity.

The definition shape

FieldTypeDescription
iduuidThe definition's id in Peak PIM.
typestringThe Shopify definition type — the cross-store identity key.
namestringThe definition's display name.
descriptionstringThe definition's description, when set.
display_name_keystringWhich field's value names an entry.
fieldsarrayThe canonical field structure, in definition order — see below.
publishablebooleanEntries can be draft or active.
entry_countintegerThe account-wide entry count.
has_structure_conflictbooleanStores disagreed about this definition's structure as of the last import.
pending_publish / last_publish_statusboolean / enumThe usual publish state.
storesarrayOne presence record per store, same shape as on metafield definitions.

Each item in fields is one field of the structure:

FieldTypeDescription
keystringThe field key an entry's value is written under.
namestringThe field's display name.
descriptionstringThe field's description, when set.
typestringShopify's field type.
requiredbooleanWhether entries must fill this field.
validationsarray{"name": …, "value": …} pairs.

List a definition's entries

GET/api/v1/metaobject-definitions/{id}/entriespim:read

The structured content records under one definition, with their values and per-store publish state. Bounded by one definition, so next_cursor is always null.

Response — 200

{
  "data": [
    {
      "id": "c8a1f4e2-6b3d-4a9c-8f1e-2d7b5c9a4e61",
      "definition_id": "9d4e2a7b-1c8f-4b6a-8e3d-5f2c9b1a7e40",
      "handle": "size-guide-tops",
      "title": "Tops",
      "attributes": [
        { "key": "title", "value": "Tops", "type": "single_line_text_field" }
      ],
      "draft_revision": 4,
      "pending_publish": false,
      "last_publish_status": "published",
      "stores": [
        {
          "store_id": "1e8e4c2a-9f3b-4d7c-8a5e-6b2d9c1f7a30",
          "store_domain": "acme-eu.myshopify.com",
          "pending_publish": false,
          "last_publish_status": "published"
        }
      ]
    }
  ],
  "next_cursor": null
}

An entry's attributes carry its values as {key, value, type} triples; draft_revision is the same optimistic-concurrency handle entities carry. The entry named by the definition's display_name_key surfaces that value as title.

Notes