Shopify Category Metafields: What They Are and How to Fill Them

Shopify category metafields are product attributes, such as color, fabric, size or neckline, that come with the category you choose from Shopify's Standard Product Taxonomy. Set a product's Category in Shopify admin and a Category metafields section appears, with some fields added automatically and others suggested.

Each value is a shared metaobject entry, so "Black" is created once and used by every product that needs it. You fill category metafields on the product page, in bulk with the bulk editor or a product CSV, and they power variant options, color swatches, storefront filters and reports.

What are category metafields in Shopify?

Shopify's category metafields guide describes them as metafields linked to categories in the Standard Product Taxonomy, where they're called product attributes. In Shopify's examples, the category Apparel & Accessories > Clothing > Clothing Tops > Shirts offers fields such as size, neckline, sleeve length type, fabric and color. A clock or a sofa gets a different set.

Three things set them apart from the metafields you create yourself:

• They come with the category. Shopify adds some category metafields by default based on AI predictions and suggests others, which you can choose to add.
• They come with values. Each field has default entries, such as orange, red and black for color, that you can keep, edit or add to. Shopify's custom data glossary calls these default entries.
• Their values are shared. Renaming an entry, for example from black to graphite, updates it everywhere it's used.

What is Shopify's Standard Product Taxonomy?

Shopify's product taxonomy guide and glossary describe it as a predefined, standardized list of product categories, attributes and attribute values. Shopify publishes it as an open-source project under the MIT license, covering more than 25 verticals, with versioned releases you can browse in the taxonomy explorer.

What does the Shopify product category do?

Each product can have only one category, and Shopify says all products should have one. Without it, the product saves as uncategorized, which can also happen when products are created by CSV or an app. When you enter a name, description and images, Shopify generates an AI-powered category suggestion that you can accept or replace.

The category does more than unlock attributes. According to Shopify's taxonomy guide, it:

• sets the tax rate when you use Shopify Tax, so a wrong category can mean collecting too much or too little sales tax;
• helps sync products to channels that need a standardized product type, such as Google and Facebook;
• works as a collection condition and a product list filter;
• decides which return reasons customers see in the returns process.

What's the difference between product category and product type?

Keep using product type for your own groupings. The category is the standardized field that Shopify, its tax engine and sales channels read.

How do category metafields link to metaobject entries?

A category metafield value isn't free text. Each value is an entry, and entries are metaobject entries, which is why they also show up in Content > Metaobjects. Shopify's add category metafields guide says you can edit entries on the product page or in Content > Metaobjects, that a new entry becomes available to every product connected to that metafield, and that editing an entry updates it everywhere it's connected.

A color entry pairs the name your customers see, such as "Graphite", with a base value from the taxonomy. Shopify's glossary describes a base value, such as base color or base pattern, as a field of a standard metaobject entry. Base values are what let storefront filters group similar shades: Shopify's Search & Discovery filters guide says automatic grouping puts values under their taxonomy base value, and the September 2024 announcement gives the example of powder blue and navy blue both appearing under a "Blue" filter option.

Behind the scenes, Shopify's CSV guide treats category metafields as product metafields in the shopify namespace, such as product.metafields.shopify.fabric, and the metaobject query docs query color entries of the shopify--color-pattern type by taxonomy value. Check the exact namespaces, keys and types in your own store before you write CSV headers or code against them.

What's the difference between category and custom metafields?

Custom metafields are covered in our plain-English guide to Shopify metafields. Use category metafields first when the attribute exists in the taxonomy, and your own metafield for anything the taxonomy doesn't describe, such as care instructions or a designer's note.

Standard metafield definitions are a third, separate thing. Shopify's list of standard definitions describes them as preset templates with reserved namespaces and keys, such as descriptors.subtitle for a product subtitle or descriptors.care_guide for a care guide. You add them yourself, like a custom definition, rather than getting them from a product category.

Can you create your own category metafields?

Not as new taxonomy attributes: Shopify lists custom attributes as unsupported. You can, however, assign your own product metafield to one or more categories, and it then appears in the category metafields card for products in those categories. Shopify's add category metafields guide gives these steps:

1. Go to Settings > Metafields and metaobjects (some Shopify guides still call it Custom data) and click Products.
2. Create a product metafield definition, or open an existing one.
3. In the Category assignments card, click Assign categories.
4. Select one or more categories, click Done, then click Save.

Developers do the same with conditional metafield definitions, which limit a product definition to listed category IDs. Shopify's examples list child categories by their own IDs, so test which subcategories a constraint covers.

How do you fill in category metafields on a product?

These steps follow Shopify's guides as of October 2026:

1. From your Shopify admin, go to Products and open a product, or add a new one.
2. In the Category section, search for the category or click through its levels, then select the most accurate result. Choose by the product's main function: Shopify's example is a clock with a light, which belongs under alarm clocks.
3. In the Category metafields section, click a field, then select an existing entry, add a new entry or edit one.
4. Click Save.

