Guides

Metafields & metaobjects

Definitions are the schema layer of the catalog: metafield definitions describe the custom fields an entity may carry and how each is typed; metaobject definitions describe structured content types and their entries. Read them before writing values — they tell you the key and the type a value must match.

Why the schema layer comes first

Attribute values are strings, but a metafield value is only valid when it matches the type its definition declares — single_line_text_field, a number, a reference, and so on — plus the definition's validations. An integration (or an assistant) that writes custom-field values without reading the definitions first is guessing at both key and type.

Metafield definitions

GET/api/v1/metafield-definitionspim:read

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

The list is bounded by the account, so the whole set is returned and next_cursor is always null. Narrow with owner_type (product, variant, or collection):

curl -s "https://api.peak-pim.com/api/v1/metafield-definitions?owner_type=product" \
  -H "Authorization: Bearer pk_live_..."

{"data": [
  {"id": "5f6a...", "namespace": "custom", "key": "care_instructions",
   "name": "Care instructions", "type": "single_line_text_field",
   "owner_type": "product",
   "validations": [], "position": null,
   "pending_publish": false, "last_publish_status": "published",
   "stores": [
     {"store_id": "a1b2...", "store_domain": "acme-us.myshopify.com",
      "pending_publish": false}
   ]}
], "next_cursor": null}

Field	Meaning
`namespace` / `key`	The identity a value is written under
`type`	Shopify's field type, e.g. `single_line_text_field`
`owner_type`	Which kind of entity carries this field
`validations`	`{name, value}` constraint pairs a value must satisfy
`position`	The merchant's manual display position, or null when never reordered
`stores`	The stores the definition exists on, with per-store name/description overrides and `pending_publish`

Definitions carry publish state like everything else — a definition itself can be pending_publish.

Metaobject definitions

GET/api/v1/metaobject-definitionspim:read

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

Each definition is a structured content type with its canonical field structure and its account-wide entry count:

{"id": "8b2c...", "type": "designer", "name": "Designer",
 "display_name_key": "name",
 "fields": [
   {"key": "name",    "name": "Name",    "type": "single_line_text_field", "required": true},
   {"key": "bio",     "name": "Bio",     "type": "multi_line_text_field",  "required": false},
   {"key": "website", "name": "Website", "type": "url",                    "required": false}
 ],
 "publishable": true, "entry_count": 14, "has_structure_conflict": false,
 "pending_publish": false, "last_publish_status": "published",
 "stores": [...]}

type is the Shopify definition type — the cross-store identity key.
display_name_key names the field whose value names an entry.
fields come in definition order, each with key, type, required, and optional validations.
publishable means entries can be draft or active.
has_structure_conflict flags that stores disagreed about the definition's structure as of the last import — worth surfacing before writing entries.

Entries

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

The structured content records under one definition, with their values and per-store publish state. An entry looks like any other entity: attributes, draft_revision, pending_publish, and a stores[] state array — plus its handle and its definition_id:

{"data": [
  {"id": "d41e...", "definition_id": "8b2c...", "handle": "jane-doe",
   "title": "Jane Doe",
   "attributes": [
     {"key": "name", "value": "Jane Doe", "type": "single_line_text_field"},
     {"key": "website", "value": "https://janedoe.example", "type": "url"}
   ],
   "draft_revision": 3, "pending_publish": false,
   "last_publish_status": "published", "stores": [...]}
], "next_cursor": null}

The MCP equivalents

The connector exposes the same schema layer, with the same read-before-write advice built into the tool descriptions:

Tool	Arguments	Answers
`list_metafield_definitions_v1`	`owner_type` optional ("Product", "Variant", or "Collection")	The custom-field definitions and how each is typed — read this before writing a metafield value
`list_metaobject_definitions_v1`	—	The structured-content types, each with field structure and entry count
`list_metaobject_entries_v1`	`definition_id` required; `page`, `page_size`, `search`	The records under one definition, with paging and free-text search over name and handle

A write-tier assistant should call list_metafield_definitions_v1 before writing a metafield value with update_master_attributes_v1 or update_projection_attributes_v1 — the definition supplies the key and the type the value must match.

Metafield definitions reference and metaobject definitions reference.
Translations & markets — product and collection translated values, plus regional catalog context.
Build an AI catalog operator — the read-schema-then-write pattern in an agent.