Merchants: Shopify Product Metafields, Definitions, Validation, CSV/API

Shopify product metafields let you attach structured, reusable custom fields (dimensions, care, warranty, references) to products so you can display and manage additional product data without editing theme code. Open Settings > Custom data in your Shopify admin, choose Products, and add your first definition to see how it works.

TL;DR:

• Choose a standard Shopify definition when available, then set the content type and validation limits before adding values; later type changes can invalidate existing data.
• Use a metaobject for related content that repeats, such as a specifications table; products can reference one shared block across the catalog.
• Use the Bulk Editor for variant metafields, because CSV imports support most types but have limitations for variant level fields.
• To display a value on product pages, enable storefront access and connect the metafield to a compatible Theme Editor block through its dynamic source control.
• Create merchant owned fields in admin for values your team edits, and leave app owned namespaces to their apps to avoid disrupting syncs.

What metafields and metaobjects are, with practical examples

A metafield is a single key-value pair attached to a resource such as a product, variant or collection. Each one has a namespace and key (together written as namespace.key) plus a defined type, such as text, number or date. According to Shopify’s documentation, valid metafield data spans text, numbers, dates, files like images, measurements and references to other Shopify resources such as products or pages. A warranty length, a care instruction or a product’s country of origin all fit neatly into this format.

Metaobjects work differently. Rather than one value per field, a metaobject bundles several fields into a reusable structure, and Shopify’s metaobjects documentation describes them as multi-field content blocks, such as product highlights or an ingredient table, that a metafield can then reference. You build the metaobject definition once, populate as many entries as you need, and link them wherever relevant.

The choice between the two usually comes down to structure:

• Use a metafield when a product needs one discrete value, such as a single warranty period or a material composition string.
• Use a metaobject when the content has several related fields that repeat together, such as a size chart row with measurement, fit and stock status.
• Use a metafield that references a metaobject when you want a product to pull in a shared, reusable block, such as a brand story or a certification badge used across many products.

Getting this distinction right early saves a lot of rework later, particularly once you start scaling a catalogue across multiple collections or markets.

Metafield types, allowed values and validation rules

Shopify groups metafield content types into several families, and knowing which one fits your data avoids a lot of trial and error. The metafield types reference documents categories including text, number, date and time, measurement, reference, and advanced types such as JSON.

• Text types cover single-line and multi-line fields, useful for short descriptors or longer notes like care instructions.
• Number types handle integers and decimals, suited to quantities, counts or ratios.
• Measurement types store a value with a unit (metric or imperial), ideal for dimensions, weight or volume.
• Reference types point to another resource, such as a product, page, or metaobject entry.
• Date and time types record a single date or a full timestamp, often used for release dates or expiry information.
• Advanced types, including JSON, store more complex or mixed data structures when nothing else fits.

Some of these accept list variants, meaning a single field can hold multiple values of the same type, such as a list of related product references or a list of colour swatches. Not every type supports a list, so check the type reference before designing a field that depends on multiple entries.

A key configuration step most merchants skip is validation. Shopify’s documentation notes that definitions can carry validation rules such as minimum and maximum values, character limits, or a fixed list of allowed entries. Setting these when you create the definition stops inconsistent data from creeping into your catalogue as more people add values over time, which matters once a store has dozens of contributors or an agency managing uploads.

Where possible, reach for one of Shopify’s standard metafield definitions rather than building a bespoke one. Standards cover common fields like ISBN, ingredients and care instructions, and Shopify notes that using them improves compatibility with apps, themes and sales channels, since everyone reading the data expects the same structure.

Step-by-step: create a metafield definition and add values in Shopify admin

Creating your first metafield definition takes a few minutes once you know the path. Here is the full workflow from definition to verification.

1. In your Shopify admin, go to Settings > Custom data > Products, then select Add definition.
2. Give the field a clear name (this becomes the label merchants and theme editors see) and choose a namespace and key if you want control over the technical identifier, otherwise Shopify assigns one automatically.
3. Pick the content type that matches your data (text, number, measurement, reference, and so on) based on the type groups covered above.
4. Set any validation rules that apply, such as a character limit, a minimum or maximum number, or a list of permitted values.
5. Decide on storefront access. Shopify’s guidance explains that this setting controls whether the field is readable through the Storefront API, which matters if you plan to display it on your theme or pull it into a custom storefront.
6. Save the definition, then open an individual product and scroll to the Metafields section to add a value.
7. If the field is one you will use often, pin the definition from the custom data settings so it appears near the top of every product’s metafields list rather than buried further down.
8. Save the product and check that the value stored correctly by reopening the product page in admin.

Pro Tip: Add the definition and test it on one product before rolling it out across your catalogue, since a wrong type or missing validation rule is far easier to fix on a single item than after a bulk import.

Once the definition exists, every new product in that resource type will show the field as an option, even if you leave it blank. This is a useful way to standardise what information your team is expected to capture for each new listing, whether that is a warranty period, a fabric composition or a supplier reference code.

Manage metafields at scale: bulk editor, CSV import/export and API options

Adding values one product at a time works fine for a handful of listings, but a catalogue with hundreds or thousands of products needs a bulk approach. Shopify gives you three practical routes, and most stores will end up using a mix of them depending on the task.

1. Bulk Editor: select the products you want to update, choose Edit products, then use the Columns menu to add the metafield columns you need. Shopify’s bulk editing guidance confirms this lets you edit metafield values across many products in one grid view, similar to editing a spreadsheet.
2. CSV import and export: export your product catalogue, add or edit a column named in the product.metafields.namespace.key format, then re-import the file. Shopify’s CSV documentation notes this supports most metafield types, but variant-level metafields carry limitations in CSV, so the Bulk Editor is the more reliable route for variant-specific data.
3. GraphQL Admin API: for large, repeatable or automated tasks, such as syncing metafields from an external inventory system, Shopify’s developer documentation describes mutations like metafieldsSet and productUpdate that let you create, update or clear metafield values programmatically.

