Shopify metafields: definitions, types and how to manage them

Metafields are key-value pairs that add custom data to a Shopify resource. Products are the most common owner, but variants, collections, customers, orders and the shop itself can carry metafields too. Every metafield has the four parts in the table below. Together, the namespace and key form its identifier, so custom.material on a product is a different field from specs.material.

Merchants usually work in the custom namespace, which Shopify suggests when you create a field in the admin. Apps use their own namespaces, and Shopify reserves an app-owned namespace ($app in the API) for data that belongs to one app. See the metafields overview on shopify.dev for the full model.

A metafield definition is the schema: name, namespace and key, type, optional description and validation rules. The value is the data stored on one product. Shopify's own advice is to create the definition first, because the definition is what turns a metafield into a field in the product page of the admin, enforces validation, and lets you use it in smart collections, admin filters and, when your theme supports dynamic sources, the theme editor.

A value can exist without a definition. The Admin API accepts it as long as you send the type, which it requires when no definition exists for that namespace, key and owner type. Those values are stored, but nobody sees a typed input for them in the admin. If you later add a definition with the same namespace, key and type, you can migrate the existing values to it, and values that fail the new validation rules can then be fixed.

The type decides what a value may contain and how themes and apps read it. Shopify groups the types roughly as in the table. Most basic and all reference types also exist as a list, such as list.single_line_text_field, except boolean, id, json, language, money, multi_line_text_field and rich_text_field. The full, current list is on the metafield data types page.

Shopify's standard product taxonomy gives each product one category, separate from the free-text product type. The category powers category metafields: attributes that belong to that category, such as size, neckline and color for shirts. Their values are metaobject entries with default values that link to Shopify's standardized values, and you can rename an entry (black to graphite, for example) or link a field to a variant option so one edit updates everywhere.

You set the category on the product page, where the Category metafields section then shows the fields for that category, or in bulk through the bulk editor or a CSV with the category ID or breadcrumb. When you change a category, metafields that have a value or a variant link carry over and empty ones do not. Shopify documents this on its product category page.

One product at a time, the product page in the admin is enough. For a catalog, you need one of the bulk routes below. Each has its own rules, so check them before you change hundreds of products. For the bulk routes in more depth, see how to bulk edit Shopify products.

Limits rarely bite on day one, but they shape how you design fields for a growing catalog. Every app and every team that adds its own definitions draws from the same allowance per resource type. The figures below come from Shopify's metafield limits and the MetafieldsSetInput reference; check them again before a large build, because Shopify adjusts them.

When product data lives in a PIM, the PIM becomes the place where you edit specs, and the Shopify connection writes them to metafields. That keeps one source for the values your webshop, feeds and marketplaces share. The part to get right is the split of work: the PIM writes values, and the definitions that make those values visible in Shopify are set up in Shopify.

WISEPIM's Shopify PIM connection writes metafield values with metafieldsSet. By default it writes wisepim.ean, wisepim.mpn and wisepim.country_of_origin, wisepim.cost as number_decimal and wisepim.short_description as multi_line_text_field. Brand goes to Shopify's native vendor field, not a metafield. Product FAQs, when you use them, go to wisepim.faqs and wisepim.faq_schema as json.

Any attribute you enable for Shopify in attribute management is written too: under the wisepim namespace with a key derived from the attribute code, or back to its original namespace, key and type when the attribute came from an imported Shopify metafield definition. Per-connection field mappings can switch an entry off or fill it from another attribute, a fixed value or a template, and a value that does not fit its type is skipped rather than sent.