Shopify platform
Metafields
Metafields are custom fields that extend Shopify's built-in resources — products, variants, collections, customers, orders — with data the platform does not model natively. A typical use is a product's care instructions, size chart, or ingredient list. Metafields are typed, can be edited in the admin, and are readable from Liquid and the Storefront API.
Why it matters
Before metafields, structured product data had exactly one home: the description field. Care instructions, dimensions, warranty terms, and ingredient lists all went in as hand-formatted HTML, which meant none of it could be filtered, sorted, translated, or reused anywhere else. Change the layout and every product needs re-editing by hand.
Metafields separate what a product is from how it is shown. A "Fabric" metafield holds the word "linen"; the theme decides whether that surfaces as a spec row, a filter, or a badge. The same value can feed a Storefront API query, a Google Shopping feed, and a marketplace export without anyone retyping it.
For a merchandising team, that is the difference between editing four hundred product descriptions and editing one theme section.
How it works on Shopify
Metafields are declared in Settings → Custom data, where you choose the resource, a namespace and key, and a type. The type is the load-bearing decision: single line text, rich text, integer, dimension, file, or a reference pointing at another product, collection, or metaobject. Reference types are what turn flat data into relationships — a "Complementary products" metafield returns real product objects the theme can render, not a string of handles you have to parse.
Values are edited in the admin next to the product, so merchants never open theme code. Themes read them through Liquid. Headless storefronts read them through the Storefront API, but only when the definition has been explicitly marked as storefront-visible.
List types such as list.single_line_text and list.product_reference hold several values under one key, which is the correct shape for materials, certifications, or a curated set of related products.
Common mistakes
- Values without definitions. Metafields written by an app or straight through the API still exist, but they never appear in the admin, cannot be validated, and stay invisible in the theme editor. Define first, populate second.
- Text where a reference belongs. Storing a related product's handle as a string means a rename silently breaks the connection. A product reference cannot dangle.
- Forgetting storefront access. The classic headless bug: the field renders correctly in the theme editor and returns null over the API, because nobody ticked the box on the definition.
- Repeating one shared value across the catalogue. A size guide copied onto four hundred products is a metaobject nobody has created yet. Author it once, reference it everywhere.
- Defining on the variant when the value describes the product. Variant metafields multiply the editing work by the number of variants, and most merchandising teams stop filling them in by week two.
When you need help
Adding one metafield is admin work, and no agency should be charging for it. Designing the custom data model for a whole catalogue is not: deciding what belongs in a metafield, what belongs in a metaobject, and what belongs in a PIM determines how much manual work the merchandising team carries for the next three years.
The other job worth handing over is backfilling. Populating thousands of existing products through the Admin API or a bulk import, without corrupting live data or tripping rate limits, is where this goes wrong quietly. Migrating off an app that kept its data in its own tables is the same task with a deadline attached, because those values vanish when the app is uninstalled.
Need this done on your store?
Shopify developmentRelated terms
- MetaobjectsMetaobjects are custom content types you define in Shopify — an author, a store location, a size guide — that exist independently of products and can be referenced from anywhere. Where a metafield adds a field to an existing resource, a metaobject creates a new resource entirely. Together they let Shopify act as a lightweight CMS without a separate system.
- Storefront APIThe Storefront API is Shopify's public, customer-facing GraphQL API. It exposes products, collections, cart, and checkout to any frontend, and is safe to call from a browser because its access tokens are scoped to read-only storefront data. It is the interface every headless Shopify storefront is built on.
- Online Store 2.0Online Store 2.0 is the 2021 overhaul of Shopify's theme architecture. It introduced sections on every page (not just the homepage), JSON templates, app blocks that merchants can position without editing code, and a much richer metafields system. A theme built before OS 2.0 cannot use these features, which is a common reason to rebuild rather than patch.