The Shopify mobile app follows the same flow. Shopify's add category metafields guide says any unedited suggestions are confirmed when you save the product, so review the fields Shopify added and suggested before you click Save, and add only the suggestions you'll actually fill.

To edit an entry for every product at once, go to Content > Metaobjects, click the definition name, click the entry, change its fields and click Save.

What happens when you change a product's category?

Shopify's taxonomy guide says your data is kept: category metafields that have values, or that are connected to variant options, are assigned to the new category. Empty category metafields that aren't connected to options aren't carried over. Two side effects deserve a check before you change a published product: Shopify warns that new categories might not be compatible with every sales channel, and the category sets the tax rate when you use Shopify Tax.

How do you fill in category metafields in bulk?

How do you use the bulk editor for category metafields?

1. In Products, filter the list so your selection shares one category, then select the products.
2. Click Bulk edit, as Shopify's bulk editing guide names it. Some Shopify guides still call this button Edit products.
3. Click Columns and add Product category if it's hidden. Set the category for each product and click Save.
4. Open Columns again and add the metafield columns you want to fill. Shopify's metafield bulk editing guide covers product and variant metafields but doesn't single out category metafields, so check which category fields your admin offers as columns.
5. Fill the values, click Save, and open a few product pages to check the result.

Set and save categories before filling attributes, because the available fields depend on the category. If you need a new entry, such as a new color, create it on one product or in Content > Metaobjects first, so it exists before you apply it to many products. Our Shopify bulk editor guide covers the rest of the workflow, including the limits that apply to large edits.

If saving fails with "Update the invalid values, then save again", a selected product or variant has an invalid value. Shopify's bulk editing guide names a missing required SKU and metafield validation errors as causes. Our guide to fixing metafield validation errors shows how to find it.

How do you fill category metafields with a product CSV?

Shopify's CSV guide and taxonomy guide support three things category metafields need:

• Product category column. Enter either the category ID, such as hg-3-17-1, or the full breadcrumb, such as Home & Garden > Decor > Clocks > Alarm Clocks, but not both. If the breadcrumb isn't available in your language, use the English one or the ID.
• Metafield columns. Headers follow the format Name (product.metafields.namespace.key), and Shopify's own example is Fabric (product.metafields.shopify.fabric). Metaobject reference values are written as entry handles or GIDs, not display names, and list values are separated by semicolons.
• Variant options linked to a category metafield. The Option1 LinkedTo column takes product.metafields.shopify. followed by the attribute's key, and Option1 value then takes the entry's handle or GID rather than its display name.

Variant metafields aren't supported in product CSV files, so edit those in the bulk editor. A reliable way to get the format right is to fill one product by hand, export it and copy its headers and handles. When you import with Overwrite products with matching handles, a blank cell in an included column clears the saved value, so follow our product CSV update checklist first.

Which method should you use?

Where does Shopify use category metafields?

How do you use category metafields for variants and swatches?

Shopify's variants with metafields guide lets you build options from a category metafield:

1. On the product, in Variants, click + Add options like size or color.
2. Select the category metafield. Its entries fill in as option values, and you can add more.
3. Click Save.

To convert an option you already have, click the dynamic source icon on that option and connect the metafield. Shopify's mobile steps warn that existing values are cleared when you connect, so note them first. Once connected, adding one new color to a product with three sizes creates the three new variants at once. To undo it, click Edit next to the option, click the metafield name, then Disconnect and Save; the option becomes a custom option again.

Connected color entries can show as swatches. Shopify's swatch tutorial says swatches work only with variants connected to a color category metafield, such as Color, Frame color or Upholstery color, and only on themes that support them; Shopify's taxonomy guide adds that Dawn needs its latest version. If your product page has a Variant picker block, swatches should show by default. To change their shape, go to Online Store, click Edit theme, open the product, click the Variant picker block and choose Circle, Square or None. Other themes may label these settings differently, and vintage themes may not support swatches without code edits. Linked options still count toward Shopify's variant limits, which our Shopify variant limit guide explains.

Can you filter products by category metafields?

Since 25 September 2024, products categorized in the Standard Product Taxonomy can use category metafields as storefront filters in the Search & Discovery app. Shopify's filters guide gives the route:

1. Go to Apps > Search & Discovery and click Filters.
2. Click Add filter, open Source and choose Category metafield, then the attribute, such as Color.
3. For colors, select Include swatch and, optionally, Use images when available.
4. Rename, group or sort values if you need to, then click Save.

The Multicolor entry has no hex code, so upload an image to its entry if you want a swatch for it. Search & Discovery allows 25 filters per store and shows up to 100 values per filter, and collections with more than 5,000 products don't show filters. To check that your theme supports filters, go to Content > Menus: an unsupported theme shows a message in the filters section.

