Shopify Product Metafields: The Two Types Explained

If you have spent time in Shopify's admin, you have probably encountered Shopify product metafields in at least three different contexts: a theme setting asking you to configure a spec table, an app describing what data it can fill, a help article about Google Shopping requirements. The word is the same in each case, but the systems are different.

Shopify has two distinct types of product metafields, and they work in fundamentally different ways. Understanding which type a tool, a theme, or a guide is referring to removes most of the confusion that merchants encounter when setting up Importier and wondering why their product spec table is still empty after running the AI pipeline.

What are custom product metafields?

Custom metafields are fields that merchants, app developers, or theme designers define themselves. They are not predefined by Shopify. A merchant who sells binoculars might create custom metafields for Magnification, Objective Lens Diameter, and Prism Type.

A theme might display those fields in a specification table on the product page. An app might read or write those fields for its own purposes.

Because custom metafields are user-defined, the field names, data types, and display logic are entirely up to whoever creates them. Two Shopify stores selling the same type of product could have completely different sets of custom metafields with no overlap. Shopify itself does not know what "Magnification" means as a business concept. It stores the value and makes it available to your theme and apps, but the semantic meaning belongs to whoever defined the field.

Custom metafields appear in Shopify under Settings > Custom data > Products. Every namespace and key combination is unique to the store that created it. They are typically used for:

• Product specification tables displayed by your theme
• App-specific data such as reviews, inventory metadata, or size guides
• Supplementary fields that Shopify's standard product schema does not include by default

What are category metafields?

Category metafields are different in every meaningful way. They are not defined by merchants. They are defined by Shopify as part of its Standard Product Taxonomy: a structured classification system aligned to Google's product taxonomy.

When you assign a product to a Shopify category (for example, "Apparel & Accessories > Clothing > Tops & T-Shirts > Polo Shirts"), a set of predefined attribute fields becomes available for that product. Those fields are the category metafields: attributes like Colour, Size, Material, Pattern, and Care Instructions, all standardised by Shopify and Google across every store in that category.

Unlike custom metafields, category metafields have the same meaning across every Shopify store in the same category. Google can read them as structured signals when evaluating Shopping eligibility. AI Shopping agents can compare products against each other using category metafields because the attribute fields are consistent across stores.

Shopify's category metafields system is the data layer that powers structured product discoverability outside your store. A category metafield answer to "what material is this polo shirt made from?" is machine-readable in a consistent format that Google and AI Shopping platforms understand. A custom metafield answer to the same question may be readable by your theme, but an AI agent that has never seen your store's schema has no reliable way to interpret it.

“

Custom metafields are yours to define. Category metafields are Shopify's and Google's. Importier fills the second type automatically, which is why merchants sometimes find their theme's spec table is still empty after running the AI pipeline.

The key distinction: who defines the schema

The most useful way to understand the difference is to ask who defines the field names and what they mean.

This distinction has a direct practical consequence: Google's product category taxonomy, which governs which attributes are available per product category, maps directly to Shopify's category metafield system. It does not map to custom metafields, which are invisible to Google's classification logic.

Which metafields does Importier fill?

Importier fills category metafields automatically. When the AI import wizard or a Store Scanner pass runs, it assigns your products to a Shopify taxonomy category and populates the corresponding category attributes. The 22 Industry Packs cover 3,758 attribute types, giving Importier the data to fill every field Shopify and Google use for product classification, including Material, Size, Colour, and their industry-specific equivalents.

Importier does not write to custom metafields in the standard import flow. Custom metafields are defined differently per store, so there is no general mechanism to fill them.

The fields your theme uses to display a spec table are custom metafields created by the theme designer for that specific theme. Importier cannot know what field names your theme expects, what data types are required, or what namespace and key combination the theme is reading from.

This is the source of the most common post-install question: "I ran a Store Scanner pass and the descriptions look great, but my product spec table is still empty." The spec table is reading custom metafields. Importier filled the category metafields. They are different fields in different systems.

Partially filling custom spec metafields with AI

There is a partial answer to the custom metafield gap. Importier's specification auto-fill feature, described in the Product Specifications Auto-Fill guide, lets you map up to three specification columns per import run to your store's existing custom metafield keys.

During the Review step of the import wizard, you map a Specification column to one of your custom metafield keys. The AI proposes values for each product by extracting what it can from the product title and other available data, then applies a confidence gate: it returns a blank when the information is not clearly present, rather than guessing. A product titled "8X42 ED Binocular" yields Magnification 8x and Objective Lens Diameter 42mm, but Prism Type stays blank because nothing in the title indicates it.

This feature is most useful for stores where the key specification values appear consistently in product titles and where three fields cover most of the customer-facing spec requirements. For stores with 10 or 15 custom metafield spec columns, multiple import passes targeting different field mappings is the practical approach.

For themes that use metafield-driven tab structures rather than heading-parsing, the theme tabs guide covers the full context including the Pattern B gap, which still requires manual entry or a dedicated metafield-writing app.

Setting up category metafields in Importier

Category metafields require a one-time configuration in Importier's settings. Once configured, they run automatically on every import cycle.

1. 01
   Go to Settings in your Importier admin and open the Category Metafields section
2. 02
   Enable the Industry Packs that match your product types (22 packs cover categories from fashion and electronics to food, supplements, and homeware)
3. 03
   Run the import wizard or a Store Scanner pass

   category metafields are assigned automatically for all products in scope, with no per-product review needed
4. 04
   Verify the result in Shopify admin by navigating to a product and scrolling to its Metafields section

   taxonomy attributes should now be populated
5. 05
   For custom spec metafields, use the Specification mapping in the Review step of the import wizard to map up to three columns to your existing custom metafield keys

Why the distinction matters for AI shopping

Category metafields have become the primary structured data layer for AI Shopping agents evaluating product comparisons. As AI shopping agents read your product data, they look for consistent attributes that allow cross-catalogue comparison. A category metafield for "Material: Cotton 200gsm" is legible to an agent comparing polo shirts across 40 stores. A custom metafield with the same value, stored under a namespace and key that exists only in your store, is not.

Shopify's developer documentation on metafields explains the technical architecture for both types in full. For merchants rather than developers, the practical summary is: category metafields are the ones that improve your product's discoverability outside your store, and Importier fills them automatically for every product that passes through the import wizard or a Store Scanner pass.

Data enrichment during import ensures the underlying product data (weight, HS codes, barcodes, and country of origin) is as complete as possible before category metafields are assigned, which improves the accuracy of the taxonomy match. Running data enrichment and category metafield assignment together in the same import pass is the standard workflow.

Key takeaways

• Custom metafields are defined by merchants, themes, or apps. Field names, data types, and meaning are specific to each store. Shopify stores them without interpreting their content.
• Category metafields are defined by Shopify's Standard Product Taxonomy, standardised across all stores, and aligned to Google's product taxonomy. They are used by Shopping algorithms and AI agents for structured product comparison.
• Importier fills category metafields automatically at import time via 22 Industry Packs covering 3,758 attribute types.
• Custom spec metafields can be partially filled via Importier's specification auto-fill feature: up to three custom metafield keys mapped per import run, with a confidence gate that returns blanks rather than guesses.
• If your theme's spec table is empty after an Importier run, your theme reads custom metafields, not category metafields. The fix is either the Custom Description style (for heading-parsing themes) or the specification auto-fill feature (for metafield-reading themes).