If your bulk edits mainly involve description text rather than custom fields, our walkthrough on bulk editing Shopify descriptions covers a complementary workflow. And if you are dealing specifically with variant-level content, our piece on Shopify variant descriptions explains some of the same CSV caveats that apply to variant metafields.

Ownership, access and app-owned vs merchant-owned metafields

Metafields are not all created equal in terms of who controls them. Shopify’s developer documentation on managing metafields draws a clear line between app-owned and merchant-owned namespaces, and understanding which is which avoids a lot of confusion when an app’s data suddenly appears, or disappears, from a product.

• Merchant-owned metafields are the ones you create through Settings > Custom data. You control the definition, the values and whether they show on the storefront.
• App-owned metafields use a reserved $app prefix in their namespace and belong to whichever app created them, meaning only that app typically manages the values.
• App-data metafields are installation-scoped, which means they are hidden from the merchant admin interface by default unless the app is built to expose them.
• Storefront access is set independently of ownership, so check this setting if a field is not appearing where you expect it on your theme.

As a practical rule, build your own definitions through admin for anything you or your team need to edit directly, such as warranty text or care instructions. Leave app-owned namespaces alone unless you are troubleshooting with the app’s support, since editing or deleting values outside the app’s intended workflow can cause the app to behave unexpectedly the next time it syncs.

Best practices and common pitfalls when designing metafields

A little discipline when setting up metafields saves a lot of cleanups later, especially once a catalogue grows past a few hundred products.

• Reach for Shopify’s standard definitions first; they improve compatibility with apps and sales channels compared with a bespoke field covering the same ground.
• Use a metaobject rather than several loosely related metafields when the content naturally repeats as a group, such as a specifications table.
• Keep namespaces and keys short, consistent and descriptive (specs.material rather than custom_field_7), since this becomes much harder to tidy up once dozens of fields exist.
• Pin the definitions your team uses most often so they are easy to find on every product.
• Set validation rules at the point of creation rather than after values already exist, since Shopify’s developer documentation warns that changing a field’s type later does not automatically convert existing values, and incompatible changes can invalidate them.

Pro Tip: Before a bulk import or a type change, export your current metafield values as a backup, then preview a handful of affected products in the Theme Editor to confirm everything still displays correctly.

A quick pre-launch checklist: preview new fields in the Theme Editor, run a small test CSV import before the full batch, and always keep an export of existing values before any large change.

Author perspective: when to DIY, when to use an app or developer

Most single-attribute metafields, a warranty length, a care note, a simple dimension, are entirely an admin job; for more advanced customization, tools like AccountCraft provide a visual builder for Shopify Customer Accounts to enhance data handling. No app or developer needed. Where it gets harder is structured, repeating content across a large catalogue: metaobjects with several linked fields, or metafields kept in sync with an external system.

That is where a developer earns their time, building the GraphQL calls that keep hundreds of products updated automatically rather than one admin screen at a time. For content generation at a similar scale, rather than structured data fields, tools built specifically for bulk product copy, such as the workflow described in our piece on bulk product descriptions, tend to save more time than editing each listing by hand.

— Jamie Moss

FAQ

What is the difference between Shopify metaobjects and metafields?

A metafield stores one value against a single resource, while a metaobject bundles several related fields into a reusable structure that a metafield can then reference. Use a metafield for a single attribute and a metaobject when the content naturally repeats as a group, such as a specifications table.

Can you make £10,000 a month on Shopify?

Shopify does not publish a standard figure for typical store revenue, since results depend heavily on product, pricing and marketing. Rather than chasing a specific number, focus on fundamentals such as accurate product data, strong descriptions and a catalogue structured for discoverability, which metafields and clean product content both support.

How do I add a personalised box to my Shopify products?

Personalisation fields, such as a custom text or monogram option, are usually added through a Shopify app built for order customisation rather than a standard metafield, since they need to capture buyer input at checkout. A merchant-owned metafield can store the resulting choice against the order or line item once the app captures it.

How do I find a product to sell on Shopify?

Shopify does not provide a single authoritative method for sourcing a winning product, and this falls outside what metafields or product data structure can help with directly. Once you have settled on products, well-structured metafields and consistent descriptions make it easier to list them clearly and keep that data accurate as your catalogue grows.

Sources

Getting a metafield to show on your product page does not usually require touching code. Shopify’s guidance on displaying metafields explains that the Theme Editor supports dynamic sources, a small icon that appears next to compatible block settings and lets you connect a metafield directly to that block.

To use it, open the Theme Editor on a product page, select a block that supports dynamic sources (commonly text or image blocks), and click the dynamic source icon to choose the metafield you want to display. The block then pulls live from whatever value you set in the product’s metafields.

A few things to check before you rely on this for a whole catalogue:

• Shopify Help Center | Metafields
• Shopify developer docs | Manage metafields

If you are also working on how descriptions themselves read and format on the page, our guide to the Shopify product description editor covers how structured metafield data and written descriptions can work together rather than duplicating the same information in two places.

For merchants who want more layout control over an entire template, it is worth reviewing how different product page sections are typically structured before deciding where a given metafield should live.

Recommended

• Shopify variant descriptions: how to add and show them
• How to add a short description to your Shopify products
• Shopify product schema: a merchant’s guide to AI product
• Shopify product description formatting: quick admin guide