Shopify metafields: definitions, types and how to use them well

A metafield is a typed custom field attached to something in Shopify — a product, a variant, a collection, a customer, an order, the shop itself. It's how you store data the platform doesn't model natively, without resorting to the two bad old habits: cramming it into a description, or hiding it in tags.

Define before you populate

The most important habit. A metafield definition gives the field a name, a namespace, a key, a type and validation rules. Without a definition you can still store values through the API, but they won't appear in the admin, can't be validated, and can't be used for filtering.

Definitions live under Settings → Custom data, which is where beginners never think to look because it isn't on the product page.

Namespace and key form the identifier — specs.material, custom.care_instructions. Choose a namespace convention early and hold to it; a store with fields in four ad-hoc namespaces is unpleasant to work with.

The types

Metafields are typed, and using the right type matters more than it looks:

Storing a number as text because it was quicker is the decision you regret when you want to filter or sort by it.

Where they attach

Products, variants, collections, customers, orders, pages, blogs, articles, locations, markets and the shop. Two placements worth calling out:

• Variant metafields for data that genuinely differs per variant — a specific SKU's dimensions, a per-variant lead time.
• Shop metafields for store-wide configuration a theme reads, which is often cleaner than another theme setting.

Reading them

In Liquid:

``liquid {{ product.metafields.specs.material }} {{ product.metafields.specs.material.value }} {% if product.metafields.specs.care != blank %}…{% endif %} ``

Reference-type fields resolve to the referenced object, so a metaobject_reference gives you its fields directly. That's what makes metaobjects genuinely useful rather than just another field.

In GraphQL:

``graphql product(id: "gid://shopify/Product/123") { metafield(namespace: "specs", key: "material") { value type } } ``

Storefront API access requires the definition to be exposed to it — a checkbox on the definition, and the reason "the metafield exists but my headless front end can't see it" is such a common question.

Where metafields earn their place

• Filtering. Facts in typed fields can drive collection filtering. Facts in prose cannot.
• Consistent rendering. A spec table built from fields looks identical on every product.
• Surviving a redesign. Data in fields moves with you; data marked up inside a description has to be re-entered.
• Feeding Functions. A function can't call your API, so anything its logic depends on must be sitting in a metafield already. This is the architecture of most real Functions projects.
• Integrations. A clean place for an ERP to write data Shopify doesn't model.

Metafield or metaobject?

Metafield when you're adding an attribute to something that exists. Material on a product.

Metaobject when you're describing a thing that isn't a product but relates to several. A designer, a size guide, a store location, referenced from many products.

The test: does this repeat, and does more than one product point at it? If yes, model it once as a metaobject and reference it — metaobjects.

Modelling well

• Name for meaning, not layout. care_instructions, not tab_two_text. The data should survive a redesign.
• Use validation. Choice lists, min and max, required. It's the only thing standing between you and inconsistent data entered by four different people.
• Don't duplicate what Shopify already models. Weight, price and inventory have proper homes.
• Decide who writes it. If an integration owns a field, merchandisers shouldn't be editing it — ERP integration is largely a conversation about who owns which field.

Metafields take an hour to learn and are the difference between a catalogue you can filter, template and integrate, and one where every fact is trapped in a paragraph.