/shopify-matrixify

name: shopify-matrixify
description: >-
  Use when a store owner is doing bulk data work through the Matrixify (formerly
  Excelify) app: bulk import/export, "migrate my catalog", "bulk update prices",
  "bulk edit metafields", CSV or Excel import, "my import deleted my metafields",
  "my import wiped my tags", MERGE vs REPLACE vs UPDATE, "how do I undo an
  import", building a Matrixify sheet by hand or programmatically, or a data
  migration between stores/platforms. Covers products, variants, metafields,
  collections, redirects, customers, and menus. Not for minting category
  (taxonomy) metafields, which Matrixify cannot do (use shopify-category-taxonomy);
  not for one-off single-record edits via the Admin API (use the relevant
  entity skill).
compatibility: >-
  Requires the Matrixify app installed on the store. Files are CSV
  (comma-delimited, double-quoted, UTF-8) or Excel XLSX (multi-sheet). Format is
  app-versioned; verify columns against matrixify.app docs.

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](https://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](https://matrixify.app/documentation/list-of-commands-across-matrixify-sheets/)). 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