Documentation

How these tools work, what each one does, and what to check before importing into Shopify.

Overview

These tools take a Shopify product CSV export, apply changes, and produce a smaller CSV that you import back into Shopify to update your products. All processing happens entirely in your browser — your files are never sent anywhere.

For most tasks, you'll only need the Metafield Updater. The Tag Inspector and Tag Renamer are maintenance tools — useful when you need to audit your tag coverage or correct tag names, but not part of the everyday routine.

Common use cases

New products have been imported into Shopify and their metafields need to be populated from their tags.
A tag was changed or corrected on one or more products and the metafields need to reflect that.
A new value has been added to the mapping and existing products with the corresponding tag need to be updated.

Typical workflow

Export the relevant products from Shopify (see Exporting from Shopify below).
Run the Metafield Updater — it will generate a CSV containing only the products where something changed.
Use the Import Previewer to compare the output CSV against your original export and confirm the changes look right.
Import into Shopify: Products → Import → Upload CSV.

Exporting from Shopify

Go to Products → Export. You have two options:

All products — exports your entire catalogue. Use this for a full backup before any large update, or when you're not sure which products need changes.
Filtered products — if you've already filtered your product list in Shopify (by collection, type, tag, or a search), you can export just that subset. This keeps the CSV small and makes it faster to review. Products that don't need changes are automatically skipped in the Updater output, so over-exporting is safe — but filtering first is more efficient when you know which products you're targeting.

The Tools

Metafield Updater

Reads the Tags column of each product, matches tags against a configurable mapping (e.g. color-pumpkin → orange, color-navy → navy), and fills in the corresponding metafield columns in the output CSV.

The output contains only products where at least one metafield value changed — products that are already up to date are skipped. One row is written per product, since Shopify product metafields are product-level; variant-level metafields are not supported via CSV import.

See Managing the Mapping for how the mapping is structured, where it's stored, and how to keep it in sync with Shopify.

Tag Inspector — maintenance tool

Scans your export and shows every tag in use across all products, split into two groups:

Mapped — tags that appear in the Metafield Updater's mapping and will be converted to metafield values when you run the Updater.
Unmapped — tags not in the mapping. These will be ignored by the Updater. If a tag should map to a metafield, either add it to the mapping or rename it first with the Tag Renamer.

The Inspector does not modify anything or produce a CSV — it is a read-only audit tool. Use it when you want to verify that your tag coverage looks correct, or to identify tags that may be missing from the mapping.

Tag Renamer — maintenance tool

Renames or normalises tags in bulk. You define one or more rules (old tag → new tag), then run them against your export. The output CSV updates the Tags column for every product where at least one rule matched.

Use this when tag names are inconsistent and need to be corrected before the Updater can map them — for example, if some products use fiber-silk but the mapping expects silk.

Import Previewer

Compares a generated import CSV against the original export and shows exactly what will change, per product and per field, before you upload anything to Shopify. Drop in both files and the diff appears instantly — no output is produced and nothing is sent anywhere.

Use this after running the Metafield Updater or Tag Renamer to sanity-check the output CSV: verify that the right products are included, the right fields are changing, and the new values look correct.

Managing the Mapping

The mapping is the heart of the Metafield Updater — it tells the tool which Shopify metafield each product tag should populate, and what value to write. This section covers what it looks like, where it lives, and how to keep it healthy over time.

What the mapping is

The mapping has two layers:

Metafield headers like custom.fiber_types or shopify.color-pattern are the actual metafield identifiers in Shopify (namespace.key). They must match exactly — if Shopify expects custom.fiber_types and your mapping has custom.fiber-types, the tool won't update that field.
Tag → value pairs inside each header translate one of your product tags into the value its metafield should hold. For example, the tag color-pumpkin maps to orange, so any product tagged color-pumpkin ends up with orange in its colour-pattern metafield.

You can see the current mapping by opening the Metafield Updater and clicking Edit ▾ in Step 2.

Where the mapping is stored

Your mapping is saved in this browser only — there's no server, no account, no sync. That has a few consequences worth knowing:

