shopify-matrixify

Shopify Matrixify

The bulk-data workhorse of the catalog-cleanup suite. Matrixify moves store data in and out as spreadsheets, so it is how you touch thousands of records at once instead of one at a time in the admin. Almost every destructive mistake here comes from one of two misunderstandings: what a blank cell means, and what omitting a row means. Internalize the safety doctrine below before you touch a production catalog.

Canonical docs: matrixify.app/documentation. This skill is the operational playbook the docs don't spell out.

Store access

Matrixify runs inside the store, not through the Admin API. You do the work in two places:

• The Matrixify app (Shopify admin → Apps → Matrixify): run Export to pull a sheet, run Import to push one. Every import shows an Analyze preview and, after it runs, an Import Results file.
• A spreadsheet you edit locally (Excel or any CSV editor) or generate with throwaway code.

No token lives in this skill. To verify a write landed, re-export the affected records and inspect the cells, or read them back through the Admin API: the storefront is CDN-cached and lies about freshness.

Safety doctrine

Read this section twice. Every rule here was learned by someone breaking a live store.

1. Back up first: the export IS the backup. Before any bulk write, run a full export of the entity you're about to touch (Products, Collections, etc.) and save the file. If the import goes wrong, that export is your restore path. There is no "undo import" button.
2. MERGE is the default and it is safe. An empty Command cell defaults to MERGE (except Orders/Draft Orders, which default to NEW). MERGE updates rows that exist, creates rows that don't, and leaves untouched anything you didn't put in the file. Stay on MERGE unless you have a specific reason not to.
3. A blank cell in an import DELETES that value: it does not skip it. This is the single most expensive trap in Matrixify. If your sheet has a Metafield: custom.care [multi_line_text_field] column and a product's cell is empty, the import writes empty, wiping the existing metafield. Same for any field: blank Body HTML clears the description, blank Vendor errors out. Only include columns you intend to change. The fix is column omission, not blank cells. Absent column = untouched; present-but-blank column = deleted.
4. REPLACE is destructive by definition. REPLACE deletes the existing record (or nested set: variants, images, tags) and recreates it from only what's in the file. Anything not in the file is gone. Reach for REPLACE only when you truly want the file to be the complete new truth, and back up first.
5. Omitting a row does NOT revert a prior import. Dropping a handle from your next file doesn't undo what a previous import did to it. Matrixify only acts on rows present in the current file; it has no memory of the last run. To reverse a change you must import a new file that explicitly sets the old values back.
6. Sub-command MERGE ≠ entity MERGE. Setting the entity Command to MERGE does not by itself govern tags, images, or variants. Those have their own command columns (Tags Command, Image Command, Variant Command), each of which defaults to MERGE when absent (per the matrixify.app docs). MERGE is the safe default, but state it anyway: always pair a Tags column with an explicit Tags Command so the intent (add vs. REPLACE the exact list vs. DELETE listed) is unambiguous on the sheet rather than relying on the default.

Row identification and adjacency

Matrixify decides which rows belong to the same record by matching, in priority order: ID (Shopify numeric), then Handle if ID is blank, then Title if both are blank. Prefer ID or Handle; Title matching is fragile.

Rows for one record must be adjacent. When the ID/Handle/Title in a row differs from the row above, Matrixify treats it as a new record. A multi-variant product with its variant rows scattered across the file gets split into broken fragments. Always sort the file by Handle (or ID) so every record's rows sit together. A row is treated as a variant row when any Variant … or Option … column is filled; a row is treated as an image row when Image Src is filled.

Commands

Set per row in the Command column.

Command	Behavior
(empty)	MERGE (except Orders/Draft Orders → NEW)
NEW	Create; fails if the ID/Handle already exists
MERGE	Update if present, create if not. Safe default.
UPDATE	Update existing only; fails if not found
REPLACE	Delete and recreate from file data only. Destructive.
DELETE	Delete the record; fails if not found
IGNORE	Skip the row entirely (keep context rows in your sheet)

Nested data has its own command columns, same verbs, scoped to the nested set:

• Tags Command (products, customers, orders, blog posts): MERGE adds, DELETE removes listed, REPLACE sets the exact list.
• Image Command (products): MERGE adds, DELETE removes listed, REPLACE keeps only the file's images.
• Variant Command (products): MERGE / UPDATE / DELETE / REPLACE across the variant set. When updating existing variants, include Variant ID or Matrixify may create duplicates instead of updating.
• Product: Command (custom collections): MERGE adds products to the collection, DELETE removes them, REPLACE sets the exact membership.

Generating sheets programmatically

When you write a CSV in code instead of editing Excel by hand:

1. Double-quote every value; comma delimiter; UTF-8.
2. First row is the header with exact Matrixify column names (case- insensitive, order-independent, unknown columns silently ignored).
3. Include only the columns the operation touches: this is your primary guard against the blank-cell-deletes trap.
4. Sort rows by Handle/ID so multi-row records are adjacent; repeat the Handle on each variant/image row of the same product.
5. Default Command to MERGE; pair any Tags column with an explicit Tags Command.
6. Name the file so it contains the entity: products-update.csv, redirects.csv. A file named data.csv may not be recognized as Products.
7. Metafield headers use the full form Metafield: namespace.key [type]; set the metafield definition in Settings → Custom Data before importing, or the values land "without definition."

Worked examples

Add a tag to products without wiping existing tags (note: no other product columns, so nothing else is touched):

"Handle","Tags","Tags Command"
"summer-hat","clearance","MERGE"
"winter-hat","clearance","MERGE"

Set one product metafield across many rows (definition must already exist):

"Handle","Metafield: custom.care_instructions [multi_line_text_field]"
"linen-shirt","Machine wash cold. Line dry."
"wool-scarf","Hand wash only. Lay flat to dry."

Bulk 301 redirects after a URL restructure (one entity, two columns):

"Path","Target"
"/collections/old-name","/collections/new-name"
"/products/discontinued-item","/collections/replacements"

Sibling skills

• shopify-category-taxonomy: Matrixify cannot mint category (taxonomy / "Category metafields") values; those are reserved metaobjects set via the Admin API. Route any taxonomy-attribute rollout there.
• Single-record edits (one product, one redirect) don't need a sheet: use the admin UI or the relevant entity skill's Admin API recipe.

References

• references/column-reference.md: full column schemas per entity: products, variants, metafields, collections, redirects, customers, menus.

Provenance and maintenance

Last verified: 2026-07-05. The Matrixify sheet format is app-versioned: the vendor adds columns and adjusts behavior across releases, so treat any specific column name or default here as needing confirmation against the current matrixify.app documentation before you rely on it. Read-only re-verification a stranger can run:

• Open matrixify.app/documentation/products and matrixify.app/documentation/list-of-commands-across-matrixify-sheets and confirm the command verbs and column names still match this skill.
• In any store with Matrixify installed, run Export for a single small entity (a handful of products), open the resulting sheet, and inspect the actual column headers and command columns: the export is always authoritative for that store's current format.

This skill captures operational lessons the vendor docs don't stress; it is not a replacement for them.