What are Shopify metafield definitions?

Updated August 2026

“Metafield” and “metafield definition” get used interchangeably by merchants, and that mix-up is behind most of the Shopify Community threads that start with “why can’t I see this field in my bulk editor” or “why did my app’s data disappear from the product page.” They’re two different things, and once you can tell them apart, most of the confusion around custom product data goes away. This guide covers what a definition actually is, how it differs from the metafield value itself, and how to set one up and populate it across your catalog without writing a line of GraphQL.

Already have a definition and just need to fill it in? SureEdit bulk-populates metafield values across your catalog on its free plan (up to 50 products per edit), with a before → after preview and one-click undo. Jump to the bulk-populating section below.

Metafields vs. metafield definitions

A metafield is a single piece of custom data attached to something in Shopify, most often a product: a value, saved under a namespace and a key, such as custom.care_guide holding the text “Machine wash cold.” That value exists whether or not Shopify’s admin knows anything about it. Any app, any CSV import, any custom storefront can write one.

A metafield definition is different: it’s the schema. Created in Settings → Custom data, a definition registers a namespace and key ahead of time and declares its type (text, number, date, and so on), and optionally validation rules like a minimum, a maximum, or a fixed list of allowed values. Once a definition exists, every metafield saved under that namespace and key has to match it.

Think of the definition as the column heading in a database table, and the metafield as the value in one row. You can have values with no column heading, an “unstructured” metafield, still fully functional, but you can’t see or safely bulk-edit them in Shopify’s own admin until a matching definition exists.

Why an undefined metafield doesn’t show up in the admin

Plenty of Shopify apps, from review platforms to size-chart builders to your own custom storefront, write metafields through the API without ever registering a definition. Those values are completely real: your theme can pull them with Liquid’s product.metafields.namespace.key, and the Admin API can read and write them by namespace and key any time.

What they don’t get is admin visibility. Open a product page in Products and only fields with a matching definition show up in the Metafields section. Select some products, choose Bulk edit, then Columns, and the same rule applies: only defined metafields are offered as columns. An unstructured metafield can sit on 400 products, working correctly in your theme, and stay completely invisible to a merchant clicking around the admin looking for it.

If you need to see or bulk-edit a value like that, the fix is one of two things: create a definition that matches its exact namespace, key, and type, or use a tool that addresses metafields directly by namespace and key without one.

Standard definitions vs. custom definitions

When you create a definition (Settings → Custom data → Products → Add definition), Shopify offers two starting points.

Standard definitions are a curated library Shopify maintains and keeps mapped to specific namespaces and keys: things like color, fabric, or garment care instructions. Sales channels and apps that support them, the Google & YouTube channel is the common example, read these automatically for product feeds, without you having to configure any mapping. If a standard definition exists for what you’re storing, use it: you get the mapping for free and avoid inventing your own namespace for something Shopify already has a home for.

Custom definitions are ones you build from scratch: your own namespace (commonly custom, or a namespace reserved for a specific app), your own key, your own type. Use these for anything specific to your catalog that Shopify hasn’t standardized, an internal SKU cross-reference, a supplier code, a promotional badge flag.

Check the standard library before creating a custom one. It’s a five-minute look, and retrofitting a custom field into a standard one later means creating a second definition and migrating every value across.

Choosing a type, and why it’s hard to change later

Every definition locks in a type at creation: single line text, multi-line text, integer, decimal, true/false, date, date and time, URL, JSON, a file or product reference, and list versions of most of these (a list of single-line text values, for instance).

The type is a validation rule as much as a storage format. A boolean definition rejects “yes.” A number definition rejects “approx. 12.” A date definition rejects “next Tuesday.” That rejection happens per value, which is exactly why a bulk write into the wrong type produces partial failures instead of one clean error at the top.

Shopify does not let you change a definition’s type once it’s created. Pick decimal when you meant integer, or single-line text when you needed a list, and the fix is creating a new definition with the right type and moving every value across by hand or with a bulk tool, not flipping a setting. It’s worth the extra thirty seconds to check the type against how your theme or app actually reads the field before you save the definition, not after you’ve populated 300 products with it.

Namespace and key basics

