Migrating WooCommerce custom fields (acf) to Shopify metafields (2026)

WooCommerce stores built with Advanced Custom Fields (ACF), Meta Box, or WordPress custom fields often have significant amounts of structured product data that isn't part of the standard WooCommerce product schema. This data — ingredients, specifications, certifications, dimensions, technical data sheets, related documents — needs to be migrated to Shopify metafields. This guide covers the technical migration process.

WooCommerce custom field approaches

Custom field data in WooCommerce can come from multiple sources:

• ACF (Advanced Custom Fields): Most common — field groups assigned to product post type. Stores data in WordPress wp_postmeta table with ACF meta keys.
• Meta Box: Similar to ACF — field groups with typed fields (text, number, select, repeater, etc.).
• Pods: Custom content type and field builder. Sometimes used alongside WooCommerce.
• WooCommerce product attributes: Built-in WooCommerce feature — stores attributes in wp_termmeta and product meta. Available in standard WooCommerce export CSV.
• WooCommerce custom fields: Simple key-value meta stored via update_post_meta() calls from custom plugins.

Shopify metafields overview

Shopify metafields are key-value stores attached to Shopify resources (products, variants, customers, orders, collections). For product data migration, you'll primarily work with product-level metafields.

Metafield structure

{
  namespace: "custom",          // or your own namespace e.g. "specs", "nutrition"
  key: "ingredients",
  type: "multi_line_text_field",
  value: "Water, Sugar, Citric Acid"
}

Available metafield types

• Text: single_line_text_field, multi_line_text_field, rich_text_field
• Numbers: number_integer, number_decimal
• Boolean: boolean (true/false)
• Date/time: date, date_time
• URL: url
• JSON: json (for complex structured data)
• File: file_reference (for images/documents)
• References: product_reference, variant_reference, collection_reference, metaobject_reference
• Lists: list.single_line_text_field, list.product_reference, etc.
• Dimensions: dimension (with unit), volume, weight
• Rating: rating (min/max scale)
• Color: color (hex value)
• Money: money

Step 1: Audit your WooCommerce custom fields

Before migrating, document all custom fields per product type:

1. In WordPress Admin → ACF → Field Groups — list all field groups assigned to Products. For each group, note: field name (slug), field type, whether single or multiple values.
2. Export a sample of 10 products and check the metadata values in the exported CSV or via WP-CLI: wp post meta list {product_id}
3. Identify which fields are populated (not empty) across most products vs. fields that exist but are rarely used

Step 2: Create Shopify metafield definitions

Before importing data, create metafield definitions in Shopify Admin → Settings → Custom data → Products → Add definition.

For each WooCommerce custom field, create a corresponding Shopify metafield definition:

• Choose a namespace (e.g., "specs" for technical specifications, "nutrition" for food data)
• Key = snake_case version of the field name
• Type = closest Shopify type to the WooCommerce field type

Creating definitions is important because it: (1) enables type validation, (2) makes fields available in the Shopify theme editor's metafield picker, and (3) allows Admin UI editing of these fields on product pages.

Step 3: Export WooCommerce custom field data

Via WooCommerce CSV export (for product attributes)

Standard WooCommerce product attributes appear in the default CSV export. WooCommerce Admin → Products → Export → include custom fields in export settings.

Via ACF export plugin

For ACF fields, use "ACF: Advanced Custom Fields - Export" or similar plugin to export field data alongside product data.

Via WP-CLI (most comprehensive)

# Export all post meta for products
wp post meta list --post_type=product --format=csv > product_meta.csv

# Or target specific meta key
wp post meta list --post_type=product --keys=_custom_field_name --format=csv

Via direct database query

-- Export custom fields for all products
SELECT p.ID, p.post_title, pm.meta_key, pm.meta_value
FROM wp_posts p
JOIN wp_postmeta pm ON p.ID = pm.post_ID
WHERE p.post_type = 'product'
AND pm.meta_key IN ('_ingredients', '_allergens', '_certifications')
ORDER BY p.ID;

Step 4: Map WooCommerce meta_key to Shopify metafield

Build a mapping table:

WooCommerce meta_key	Shopify namespace	Shopify key	Type
_ingredients	nutrition	ingredients	multi_line_text_field
_allergens	nutrition	allergens	multi_line_text_field
_certifications	custom	certifications	list.single_line_text_field
_material	specs	material	single_line_text_field
_dimensions	specs	dimensions	single_line_text_field
_data_sheet_url	docs	data_sheet_url	url
_warranty_years	specs	warranty_years	number_integer

Step 5: Import metafields to Shopify

Option A: Shopify Admin CSV import (metafields)

Shopify Admin → Products → Import → select "Products and their metafields".

CSV format for product metafields:

Handle,Title,Metafield: specs.material (single_line_text_field),Metafield: nutrition.ingredients (multi_line_text_field)
blue-widget,Blue Widget,Stainless Steel,"Water, Sugar, Salt"
red-gadget,Red Gadget,Aluminum,"Flour, Butter, Eggs"

The column header format is: Metafield: namespace.key (type)

Option B: Shopify Admin API (programmatic)

// POST /admin/api/2024-01/products/{product_id}/metafields.json
{
  "metafield": {
    "namespace": "nutrition",
    "key": "ingredients",
    "type": "multi_line_text_field",
    "value": "Water, Sugar, Citric Acid, Natural Flavors"
  }
}

For bulk import of many products, write a script that:

1. Reads your WooCommerce export CSV
2. For each row, looks up the matching Shopify product by handle/SKU
3. POSTs the metafield values via Admin API

Option C: k-sync metafield mapping

k-sync can import custom field values from your WooCommerce product export and map them to Shopify metafields during the migration. In k-sync's Mapping view, custom WooCommerce attributes can be mapped to target Shopify metafield namespaces and keys before pushing to Shopify.

Step 6: Display metafields in your Shopify theme

After importing, metafields need to be rendered in the product page template. Shopify's theme editor includes a metafield picker for blocks:

• Shopify Admin → Online Store → Themes → Customize → Product page
• Add a "Text" block → Source → select a metafield
• Or edit theme Liquid directly: {{ product.metafields.nutrition.ingredients }}

Liquid rendering for different metafield types

{%- comment -%} Single line text {%- endcomment -%}
{{ product.metafields.specs.material.value }}

{%- comment -%} Multi-line text (preserves line breaks) {%- endcomment -%}
{{ product.metafields.nutrition.ingredients.value | newline_to_br }}

{%- comment -%} Rich text {%- endcomment -%}
{{ product.metafields.custom.description.value }}

{%- comment -%} URL (link) {%- endcomment -%}
{%- if product.metafields.docs.data_sheet_url.value -%}
  <a href="{{ product.metafields.docs.data_sheet_url.value }}">Download Data Sheet</a>
{%- endif -%}

{%- comment -%} Number {%- endcomment -%}
{{ product.metafields.specs.warranty_years.value }} year warranty

Verifying the migration

After import, verify a sample of products:

1. In Shopify Admin → Products → select a product → scroll to "Metafields" section → verify all expected values are present
2. View the live product page on your Shopify store and verify metafields render correctly
3. Spot-check 5–10 products across different product categories
4. Check that the most important metafields (ingredients, certifications, dimensions) are correct on key products

Custom field migration is the most manually intensive part of migrating data-rich WooCommerce stores. But it's critical — customers rely on this data to make purchase decisions, and incomplete product specifications lead to higher return rates and support volume. Investing time in the metafield migration pays off post-launch.