Update Metafields CSV Guide: Shopify Native Import and Apps
To update metafields with a CSV in Shopify, export your products, edit the metafield columns in a spreadsheet and import the file back with Overwrite products with matching handles turned on. Shopify’s product CSV supports product metafields natively, with columns named like Fabric (product.metafields.custom.fabric).
Native CSV imports don’t cover everything, though. Variant metafields, some metafield types and metafields on other resources need the bulk editor, an import app or the API, so it helps to know which route fits your data before you start.
How to Update Metafields With a CSV in Shopify
The safest way to update product metafields is to start from an export, so your file already has the right columns and value formats. The whole process happens in your Shopify admin and a spreadsheet:
- Create the metafield definitions. Go to Settings > Metafields and metaobjects > Products and make sure each metafield you want to update has a definition.
- Export your products. Go to Products > Export and export the products you want to update. Defined product metafields are included in product CSV exports.
- Edit the metafield columns. Open the file in a spreadsheet, find the metafield columns and enter or change the values.
- Remove columns you don’t need. Keep the Handle column and the metafield columns you’re changing, and delete the rest to avoid overwriting other data by accident.
- Import the file. Go to Products > Import, add the file, check Overwrite products with matching handles and click Upload and continue.
- Review and import. Check the preview, click Import products and spot-check a few products afterward.
When overwriting, columns you leave out keep their existing values, while blank cells in included columns clear the current value. Product CSV files can’t be larger than 15 MB, so split large catalogs into several files.
Metafield column header format
Each metafield gets its own column, identified by its namespace and key. Shopify accepts two header formats:
- With a name:
Fabric (product.metafields.custom.fabric) - Without a name:
product.metafields.custom.fabric
You can find a metafield’s namespace and key in its definition under your metafield settings. A typo in the namespace or key means Shopify won’t match the column to the right metafield.
Metafield types supported in product CSVs
Shopify’s product CSV supports many common metafield types, but not all of them. Check your field types against this list before planning a CSV update:
| Category | Supported types |
|---|---|
| Text and links | Single line text, multi-line text, URL |
| Numbers and measurements | Integer, decimal, dimension, weight, volume, money |
| Dates and other values | Date, date and time, true or false, color |
| References | Product reference |
| Lists | Lists of colors, dates, dates and times, dimensions, integers, decimals, URLs, volumes, weights, product references and metaobject references |
The easiest way to get value formats right is to look at how they appear in your export, then enter new values the same way. This matters most for structured types such as dimensions, weights and lists.
What Shopify’s Native CSV Can’t Update
The product CSV handles product-level metafields, but several common cases need another method. Watch for these limits:
- Variant metafields. These aren’t supported in product CSV imports or exports, so use the variant bulk editor with metafield columns, or an app.
- Unsupported types. Types such as rich text, file and page references aren’t on the product CSV’s supported list.
- Collection, order and other resource metafields. The product CSV only covers products, so other resources need an app or the API.
- Customer metafields. The customer CSV supports some metafield types, such as true or false, dates, integers, decimals and single line text, using headers like
customer.metafields.namespace.key.
For smaller changes, Shopify’s bulk editor is another native option. Select products, click Bulk edit, add metafield columns and edit values directly, which also works for variant metafields in the variant editor.
Update Metafields With an Import App
Import and bulk editing apps fill the gaps in native CSV support, such as variant metafields, more types and other resources. Each app uses its own column format, so follow its documentation exactly.
| App | How metafield columns work | Notes |
|---|---|---|
| Matrixify | Metafield: namespace.key for products, and Variant Metafield: namespace.key with Handle and Variant SKU for variants |
Supports exporting, editing and re-importing metafields in Excel or CSV |
| Bulk Product Edit by Hextom | Map a CSV column to a metafield, then enter the namespace, key and value type | Covers products, variants, collections, customers and orders, and entering “delete” removes a metafield |
| Firebear Import & Export Tool | Columns named mf_namespace.key, such as mf_custom.fabric |
Imported values overwrite existing ones, and an empty value clears a field |
Apps also tend to support more value types than the native CSV, including rich text, file references and JSON. Many offer a free or demo plan with limits, so test a small file before buying a plan for a large update.
Update Metafields With the API
If you have development help, a script can read your CSV and update metafields through Shopify’s Admin API. The file usually needs a column to identify each product, such as its handle or ID, plus one column for each metafield.
The script looks up each product and writes the new values, for example with the GraphQL Admin API’s metafieldsSet mutation. This approach suits recurring updates from another system, such as an ERP or product information tool, where you want full control over formats and error handling.
Format Metafield Values Correctly
Shopify rejects values that don’t match a metafield’s type, so formatting matters as much as the column headers. A single wrong value can stop a row from updating, so keep these rules in mind:
- Dates and times. Use ISO format, such as 2026-10-13 or 2026-10-13T09:00:00.
- True or false. Enter
trueorfalse. - Colors. Use hex codes, such as #59ca22.
- References. Use the formats your tool expects, which are often Shopify global IDs.
- Lists and rich text in apps. Some apps require list values as JSON arrays and rich text as Shopify’s rich text JSON.
- Validations. Values must also meet any rules on the definition, such as minimum and maximum numbers or character limits.
Before You Import Metafield Updates
A failed or incorrect import can overwrite good data across many products. A few precautions keep updates safe:
- Back up your data. Keep an untouched export so you can restore values if something goes wrong.
- Test a few products first. Import a small file and check the results on the product pages and in the admin.
- Keep the file lean. Include only the Handle column and the metafields you’re changing.
- Watch blank cells. An empty cell in an included column clears that metafield on overwrite.
- Save as UTF-8 CSV. This keeps special characters intact.
Common Metafield CSV Problems
Many metafield import issues come from headers, types or overwrite settings. Watch for these:
- Values didn’t change. The overwrite option wasn’t selected, so rows with matching handles were skipped.
- Metafield columns were ignored. The header format, namespace or key doesn’t match the definition.
- Values were rejected. The value doesn’t match the metafield type or fails a validation rule.
- Existing values were erased. Blank cells in included metafield columns cleared the data.
- Variant metafields didn’t update. The native product CSV doesn’t support them, so use the bulk editor or an app.
- Rich text or file metafields didn’t import. Those types aren’t supported in the native product CSV.
- The upload failed. The file is larger than 15 MB, so split it into smaller files.
Conclusion
Knowing how to update metafields with a CSV saves hours when you need to change product details across your catalog. Shopify’s native product CSV covers many product metafields, while the bulk editor, import apps and the API handle variants, extra types and other resources. We hope this guide helps you update metafields with CSV files accurately and with confidence.