The namespace groups related keys and, more importantly, controls who’s allowed to write to them. custom is the open namespace merchants reach for by default. Apps typically write into a namespace reserved for that app, which only the app can write to, even though anyone can read it.

Within a namespace, the key is the specific field: custom.care_guide, custom.fabric_content, custom.badge_text. Two definitions can’t share the same namespace and key on the same resource type (product-level, in this guide), so pick keys as deliberately as you’d pick column names in a spreadsheet you plan to keep for years.

The most common namespace mistake isn’t choosing the wrong one, it’s a typo that creates a second one. custom.care_guide and custom.care_guides look almost identical, and Shopify treats them as two completely unrelated fields: writing to the typo’d version doesn’t error, it just silently creates a second, invisible field while your theme keeps rendering the original. Our guide to bulk editing product metafields covers that trap in more detail.

Bulk-populating a definition across your catalog

Once a definition exists, there are three ways to fill it in at scale.

• Shopify’s admin bulk editor. Select products, choose Bulk edit, then Columns, and add the metafield column to type values in cell by cell. Fine for a handful of products, slow past that, because every value is entered by hand with no find and replace.
• A CSV import. Add a column named Metafield: namespace.key [type] to a product export and re-import it. Works well for a one-off migration where the values already live in a spreadsheet; per-row failures land in a results email after the fact, with no preview and no undo. Our guide to importing metafields with a CSV covers the exact column format.
• A bulk-edit tool that sets the value once and applies it to every product matching a filter, with a before → after preview and verification that each write actually landed. That’s the workflow covered in our guide to bulk editing product metafields.

Manual namespace and key edits when there’s no definition yet

Sometimes you need to write a value before a definition exists, most often when the namespace belongs to an app you don’t own and Settings → Custom data won’t let you register it. Some bulk-edit tools support this: you enter the namespace, key, and type by hand instead of picking from a definitions list.

The risk is guessing the type wrong. If an app already created custom.spec_json as JSON and you manually write it as single-line text, you either get rejected or, worse, create a parallel value that doesn’t match what the app expects. When you own the namespace, creating the definition first is almost always the safer path: it gives you validation and admin visibility for free.

Common mistakes

• Type mismatches. A batch of values that doesn’t match the definition’s type fails per product, not all at once, so a run of 200 can quietly save 180 and reject 20.
• Wrong namespace or key. A typo creates a second, invisible field instead of erroring. Check what your theme actually reads (view the theme code, or ask whoever built it) before assuming a namespace is correct.
• Orphaned values after deleting a definition. Deleting a definition offers you a choice: delete the underlying values too, or leave them behind. Leave them behind and you’ve recreated the exact “invisible field” problem this guide started with, just self-inflicted.

Doing this with SureEdit

Creating the definition itself still happens in Shopify’s own admin, under Settings, then Custom data, then Products. SureEdit doesn’t create definitions for you. Where it helps is everything after that: SureEdit lists your store’s existing metafield definitions so you can pick one instead of retyping a namespace and key, or accepts a manual namespace, key, and type for fields that don’t have a definition yet. Either way, you filter to the exact products and preview every before → after value before the write runs. Each value is then re-read from Shopify to confirm it actually saved, anything rejected is itemized with the reason, and the original values are journaled so a bad bulk write is one click to undo. It’s free on the free plan, up to 50 products per edit, metafields included.

FAQ

Do I need a metafield definition before I can bulk edit metafields?
Not strictly. Some bulk-edit tools, including SureEdit, support writing through an existing definition or manually by namespace, key, and type. A definition just gives you validation and admin-UI visibility that a manual namespace and key write doesn’t provide.

Can I create a new metafield definition and populate it in bulk at the same time?
They’re two separate steps. You create the definition once in Shopify’s admin, under Settings, then Custom data, then Products. Once it’s saved, it’s available immediately: pick it from your definitions list and apply a value across every product in your filtered set in one bulk edit.

What happens to a metafield’s values if I delete its definition?
Shopify asks whether to delete the underlying values too. If you choose to keep them, they stay attached to every product and keep rendering wherever your theme reads them directly, but they become invisible and uneditable in the admin again, the same undefined-metafield problem this guide describes, just self-inflicted.