Peak PIMDevelopers

Operations

Metafield definitions

The custom fields an entity may carry, and how each one is typed. This is the schema layer: read it before writing metafield values, so your writes match the field's type and validations.

List metafield definitions

GET/api/v1/metafield-definitionspim:read

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

Query parameters

ParameterTypeDescription
owner_typeenumNarrow to one owner kind: product, variant, or collection. Any other value is rejected with 400 validation_failed.
 
curl "https://api.peak-pim.com/api/v1/metafield-definitions?owner_type=product" \
  -H "Authorization: Bearer $PEAK_PIM_KEY"

Response — 200

{
  "data": [
    {
      "id": "4f2b8d1c-7a9e-4c3b-9d5f-1e6a2c8b4d90",
      "namespace": "custom",
      "key": "care_instructions",
      "name": "Care instructions",
      "description": "Washing and drying guidance shown on the product page.",
      "type": "multi_line_text_field",
      "owner_type": "product",
      "validations": [],
      "position": 3,
      "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/MetafieldDefinition/23816765622",
          "name": "Care instructions",
          "description": "Washing and drying guidance shown on the product page.",
          "pending_publish": false
        }
      ]
    }
  ],
  "next_cursor": null
}

Get one metafield definition

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

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

The definition shape

FieldTypeDescription
iduuidThe definition's id in Peak PIM.
namespacestringThe metafield namespace.
keystringThe metafield key within its namespace.
namestringThe definition's display name.
descriptionstringThe definition's description, when set.
typestringShopify's field type, e.g. single_line_text_field.
owner_typestringWhich kind of entity carries this field.
validationsarrayEach validation is a {"name": …, "value": …} pair.
positioninteger or nullThe merchant's manual display position, or null when the definition has never been reordered.
pending_publishbooleanThe definition has unpublished changes.
last_publish_statusenumnever_published, pending, published, or failed.
storesarrayOne record per store the definition exists on — see below.

Each entry in stores records the definition's presence on one store:

FieldTypeDescription
store_id / store_domainuuid / stringWhich store this record belongs to.
shopify_gidstringThe definition's GID on that store.
name / descriptionstringThe store-local display name and description.
pending_publishbooleanUnpublished changes on this store's record.

Read the schema before writing values

Metafield values on entities travel as attributes. Before an integration writes one, it should confirm the field exists, what type Shopify expects, and which validations constrain the value — that is exactly what this list answers. Filter by owner_type to load only the schema for the entity kind you are writing.

Definitions can differ per store.

The top-level fields are the canonical definition; the stores array tells you where it actually exists. A definition missing from a store is not an error — it simply has no record for that store.

Notes