Shopify's taxonomy guide and add category metafields guide still say attributes aren't supported in Search & Discovery, so preview a new filter on your storefront after you save it.

What about collections, reports and returns?

• Collections: Shopify's collections guide says a category metafield condition can narrow a collection to specific variants, such as only red ones, when that metafield is connected to a variant option.
• Reports: since a 28 September 2026 update, category metafields such as color, material and fit are dimensions and filters in Reports, Explore and the query editor, with nothing to turn on. A product with several values for one attribute stays on one row, so sales aren't counted twice.
• Returns: Shopify's taxonomy guide says return reasons are based on the product category, so an accurate category gives you cleaner return data.

Do Google and other sales channels read category metafields?

Shopify says categories help you sell on channels that need a standardized product type, such as Google and Facebook. The Shopify category isn't the whole feed, though:

• Shopify's Google & YouTube channel requirements recommend adding a Google Product Category; without one, Google assigns a category itself and you might see errors. Apparel might also need age group, gender, color and size before it's published, and the page doesn't say whether these values are read from category metafields, so check product status in the channel.
• Product CSVs have a separate Google Shopping / Google Product Category column that uses Google's taxonomy.
• For checkout directly on Instagram or Facebook, Shopify says Google Product Categories are required for tax reasons, even with a Shopify category set.

What are the limitations of category metafields?

Shopify's taxonomy guide lists these, as of October 2026:

• Custom attributes aren't supported. Assign your own metafield definitions to categories instead.
• Unit of measurement and dimension type attributes aren't currently available.
• Attributes aren't supported in Shopify Bundles. The same list names Search & Discovery, which conflicts with Shopify's filters guide and changelog, so test filters in your store.
• Swatches on Dawn need the latest theme version.
• New categories might not be compatible with every sales channel.

How do you fix common category metafield problems?

How do you keep category data clean?

Filters, swatches and reports all read the same entries, so decide which attributes each category needs, fill them before publishing and recheck after big imports. Our Shopify metafield audit checklist gives a routine for spotting blank and mismatched values. ShopOpsy is also building Metafield Error Scanner, an app to scan a catalog for missing, empty or invalid metafield values; it isn't available yet.

Frequently asked questions

Do I have to fill in category metafields?

No. Shopify says every product should have a category, but its guides don't make filling category metafields mandatory. You need them for the features that read them, such as linked variant options, swatches, category filters and attribute reports, and channels may ask for some of the same details, such as color and size for apparel on Google.

Do category metafields help SEO?

Shopify's category metafields guide says they make products more discoverable on your site, on marketplaces and on search engines. Treat them as structured product data, not a ranking switch: titles, descriptions and page content still do most of the work.

Can apps and developers set category metafields?

Yes, through the GraphQL Admin API or a product CSV. Shopify's guide to linking metafields to product options shows how an app sets a product's category and links an option to a metaobject reference list metafield, which needs the write_products and write_metaobjects scopes. Its examples use a custom metafield rather than a category one, and an entry must exist before an option can link to it.

Sources

• Category metafields — Shopify Help Center, accessed 26 October 2026.
• Add category metafields — Shopify Help Center, accessed 26 October 2026.
• Adding color swatches using category metafields — Shopify Help Center, accessed 26 October 2026.
• Shopify's Standard Product Taxonomy — Shopify Help Center, accessed 26 October 2026.
• Custom data terminology — Shopify Help Center, accessed 26 October 2026.
• Adding variants with metafields — Shopify Help Center, accessed 26 October 2026.
• Using CSV files to import and export products — Shopify Help Center, accessed 26 October 2026.
• Editing metafields in bulk — Shopify Help Center, accessed 26 October 2026.
• Bulk editing — Shopify Help Center, accessed 26 October 2026.
• Metafield definitions — Shopify Help Center, accessed 26 October 2026.
• Search & Discovery filters — Shopify Help Center, accessed 26 October 2026.
• Creating collections with metafields — Shopify Help Center, accessed 26 October 2026.
• Google & YouTube channel requirements — Shopify Help Center, accessed 26 October 2026.
• Storefront filters now support category metafields — Shopify Changelog, accessed 26 October 2026.
• Now link product metafields to product options — Shopify Changelog, accessed 26 October 2026.
• Category metafields are now available in Analytics — Shopify Changelog, accessed 26 October 2026.
• List of standard metafield definitions — Shopify developer documentation, accessed 26 October 2026.
• Conditional metafield definitions — Shopify developer documentation, accessed 26 October 2026.
• Link metafields to product options — Shopify developer documentation, accessed 26 October 2026.
• Query metaobjects — Shopify developer documentation, accessed 26 October 2026.
• Shopify product taxonomy — Shopify on GitHub, accessed 26 October 2026.