Every product has facts that a store’s default fields cannot hold. A rug has a pile height and a backing material. A phone case is compatible with certain models. A skincare product has an ingredients list and a shelf life. A supplier part has a code you need for ordering. Without a place for those facts, they end up crammed into descriptions, hidden in tags or kept in a spreadsheet nobody trusts.
Shopify’s answer is the metafield: a custom field attached to a resource, with a name, a type and a value. Used well, metafields make a catalogue consistent, searchable and ready for feeds, filters and automations. Used badly, they become a drawer of unlabelled data. This guide covers what to store, how to design the fields, when to choose something else and how to fill them at scale. Features evolve, so check Shopify’s current documentation for options and limits. For related work, see Shopify CSV import errors and product title formulas.
What a metafield is
A metafield has a namespace and key, a type and a value, and it belongs to a resource such as a product, variant, collection, customer or order. Defining the field in the admin gives it a name, a description and validation, and lets you edit it in a clear place rather than in raw form. Themes and apps can read the value and display it, and many feed and search tools use it.
| Part | Meaning | Example |
|---|---|---|
| Namespace | A grouping that avoids clashes | specs |
| Key | The field name within the namespace | material |
| Type | What kind of value it holds | Single line text, number with unit, date, URL, list, file, reference |
| Resource | What it attaches to | Product, variant, collection, customer, order |
| Validation | Rules for allowed values | Choices, minimum and maximum, length |
| Access | Who can see or use it | Storefront, admin only, apps |
What belongs in a metafield
- Specifications. Material, dimensions, weight with units, capacity, power, care instructions.
- Compatibility. Models, sizes or systems a product works with.
- Ingredients and certifications. Only values you can substantiate, with the certificate reference kept internally.
- Merchandising facts. Gender, season, occasion, style, used by filters.
- Content blocks. A short “what’s in the box” list or a size guide reference.
- Supplier data. Supplier SKU, lead time, minimum order. Keep admin-only.
- Compliance data. Country of origin, safety warnings and harmonised codes where relevant.
- Links. A manual, a video or a related product.
Choosing the right tool
| Need | Best fit | Why |
|---|---|---|
| The shopper chooses it (size, colour) | Variant options | It drives the variant selector and inventory |
| Simple filtering or grouping | Tags or collections | Fast to apply, but untyped |
| A structured fact about one product | Product metafield | Typed, validated, editable |
| A fact about one variant | Variant metafield | Different per size or colour |
| A reusable record shared across products | Metaobject | One brand, designer or size chart used on many products |
| Internal operational data | Admin-only metafield | Keeps it off the storefront |
| Customer or order notes | Customer or order metafield | Attached to the right resource |
A frequent mistake is to use tags for everything. Tags are quick, but they hold only text, have no validation and quickly become inconsistent: “Cotton”, “cotton” and “100% cotton” are three tags and three filters. A metafield with a list of allowed values is cleaner. Metaobjects fit data shared across products, such as brand pages or size charts, so you edit it once.
Design the fields properly
- List the questions shoppers ask and the facts feeds and marketplaces require.
- Group them by category. Rugs need pile height; mugs need capacity. Do not create one field list for all.
- Choose the narrowest type that fits: a number with unit for dimensions, a list for materials, a date for expiry.
- Use controlled values through validation or reference lists for anything that you will filter on.
- Name consistently. Use lowercase keys, a clear namespace and descriptions in the admin.
- Write the data dictionary: field, type, allowed values, example, who edits it and where it appears.
The data dictionary is the thing most stores skip and later regret. A three-column table in a shared document saves hours when a new person, or an automation, has to add products.
Display and use in the storefront
Modern themes can show metafield values in product pages through dynamic sources in the theme editor, without code. Custom layouts can use Liquid. Use them for specification tables, compatibility lists and care instructions, and also for structured data on the page. They can feed collection filters in the Search & Discovery app and product feeds through apps. Always check the live page after adding fields, on mobile as well as desktop.
Keep sensitive data private
Metafields can be exposed to the storefront or kept to the admin and apps. Cost prices, supplier details and internal notes should never be accessible to the public. Check each definition’s access settings and test by viewing the page source and, where relevant, the storefront API. Remember that anything you store may be seen by apps that you install, so review app permissions.
Fill them at scale
Filling metafields product by product does not scale. Options include import through CSV templates, Shopify’s bulk editor for some fields, apps built for metafield management and the Admin API for custom flows. The real challenge is the source data: supplier files with inconsistent units, free-text materials and missing values. A pipeline cleans and maps the source, validates each value against the definition and loads in batches with a log of what was changed.
| Step | What happens | Check |
|---|---|---|
| Collect | Gather supplier files and existing data | Identify the source of truth |
| Clean | Normalise units, case and spelling | Compare with controlled values |
| Enrich | Fill gaps with rules or AI drafts | Review AI-filled values |
| Map | Match source columns to metafield definitions | Spot-check each column |
| Validate | Type, range and allowed values | Reject bad rows |
| Load | Import in small batches | Test on a few products first |
| Verify | View the storefront and admin | Compare to the source |
Our AI product data enrichment, bulk product upload and catalogue automation services follow exactly this sequence. Where an AI model proposes missing values, a review step is essential, as explained in our review process guide.
Governance for custom data
Custom fields multiply quickly. Without a little governance, a store ends up with three fields for material, two spellings of the same value and nobody sure which is correct. Keep a short register of every metafield definition with its owner, its purpose and the places it is used, such as the theme, feeds and apps. Review it each quarter and retire fields that nothing reads. Restrict who can create definitions in the admin, so that new fields go through the same quick check. When you rename or delete a field, search your theme, apps and automations first, because a missing field often fails silently and simply leaves a gap on the page. A tidy schema makes every later project, from feeds to translations, faster and cheaper.
A worked example
A home-goods store has 1,800 products whose dimensions and materials live in descriptions. It defines five metafields for dimensions, material, care, country of origin and supplier SKU, and builds a pipeline to extract values from descriptions and supplier files. The extraction fills about 85 percent of values with confidence; the remaining 15 percent, 1,350 values, go to review at about 30 seconds each, roughly 11 hours. At $20 an hour, the whole data project costs about $220 in review time plus the build. The benefits are filters that shoppers use, cleaner Google Shopping attributes and fewer returns caused by wrong sizes. The figures are illustrative.
Mistakes to avoid
- Creating fields without definitions, so they are hard to find and edit.
- Inconsistent values that break filters.
- Mixing units such as inches and centimetres in the same field.
- Storing layout in data, like HTML in a text field, which becomes hard to maintain.
- Exposing internal data by mistake.
- Too many fields that no one maintains.
- No backup before a bulk update.
Sources and further reading
Figures and rules in this guide come from the primary pages below. Platform limits and prices change, so open the page before you build on a number.
- Shopify Help Center: metafields, defining and using metafields
- Shopify Help Center: metaobjects, reusable structured content
- Shopify Developer Docs: custom data, the API model for metafields and metaobjects