ACF fields don't move to Shopify. Their data does.

Two halves of one move

Take one product from a clothing store: a fabric note, a launch date, an organic flag and a size chart built with a repeater. In WordPress all of it lives in wp_postmeta, one row per value, next to the row that tells ACF which field the value belongs to.¹⁶ On Shopify the same product carries typed metafields, and the size chart becomes a list of metaobject entries.

The _fabric row only tells ACF which field a value belongs to, and is not migrated. The repeater's row count (3) and its numbered keys become three metaobject entries.

That gives you two separate jobs. The structure, meaning the field groups, is rebuilt once by hand or by script as Shopify definitions. The values are exported, converted and imported for every product. Mixing the two up is how custom fields get lost: an import that writes values to a metafield with no definition behind it may succeed, but the field does not appear in the product editor, cannot be validated, and cannot be connected to the theme without code.

Every ACF field type, mapped

Shopify's list of metafield types has grown well beyond the twenty-odd types most guides still describe. It now includes measurement types such as temperature and duration, references to articles and orders, and mixed_reference, which can point at metaobjects of more than one definition.¹ For ACF fields, the useful subset is below.

Convert your field groups

In WordPress, open ACF's export tool, export the field groups attached to products, and paste the JSON below. You get the Shopify type for every field, what to watch out for, and the GraphQL to create the definitions. The converter runs in your browser, so nothing you paste is sent anywhere.

Treat the output as a first draft. It suggests the type a field's data needs, but whether a fabric note should be free text or a fixed list depends on how you want to filter it. That decision is worth making now, before 2,000 products are imported into the wrong shape.

Repeaters and flexible content

A repeater is the field type that makes people put off this part of a migration, and it maps more cleanly than its reputation suggests. ACF stores a repeater as numbered keys, size_chart_0_size, size_chart_1_size and so on, with the row number in the middle of the key.¹⁴ On Shopify, the sub-fields become a metaobject definition, each row becomes an entry, and the product holds a list that points to its entries in order.¹

Before creating one definition per repeater, check whether the rows are really shared data. If forty products carry the same size chart, create one chart and reference it from all forty. A fix to that chart then reaches every product at once, which a repeater never could.

Flexible content follows the same idea, with one metaobject definition per layout and a list.mixed_reference on the product, the type that may point to entries of different definitions.¹ If a flexible content field mostly builds page layouts rather than holding product data, rebuild it with theme sections instead. Section blocks are what Shopify themes use for that job, and they give the merchant a visual editor.

Moving the values

1. DefineCreate every metafield and metaobject definition on Shopify first, with validations.
2. ExportRead the values from the WooCommerce REST API or the database.
3. ConvertDates, booleans, serialized arrays, attachment and post IDs.
4. ImportProduct CSV for simple types, the Admin API for the rest.

Where to read them

The WooCommerce REST API returns a product's custom fields in meta_data.¹⁷ It leaves out only WooCommerce's own internal keys and keys that start with wp_,²¹ so ACF's values arrive along with the underscore rows that point to their field keys, still in their stored format. Since ACF 5.11, a field group can also be shown in the WordPress REST API, under an acf property, with the setting "Show in REST API".¹⁵ It is off by default. For large catalogues, a direct database export is faster than either.

What needs converting

• Dates: 20260315 becomes 2026-03-15.¹¹
• True/false: 1 and 0 become true and false.¹²
• Serialized arrays: a:2:{i:0;s:3:"123";…} is unpacked into a list.¹³
• Attachment IDs: look up each file's URL in WordPress, upload it to Shopify Files, and write the new file ID.
• Post IDs: import products first, keep a table of old WooCommerce ID to new Shopify ID, then write the references. Keeping the old ID in a metafield of type id makes later imports match by it.¹
• Everything: Shopify stores every metafield value as a string, whatever its type, so lists and numbers are written in their string form.¹

CSV or API

The product CSV takes metafield columns named like Fabric (product.metafields.custom.fabric), and list values separated by a semicolon and a space.⁵ That covers text, numbers, booleans, dates, colours, URLs, measurements, product references and lists of metaobject references. It does not cover file references, rich text, JSON, single metaobject references or links, and variant metafields cannot go through the product CSV at all.⁵ Those go through metafieldsSet, which writes up to 25 metafields per call, all or nothing.⁹

Showing and filtering them

On WordPress, someone wrote PHP in the theme to display each field. On a Shopify Online Store 2.0 theme, most metafields can be connected to a section setting from the theme editor without code, through dynamic sources: a file_reference fills an image setting, a list.product_reference fills a product list, and text, numbers, dates and money can fill a rich text block.⁷ Liquid can read every metafield. A headless storefront needs storefront access switched on in the definition, which is off by default.⁸

Filters are where the type choice pays off. The Search & Discovery app can filter by single line text, integer, decimal, true or false and metaobject reference metafields, and their list versions, up to 25 filters per store.⁶ A fabric stored as free text in a multi-line field can never become a filter. The same fabric as a choice list can.

Meta Box, Pods, Secure Custom Fields and plain attributes

ACF is the common case, with more than two million active installs, but not the only one.¹⁸ Secure Custom Fields, the fork WordPress.org created from ACF in October 2024, stores data the same way and maps the same way.²⁵ Meta Box (500,000+ installs) and Pods (100,000+) use their own field names but the same underlying idea of values in post meta, so the type table above still applies once you know which field type each one is.²⁶²⁷

The custom data many WooCommerce stores forget is not in a plugin at all. Product attributes that are not used for variations, such as Material or Origin, show on the product page's "Additional information" tab.¹⁷ On Shopify they are metafields too. The variations guide covers how to tell which attributes should be options and which should not.

Custom field checklist

• Export every ACF field group and list which ones sit on products, variations, categories, pages and posts.
• Remove fields that are empty on most products. A migration is the cheapest moment to drop them.
• Check each field against Shopify's category metafields before creating a custom definition.
• Decide which fields need to be filters, and give those a filterable type.
• Create all definitions and metaobject definitions, with validations, before importing a single value.
• Upload files to Shopify first, and keep a table from WordPress attachment ID to Shopify file ID.
• Import products before writing product references, and keep the old WooCommerce ID in an id metafield.
• Convert dates, date-times (with the right time zone), booleans and serialized arrays.
• Connect each metafield to the theme with dynamic sources, then compare ten products side by side with the old store.

The free readiness scanner detects ACF and other plugins on a WooCommerce store, and the plugin map lists what replaces each of them.

Frequently asked questions