Shopify metafields: a practical guide for stores migrating from WooCommerce (2026)

WooCommerce stores commonly extend product data with custom fields — via Advanced Custom Fields (ACF), WooCommerce product attributes, WooCommerce Product Add-Ons, or direct custom post meta. Shopify's equivalent is metafields: structured key-value data attached to products, variants, customers, orders, collections, and other objects. Understanding metafields is essential for a successful migration because product attributes that live in WooCommerce custom fields need to move somewhere in Shopify.

What are metafields

A metafield is a piece of structured data attached to a Shopify resource (product, variant, collection, customer, etc.). It has three components:

• Namespace: Groups related metafields (e.g. custom, product, seo). Use a descriptive namespace for your project (e.g. clothing, electronics, specs).
• Key: The field name within the namespace (e.g. material, warranty_years, compatible_models).
• Value: The stored data, typed according to the metafield type.

Example: product.metafields.clothing.material = "100% organic cotton"

Metafield types

Type	Use for	Example
Single line text	Short text values	Material, colour, brand
Multi-line text	Longer text, formatted notes	Care instructions, technical specs
Integer	Whole numbers	Warranty years, minimum age, quantity
Decimal	Decimal numbers	Weight, dimensions, alcohol %, THC mg
True/false	Boolean flags	Dishwasher safe, vegan, organic certified
Date	Date values	Production date, expiry date
URL	Links	Safety data sheet URL, lab certificate
JSON	Structured data	Compatibility lists, spec tables
File	Attached files	PDF instruction manual
Colour	Colour picker value	Primary colour hex
Rating	Star rating value	Product quality rating
Measurement	Value + unit	Weight in kg, height in cm
List of [type]	Multiple values of same type	List of compatible models (text list)
Metaobject reference	Links to a custom structured object	Linked to an "Artist" metaobject

Metafield definitions vs custom namespaces

Shopify supports two approaches to metafields:

• Defined metafields: Set up in Shopify Admin → Settings → Custom data. These have a specific type, are validated, appear in the product editor UI, and can be displayed in themes using metafield blocks. Recommended for all fields you want your team to edit.
• Unstructured metafields: Set via API without a prior definition. Useful for programmatic data import but not editable in admin without a definition.

During migration with k-sync, metafields are pushed to Shopify via API. Create metafield definitions in Shopify Admin after migration so your team can edit them without needing API access.

Replacing WooCommerce custom fields

WooCommerce approach	Shopify metafield equivalent
ACF field on product post type	Defined metafield (product namespace)
WooCommerce product attribute (global)	Shopify product options (for variants) or metafields (for spec data)
WooCommerce product attribute (custom)	Shopify product options or metafields
WooCommerce custom field (meta box)	Defined metafield
Product tab content (WooCommerce Tab Manager)	Metafield (multi-line text) + theme section
Product documents/PDF attachments	Metafield type: file

Displaying metafields in your theme

Shopify's Online Store 2.0 themes (Dawn and all modern themes) support metafield blocks in the theme editor. To display a metafield on a product page:

1. Create a metafield definition in Admin → Settings → Custom data → Products
2. In the Online Store theme editor, navigate to a product page template
3. Add a "Text" or "Metafield" block to the product section
4. Configure the block to display the specific metafield

For complex metafield displays (tables, conditional visibility), theme Liquid customisation or a metafield display app (Metafields Guru, Custom Fields) is required.

Bulk editing metafields after migration

After a k-sync migration, some metafields will be populated by the import (data that existed in WooCommerce), and others will need manual completion. For bulk editing:

• Shopify Admin → Products → All products → Export: Exports include metafield columns for defined metafields. Edit in spreadsheet, re-import.
• Metafields Guru app: Spreadsheet-style bulk editor for metafields in Shopify admin.
• Shopify Admin API: Programmatic bulk metafield update via metafieldsSet GraphQL mutation.

Metafield strategy for the migration

A practical approach to metafields during migration:

1. Audit WooCommerce custom fields: List all custom fields in use across your product types. Note which fields are displayed publicly and which are internal only.
2. Categorise each field: Is it a variant option (creates separate purchasable SKUs)? A specification (display only)? An internal tracking field? A content field (long text)?
3. Design namespaces: Use one namespace per product category (e.g. electronics, clothing) or one namespace for all custom data (custom).
4. Create definitions before import: Pre-create metafield definitions in Shopify so API-imported values are immediately typed and editable.
5. Configure theme display: Set up product page template metafield blocks for the fields customers need to see.

Post-migration metafield checklist

• WooCommerce custom fields audited and mapped to Shopify metafield definitions
• Metafield definitions created in Shopify Admin → Settings → Custom data
• Theme metafield blocks configured for publicly visible spec data
• Bulk edit tool identified for post-migration metafield enrichment
• Internal-only metafields set with correct namespace (not exposed in theme)
• Spot-check 20 products: verify metafield values migrated correctly