Shopify Variant Metafields CSV Import: A Step-by-Step Guide
Shopify variant metafields CSV import: the short answer
You can bulk-update variant metafields from a supplier CSV by matching each row to a variant on SKU, mapping CSV columns to existing metafield definitions, and reviewing the changes before anything is written. Shopify's admin gives you manual editing and a bulk editor for this, and you can add an import app when the supplier file is large or recurring. Shoperize Variant CSV is built for exactly that task, and it has been live on the Shopify App Store since October 26, 2026.
This guide walks through one supplier file from upload to restore, so you can see where each check happens. It is part of the Shoperize Shopify apps family, alongside the Price Calculator.
What you can do natively vs. with an app
A variant metafield is a custom field attached to one variant (one width, one colorway, one pack size). A product metafield is attached to the product as a whole. If a fabric comes in three widths, the width belongs on the variant, because it differs per row of your supplier sheet.
Here is what Shopify gives you on its own:
- Metafield definitions in Settings. A definition fixes the namespace, key and type (text, decimal, boolean, list and so on) so values stay consistent.
- Manual editing on each variant page.
- The bulk editor, a spreadsheet-style grid in the admin where you can show metafield columns and edit many rows.
- Shopify's product CSV import, which is built around products and handles. Shopify's Help Center documents which metafield columns it supports, so check the current docs for your store before relying on it for variant-level fields.
What none of those are designed to do is take a supplier file keyed by SKU, show you a field-by-field before/after, and keep a restore history. That gap is what an import app fills.
Where Shoperize Variant CSV fits (live since Oct 26, 2026)
Variant CSV imports a supplier CSV into existing variant metafield definitions. It matches on exact, unique SKU, validates each value against the definition's type, and shows a before/after review that you must approve before it applies anything. Blank cells leave current values unchanged, and eligible updates can be restored from a 90-day history.
It is deliberately narrow. It does not create products, edit prices or inventory, or read XLSX. More on that in the limits section.
Why supplier spec sheets are painful to load into variant metafields
Picture a fabric store with 400 variants. The supplier emails a new spec CSV each quarter with widths, material names and care text. Some values changed, most did not, and a few rows use new SKUs you have not created yet. Nobody wants to open 400 variant pages to find the 60 that changed.
Manual editing and the bulk editor: where each stops being practical
Be fair to the native tools: for 10 or 20 variants, editing by hand is fine, and the bulk editor is a good fit for a one-off cleanup of a single field. The trouble starts when the source of truth is a file someone else sends you.
- Manual editing means finding each variant and retyping values. It is slow and typo-prone.
- The bulk editor works inside the admin grid. You select and edit rows there, and you can paste values, but there is no step where it reads a supplier file, lines rows up by SKU, and tells you which rows did not match. Check Shopify's current docs for how many rows and columns it loads at once.
- Neither gives you a saved mapping from this supplier's column names to your metafields, so you rebuild the process every quarter.
What goes wrong: wrong SKU matches, text in number fields, blanks wiping data
Three failures show up again and again with supplier files:
- Wrong or ambiguous SKU matches. A trailing space, a changed case or a duplicate SKU in the store sends a value to the wrong variant, or nowhere.
- Text in typed fields. Suppliers write "approx 48 in" or "48in" into a column that your definition stores as a decimal. Depending on the tool, that is either rejected late or silently mangled.
- Blanks wiping data. If an empty cell is treated as "set to empty", a supplier file with missing care text erases the care text you wrote yourself.
A good import process catches all three before data is written.
Your options compared
| Option | Best for | Review before write | SKU matching | Undo | Remote or scheduled import |
|---|---|---|---|---|---|
| Manual / bulk editor | Small batches, one-off fixes | You see the grid as you edit | You find rows yourself | No dedicated restore history in the editor | No |
| Shoperize Variant CSV | Supplier spec updates to variant metafields | Required before/after approval | Exact, unique SKU | 90-day history, conflict checks | No |
Manual / bulk editor
Free, built in, and the right answer when the batch is small. Use it first if your catalog is small or your supplier file rarely changes.
Shoperize Variant CSV
Pick it when a person uploads a supplier file, wants to see exactly what will change, and wants a way back. It trades breadth for a review-first workflow.
Worked example: a 6-row supplier CSV to variant metafields
This example uses illustrative data from an imaginary fabric store. The goal: update width, material and care text on six variants.
Step 0: metafield definitions must already exist
Variant CSV writes into existing definitions. Before uploading, create these in Settings, Custom data, Variants:
| CSV column | Namespace.key | Type |
|---|---|---|
| SKU | (used for matching) | n/a |
| width | custom.width_in | Decimal (number_decimal) |
| material | custom.material | Single line text |
| care | custom.care | Multi-line text |
Using a decimal named width_in keeps the unit in the key. If you prefer Shopify's dimension type, which stores a value plus a unit, check the app listing for how Variant CSV expects dimension values to be written.
Step 1: the CSV
Save the file as UTF-8 CSV. These are the raw lines of the file (one line per bullet, remove the bullet when copying):
- SKU,width,material,care
- LIN-NAT-48,48,Linen,"Machine wash cold, tumble dry low"
- LIN-SAGE-48,48,Linen,"Machine wash cold, tumble dry low"
- COT-WHT-56,56,Cotton,Machine wash warm
- COT-NVY-56,approx 56 in,Cotton,Machine wash warm
- VEL-RED-54,54,Velvet,
- VEL-RED-54B,54,Velvet,Dry clean only
Note the quotes around care text that contains a comma. Without them, a CSV reader splits the cell in two and shifts every column after it.
Step 2: upload and map columns (save the mapping for this supplier)
Upload the file and map each column to its definition using the table above. Save the mapping as this supplier's profile. Next quarter the supplier's file will have the same headers, so you pick the saved mapping instead of rebuilding it. You select only the metafields you want to touch (the app caps this at 20 per import).
Step 3: exact SKU matching
Variant CSV matches on exact, unique SKU. In our file:
- Rows 1 to 5 match one variant each.
- Row 6, VEL-RED-54B, matches nothing in the store. It shows as unmatched and is skipped. Maybe it is a new variant you have not created, or a supplier typo. The app does not guess, and it does not create products or variants.
- If a SKU appeared twice in your store, it would not be a unique match and would be flagged rather than written to one of the two at random.
Step 4: typed-value validation catches "approx 56 in"
Row 4 has approx 56 in in a column mapped to a decimal. That cannot be stored as a number, so validation flags the row before any write. You have two fixes: edit the CSV to read 56 and re-upload, or correct the value as the review prompts. We change it to 56 and re-run validation. All five matched rows now pass.
Step 5: before/after review and approval
The review shows old and new values for every matched row. Here is the result for our file:
| SKU | Width | Material | Care |
|---|---|---|---|
| LIN-NAT-48 | empty to 48 | Linen (no change) | "Machine wash" to "Machine wash cold, tumble dry low" |
| LIN-SAGE-48 | 45 to 48 | "Flax linen" to "Linen" | empty to "Machine wash cold, tumble dry low" |
| COT-WHT-56 | 56 (no change) | Cotton (no change) | "Wash warm" to "Machine wash warm" |
| COT-NVY-56 | 54 to 56 | "cotton" to "Cotton" | Machine wash warm (no change) |
| VEL-RED-54 | 54 (no change) | Velvet (no change) | "Dry clean only" stays, because the CSV cell is blank |
| VEL-RED-54B | unmatched, skipped | unmatched, skipped | unmatched, skipped |
Two things to notice. The blank care cell on VEL-RED-54 leaves "Dry clean only" in place, which is what you want when a supplier file is incomplete. And the "Flax linen" change would have been easy to miss by hand: a review makes you decide on it. Nothing is written until you approve.
Tile stores follow the same pattern: keep carton coverage and thickness current in metafields, then sell by carton with the Shopify tile calculator.
Step 6: reports, selected-field export and restore from 90-day history
After applying, download the CSV report to see what was written, skipped or rejected. You can also export selected fields, which gives you a clean backup of current values before your next supplier file arrives.
If the supplier file turns out to be wrong, eligible updates can be restored from the 90-day history. Restore runs conflict checks: if someone edited a value after your import (say a colleague changed LIN-SAGE-48's width to 47), that field is flagged rather than overwritten.
One limit to plan for: newly created metafields cannot be automatically undone. In our example, LIN-NAT-48's width and LIN-SAGE-48's care had no previous value, so those values were newly created and would need to be cleared by hand. Exporting before you import makes this easy to manage.
Typed values: what to put in the CSV
Each definition has a type, and every cell mapped to it must fit. Check Shopify's metafield type documentation for the full list, and the app listing for how lists and dimensions are handled.
Text, number, boolean, list, dimension: format examples
| Type | Example cell | Notes |
|---|---|---|
| Single line text | Linen | No line breaks |
| Multi-line text | Machine wash cold | Quote cells that contain commas or line breaks |
| Integer | 12 | Whole numbers only |
| Decimal | 48.5 | Digits and a decimal point, no units or words |
| Boolean | true | Use true or false, not "yes" or "Y" |
| List | See the listing | Confirm the expected separator before importing a whole file |
| Dimension | See the listing | Stores value and unit, confirm accepted format first |
When unsure, test with a two-row file first. Validation costs nothing, because the review stops before any write.
Common validation errors and fixes
- "approx 48 in" or "48in" in a decimal. Strip the words and unit: 48. Put the unit in the key (width_in) or use a dimension definition.
- "Yes" in a boolean. Replace with true.
- Comma in an unquoted cell. Wrap the cell in double quotes.
- Comma as decimal separator (48,5). Use 48.5, or the cell splits.
- SKU with trailing space or different case. Clean it in the CSV. Matching is exact.
- File not UTF-8. Re-save as CSV UTF-8, or accented characters (like "Velours" or "Étoffe") can arrive garbled.
Limits and what Variant CSV does not do
Limits: UTF-8 CSV, 20 MB, 10,000 rows, 100 columns, 20 selected metafields
- UTF-8 CSV file, up to 20 MB
- Up to 10,000 rows
- Up to 100 columns
- Up to 20 selected metafields per import
If your supplier file is bigger, split it by collection or product line.
Does not: create products, edit prices or inventory, delete, read XLSX, fetch remote files, schedule imports
- It does not create products or variants. For that, use Shopify's native product import.
- It does not edit prices or inventory.
- It does not delete products, variants or metafield definitions.
- It does not read XLSX. Export to CSV first.
- It does not fetch supplier files remotely (no FTP, URL or email pickup) and does not schedule imports. Someone uploads each file.
- Restore does not automatically undo newly created metafields.
If you need a feed that runs on its own every night, an automation tool is the better fit. If you need to load whole new catalogs, use a product import tool. Variant CSV is for the specific job of keeping supplier specs on existing variants accurate, with a review.
Pricing and how to try it
$14.99/month, 7-day free trial; upload, mapping and validation work before purchase
Variant CSV costs $14.99 per month with a 7-day free trial. You can upload a file, map columns and run validation before you buy, so you can test your own supplier CSV and see which rows would fail. Install it from the Shopify App Store listing or read the Variant CSV app page.
If your store also sells by area, length or package, the Shoperize Price Calculator turns shopper measurements into purchasable quantities. See the Price Calculator launch post and our square footage calculator guide for flooring and tile stores whose coverage specs come from supplier CSVs. More guides are on the Shoperize blog.
Ready to try it on your own supplier file? Install Shoperize Variant CSV (details at shoperize.com/apps/variant-csv), and find setup help at help.shoperize.com.
Frequently Asked Questions
How do I import a CSV file into Shopify?
For products, use Import on the Products page in the Shopify admin and upload a file that follows Shopify's CSV template. For supplier data going into variant metafields, an app like Shoperize Variant CSV matches rows by SKU and shows a review before it writes anything.
How do I bulk edit product metafields in Shopify?
Create the metafield definitions first, then open the bulk editor from the Products page and show the metafield columns you want to edit. It works well for small batches. For a supplier file with hundreds of rows, an import app that maps columns and validates values is faster.
How do I add products to Shopify?
Add them one at a time from the Products page, or use Shopify's native product CSV import for many at once. Shoperize Variant CSV does not create products or variants. It only updates metafields on variants that already exist in your store.
How to check product count in Shopify?
Open the Products page in your Shopify admin and use the filters or tabs to narrow the list. The admin shows the count for the current view, and the exact layout can change, so check Shopify's current help docs.