Metafields

How do Shopify metafields work?

A metafield has three parts: a namespace, a key and a value. The namespace and key form its address, such as custom.material, and the value is what the merchant types in. What makes a metafield useful is its definition. The definition sets the type, the validation rules, who can read it and where it appears in the admin.

You create definitions in Settings > Custom data, per resource: products, variants, collections, customers, orders, companies, locations, pages, blogs and more. Once a definition exists, the field appears on every record of that resource, and staff fill it in next to the title and price. No theme code is touched to add data.

The type is the decision that matters most. The main groups are:

• Text: single line, multi line and rich text.
• Numbers and measurements: integer, decimal, dimension, weight, volume and around 30 newer units such as temperature and voltage.
• Simple values: true or false, date, date and time, color, URL, money, rating and JSON.
• References: product, variant, collection, page, article, customer, company, file, metaobject and mixed references.
• Lists: most types also come as a list, such as list.single_line_text_field or list.product_reference.

References are what turn flat data into relationships. A "Pairs with" metafield of type list.product_reference returns real product objects, so a renamed product cannot break the link the way a pasted handle would.

On the storefront, themes read values in Liquid as product.metafields.custom.material.value. On Online Store 2.0 themes you can also connect a metafield to a section or block setting as a dynamic source, with no code. Headless storefronts read them through the Storefront API, but only after the definition's storefront access is switched on. That setting is off by default, whether the definition was made in the admin or through the API.

When should you use a metafield instead of something else?

Use a metafield when the data belongs to one record and differs from record to record: a fabric weight, a voltage, a supplier ID, a care code. If the same block of content repeats across many records, such as one size guide shared by 300 products, create it once as a metaobject and point a metafield reference at it.

Tags are for loose grouping and automation, not for values you filter, sort or display. Descriptions are for prose. Anything a shopper filters on or a feed exports belongs in a typed metafield.

If product data already lives in a PIM or ERP, that system stays the source of truth and metafields become the storage it writes to on Shopify.

What are the current metafield limits?

Shopify raised several limits in late 2025 and early 2026. As of October 2026:

• 256 definitions per resource type for the merchant, and another 256 per app. Shopify's standard definitions don't count.
• 50 pinned definitions per resource type.
• 64 KB per value for most types, 128 KB for JSON, and 2 KB for URL and ID values.
• 128 items in a list, or 1,024 for a list of metaobject references.
• 25 metafields per metafieldsSet call in the Admin API.
• 25 storefront filters per store in the Search & Discovery app. Metafield filters work with single line text, integer, decimal, true or false, and metaobject references.
• Liquid loops over a reference list return the first 50 items unless you paginate.
• Shopify Functions receive null for any value larger than 10,000 bytes.

There is no published cap on the number of records that carry metafields, so catalog size is rarely the constraint. Definition design is.

How do you set up a product metafield?

1. Go to Settings > Custom data > Products and select Add definition.
2. Name it, keep the custom namespace unless you have a reason not to, and pick the type. Choose a list type if a product can have more than one value.
3. Add validation: a minimum and maximum, a regex, or a fixed list of choices. Choices keep filter values clean.
4. Decide on storefront access and turn on capabilities you need, such as smart collection conditions or admin filtering.
5. Fill in values on a few products, then bulk-fill the rest with the bulk editor or a product CSV using columns named product.metafields.custom.key. Variant metafields can't be imported by CSV.
6. Connect the field in the theme editor as a dynamic source, or render it in Liquid.
7. If shoppers should filter by it, add it as a filter in Search & Discovery.

How do metafields affect SEO and filtering?

Metafields don't rank pages directly. They make the page content and markup better. Specs stored as typed fields can be rendered as a readable spec table and written into Product schema as material, size or GTIN properties, instead of being buried in a description Google has to parse.

They also drive filtered collection pages. Clean, validated values produce useful filters. Free-text values produce "Linen", "linen" and "Linen " as three separate options.

Category metafields are a newer layer. When a product is given a category from Shopify's Standard Product Taxonomy, Shopify suggests attributes such as color, fabric or size in the shopify namespace. They can be linked to variant options and used as filters, so it is worth using them before inventing your own field for the same attribute.

What does this look like on a real store?

On Ästhetik, a North Carolina textile house we moved from Magento to Shopify, each fabric's specs, such as weight, rub count and width, are typed product fields rather than text in the description. The same fields fill the spec tiles on every fabric page and power the catalogue filters for colour, fiber, fabric family and end use across more than 200 patterns.

On VIGO, a Shopify Plus B2B kitchen and bath store with more than 12,000 products, the work at that size is deciding which fields shoppers see, which feed filters and comparisons, and which only exist for integrations.

What are the common metafield mistakes?

• Writing values without a definition. Apps and API scripts can create undefined metafields that never show in the admin and can't be validated.
• Storing a handle as text where a reference type belongs.
• Copying one shared block of content onto hundreds of products instead of using a metaobject.
• Putting product-level data on variants, which multiplies the editing work.
• Forgetting storefront access, so a headless build gets null back.
• Skipping validation, then cleaning up inconsistent filter values by hand.

Do you need a developer for metafields?

Adding a single field is admin work. Planning the data model for a whole catalog, writing imports from an ERP or PIM, and backfilling thousands of products without hitting API limits is development work. That is the part our Shopify development team usually takes on, often as part of a Shopify Plus migration.