Metafields

Metafields carry merchant-defined data — care instructions, size charts, ingredient lists — on products, variants, collections, pages, articles, blogs, and the shop itself. Imported Shopify metafields arrive automatically.

Querying

Select metafields on any entity that supports it:

query Product($handle: String!) {
  product(handle: $handle) {
    id
    title
    metafields {
      namespace
      key
      type
      value
    }
  }
}

value is JSON: a scalar for simple types, or a reference payload for *_reference types.

Rendering

Read by namespace + key and branch on type:

const care = product.metafields?.find((m) => m.namespace === "custom" && m.key === "care");
if (care?.type === "multi_line_text_field") {
  /* render the text */
}

References

file_reference, product_reference (and their list.* forms) resolve to the referenced entity — a file’s CDN URL, or the referenced product’s core fields — one level deep. Query the fields you render; deeply nested reference chains are intentionally not hydrated.