WooCommerce stores often accumulate custom product data beyond the standard fields: material specifications, nutritional information, technical datasheets, care instructions, warranty details, certifications. This data is stored in WooCommerce as custom fields (via ACF, WooCommerce Custom Product Fields plugin, or direct post meta), and it won't migrate automatically to Shopify.

In Shopify, custom product data lives in metafields — a flexible key-value storage system for any data that doesn't fit Shopify's standard product schema. This guide explains how to map and migrate your WooCommerce custom data to Shopify metafields.

What is WooCommerce custom product data?

Custom product data in WooCommerce can come from:

Advanced Custom Fields (ACF): The most popular WP plugin for custom post meta. Products are WordPress posts, so ACF works on them.
WooCommerce Custom Product Fields / Checkout Fields: Various plugins that add extra fields to product edit screens.
Direct post meta: Custom code that adds data via update_post_meta()
WooCommerce product attributes: Standard WC feature — filterable attributes stored differently from post meta

All of this is accessible via the WooCommerce REST API (products endpoint returns meta_data) or the WordPress REST API.

What are Shopify metafields?

Shopify metafields are custom data fields that can be attached to products, variants, collections, customers, and orders. They have:

Namespace: A grouping identifier (e.g., custom, product_specs)
Key: The field name (e.g., material, care_instructions)
Value: The content (text, number, date, file reference, rich text, etc.)
Type: Determines how Shopify validates and displays the value

Example metafield: custom.material = "100% organic cotton"

Metafield types available in Shopify

Type	Best for	Example
Single line text	Short labels, codes, model numbers	Material: "Cotton", Model: "XJ-400"
Multi-line text	Paragraphs, multi-item lists	Care instructions, warranty text
Rich text	HTML content (formatted)	Technical specifications with headers
Integer	Whole numbers	Stock depth, pieces per box
Decimal	Decimal numbers	Weight in grams, dimensions
True/False (Boolean)	Yes/no flags	Is organic, Is gluten-free
Date	Dates	Harvest date, release date
URL	Links to documents or resources	PDF datasheet, spec sheet URL
File	Uploaded files (Shopify-hosted)	User manual PDF, size guide image
List of…	Multiple values of any above type	List of certifications, list of compatible models

Step 1: Inventory your WooCommerce custom fields

Before migrating, get a full list of custom fields in use:

Via WooCommerce REST API

Fetch a product and look at the meta_data array:

GET /wp-json/wc/v3/products/123

{
  "meta_data": [
    { "id": 1, "key": "_material", "value": "cotton" },
    { "id": 2, "key": "_care_instructions", "value": "Hand wash cold" },
    { "id": 3, "key": "_acf_weight_grams", "value": "350" }
  ]
}

ACF fields often have underscore-prefixed keys like _field_name or use prefixes like _acf_. WooCommerce internal fields also use underscore prefixes (e.g., _price, _sku) — filter these out, as they're already handled by standard migration.

Build an inventory spreadsheet

Collect all custom field keys used across your products:

Field key (as stored in WordPress)
Field label (human-readable name)
Data type (text, number, boolean, date)
Used in X products (% coverage)
Migration priority (high/medium/low based on customer-facing importance)

Be ruthless: many stores have accumulated custom fields over years that are no longer used or relevant. Now is a good time to decide what's worth migrating vs. what can be abandoned.

Step 2: Define Shopify metafield definitions

Before importing metafield values, create metafield definitions in Shopify. Definitions give metafields a name, type validation, and make them available in the theme editor.

In Shopify Admin → Settings → Custom Data → Products → Add definition:

Name: "Material" (customer-facing label)
Namespace and key: custom.material
Type: Single line text
Description: optional
Pin to top of product form: optional (useful for high-priority fields)

Create one definition per WooCommerce custom field you're migrating. Definitions also make metafields available in the Shopify theme editor (via Online Store 2.0), so you can display them on product pages without code.

Step 3: Display metafields in your Shopify theme

How metafields are displayed depends on your theme:

Online Store 2.0 themes (Dawn, Refresh, most themes from 2021+)

In the theme editor, you can add metafield blocks to product pages directly — no code required:

Go to Online Store → Themes → Customize
Open a product page template
Add a "Text" block or "Collapsible row" block
Set the content source to a metafield (e.g., custom.material)

Older themes or complex layouts

Use Liquid to output metafields:

{% if product.metafields.custom.material %}
  <p>Material: {{ product.metafields.custom.material.value }}</p>
{% endif %}

Step 4: Migrate metafield values via the Shopify API

After creating definitions and migrating products, populate metafield values via the Shopify Admin API.

Option A: Shopify metafields endpoint (per-product)

POST /admin/api/2024-01/products/{id}/metafields.json
{
  "metafield": {
    "namespace": "custom",
    "key": "material",
    "value": "100% organic cotton",
    "type": "single_line_text_field"
  }
}

Option B: metafieldsSet mutation (GraphQL bulk)

For large catalogs, the GraphQL metafieldsSet mutation can set multiple metafields across multiple products in one operation:

mutation metafieldsSet($metafields: [MetafieldsSetInput!]!) {
  metafieldsSet(metafields: $metafields) {
    metafields { id key value }
    userErrors { field message }
  }
}

With input of up to 25 metafield objects per call. For 1,000 products × 5 metafields each = 5,000 values — takes ~200 GraphQL calls.

Option C: Shopify CSV import (limited)

Shopify's standard CSV product import supports metafields via the "Metafield: namespace.key" column format. This works for simple text metafields but has limitations on type support.

Column format: Metafield: custom.material [single_line_text_field]

Handling WooCommerce product attributes vs. custom fields

WooCommerce has two systems that are often confused:

Product attributes: Used for product variants (Color, Size) and for display in a product attributes table. These migrate to Shopify variant options during standard migration.
Custom fields / post meta: Arbitrary data not tied to variants. These need the metafield migration path described in this guide.

For non-variant product attributes that you display in a "Product details" table on WooCommerce, the best Shopify equivalent is either:

Metafields with a "Product details" section in the theme
A freeform section in the product description
A collapsible accordion section in the theme (most OS 2.0 themes have this built in)

What k-sync supports for custom data migration

k-sync's WooCommerce import captures meta_data from the WooCommerce API and stores it in the raw sourceData JSONB field per product. During migration:

Standard product fields (title, description, price, SKU, etc.) are automatically mapped to Shopify fields
Custom meta_data fields are available in the product detail view for inspection
You can manually copy or reference custom field values

Automated custom field → metafield mapping (select a meta_data key and assign it to a Shopify metafield namespace/key) is on the k-sync roadmap for a future release. For the current version, metafield population after product migration can be done via the Shopify API using the product IDs returned by the push process.

Shopify metafields: how to migrate custom WooCommerce product data (2026)