Other people can't see your mapping, even on the same Shopify store.
A different browser or computer starts with the built-in default mapping.
Clearing your browser's site data will erase your saved mapping.
The Step 2 row says either Saved mapping (a saved version exists) or Default mapping (the one built into the tool).

Because of this, export your mapping as a JSON file regularly — think of it as a backup of your translation table. Inside the editor, click Export JSON to download mapping.json and keep it somewhere safe (Drive, Dropbox, your Shopify documentation folder).

To restore a backup, click Edit ▾ → Import JSON and choose your saved file. The Step 2 row will switch to Saved mapping with the new counts.

Keeping the mapping in sync with Shopify

The default mapping baked into the tool reflects what your Shopify store looked like when the tool was built. If you've added new metafields in Shopify since then — a new colour, a new fibre type, a brand-new metafield definition — the tool won't know about them automatically.

The most common symptom: you process a CSV, but a metafield column that should be filled comes out blank for some or all products. That usually means one of two things:

The tag isn't in the header's list yet. Open Edit ▾, find the right header, and add the new tag → value pair.
The metafield itself isn't in your mapping at all. Click + Add group at the bottom of the editor, type the new namespace.key (exactly as it appears in Shopify), then add tag → value pairs inside.

After any change, export a fresh JSON backup.

If something looks wrong but you can't tell why, run the Tag Inspector against the same export — it shows which tags are mapped vs. unmapped, which is usually the fastest way to spot the gap.

Setting up another computer

If you need to work from a different computer (or hand the tool off to someone else):

On your current computer, click Edit ▾ → Export JSON. Save the file.
On the new computer, open the Metafield Updater. The Step 2 row will read Default mapping.
Click Edit ▾ → Import JSON and choose the file you exported. The row will switch to Saved mapping with your counts.

If the new computer's browser data is ever cleared, repeat from step 2.

A note on Reset to default

The Reset to default button inside the editor wipes your saved mapping and goes back to the built-in default. It's mainly useful if you've made a mess of the editor and want to start clean. Export a JSON backup first — there's no undo for this action.

Understanding the Output CSV

Before importing, open the file in a spreadsheet app (Numbers, Excel, or Google Sheets). The key columns are:

Column	What it contains
`Handle`	Shopify's unique URL identifier for the product (e.g. `my-canvas-title`). This is how Shopify matches each row to the correct product on import. It must match exactly.
`Title`	The product's display name.
`Option1 Name`	The name of the product's first option. For products with no real variants, this is always `Title`.
`Option1 Value`	The value of the first option. For products with no real variants, this is always `Default Title`.
Metafield columns	One column per metafield, named like `Fiber Type (product.metafields.custom.fiber_type)`. Multiple values are separated by semicolons. (Metafield Updater output only.)
`Tags`	The full updated tag list for the product, comma-separated. (Tag Renamer output only.)

A note on Option1 Name and Option1 Value

For products that have no real variants — no size, no colour, no other selectable option — Shopify uses a placeholder variant with Option1 Name = Title and Option1 Value = Default Title. This is normal and expected. You should see these values in the vast majority of rows in the output CSV.

If you see different values (e.g. Option1 Name = Size), that product has real variants. This is also fine — it just means that product offers multiple options to customers.

These columns are included in the output to prevent Shopify from inadvertently removing a product's variants on import.

What to Check Before Importing

Open the downloaded CSV in a spreadsheet app and review the following before going back to Shopify:

Row count looks right. One row per product. If the log said 50 products were updated, expect 51 rows including the header.
Option1 Name reads Title. This should be true for most or all rows.
Option1 Value reads Default Title. Same — most or all rows should show this.
Handles look familiar. Spot-check a few against actual products in your Shopify admin. They should match the product URL slugs exactly.
Metafield values are correct. Pick a handful of products, look at their tags in Shopify, and verify the metafield column in the CSV reflects what you'd expect from the mapping.
No unexpected blank cells. Empty metafield cells are fine (Shopify leaves those fields untouched), but a blank Handle or blank Option1 Value would be a problem.

If anything looks wrong, do not import. Export a fresh product CSV from Shopify, compare it to the output, and get in touch for help.