Every non-trivial Shopify app eventually needs the Shopify metafields API — for custom product specifications, loyalty points on customers, supplier data on variants, or fulfilment metadata on orders. This guide covers the full architecture: metafield structure, owners, types, reading and writing via GraphQL Admin API, building Metaobjects for complex schemas, and exposing metafields to the Storefront API for headless storefronts.

Shopify metafields API — metafield structure, resource owners, Metaobjects and Storefront API exposure by CodeAtoZ

Every Shopify metafields API entry has four required fields: namespace (groups your metafields, e.g. my_app), key (the field name within the namespace), value (the stored data), and type (the value format — single_line_text_field, json, boolean, integer, file_reference, and 15+ more). Metafields can be attached to seven resource owners: Product, ProductVariant, Customer, Order, Collection, Blog, and Page. The namespace must match your app’s allowed namespace list — apps are restricted to their own namespaces to prevent data conflicts. Refer to the Shopify metafields API reference for the full type list.

metafieldsSet(metafields: [{
  ownerId: "gid://shopify/Product/1234567890"
  namespace: "my_app"
  key: "supplier_code"
  value: "SUP-UK-001"
  type: "single_line_text_field"
}]) {
  metafields { id namespace key value }
  userErrors { field message }
}

Reading the Shopify metafields API via GraphQL Admin API uses the metafield(namespace, key) field on any supported resource. For multiple metafields, use metafields(identifiers: [...]) to batch reads in a single query — never loop individual queries for each metafield on a list page. On the Storefront API, metafields must be explicitly exposed before they appear in queries.

query GetProductMetafields($id: ID!) {
  product(id: $id) {
    title
    supplier: metafield(namespace: "my_app", key: "supplier_code") { value }
    certifications: metafield(namespace: "my_app", key: "certifications") { value }
    # Batch multiple fields in one query:
    metafields(identifiers: [
      {namespace: "my_app", key: "care_instructions"},
      {namespace: "my_app", key: "country_of_origin"}
    ]) { namespace key value type }
  }
}

Metaobjects extend the Shopify metafields API to support structured, repeatable schemas — think of them as custom content types. Define a Metaobject definition with named fields and types (e.g. a specification_table type with label, value, and unit fields), then create entries and reference them from product metafields as a metaobject_reference. This replaces the fragile JSON-blob pattern where structured data was jammed into a single json metafield. The Shopify Metaobjects documentation covers definition creation and entry management via GraphQL.

Metaobjects are also directly queryable via the Storefront API, making them ideal for headless storefronts that need rich structured product content — spec tables, size guides, material certifications, or any repeatable content block. Our Shopify development team uses Metaobjects extensively for complex product data architectures. See our Shopify custom app development guide for how metafields fit into the wider app architecture. For Storefront API access, check the Shopify Storefront API documentation.