Importing Metafield Definitions
The Metafield Definitions import creates and updates your store's metafield definitions — the schema that describes a metafield (its owner type, namespace, key, data type, validations, and pinned state), not the metafield values themselves (those are the separate Metafields import). Rows are matched by owner type + namespace + key, so running the same file twice updates the same definitions instead of erroring on duplicates.
This is the piece Matrixify leaves out — bring a store's whole custom-data schema across in one file, then import the values separately.
For the wizard itself — uploading, mapping, dry runs, schedules — see Importing into EcomSolo.
Columns
| Column | Notes |
|---|---|
| Owner type | Required. The resource the definition attaches to — PRODUCT, PRODUCTVARIANT, COLLECTION, CUSTOMER, ORDER, COMPANY, PAGE, BLOG, ARTICLE, SHOP, and so on. Case-insensitive; upper-cased automatically. |
| Namespace | The container grouping related definitions (e.g. specs). Leave it blank and it defaults to custom — the standard merchant namespace, editable in the admin. (Omitting a namespace entirely would file the definition under the app-reserved namespace, which is app-owned and hidden from the admin, so we never do that.) |
| Key | Required. The definition's key within its namespace (e.g. material). |
| Name | The human-readable display name. Required to create a definition. |
| Type | The metafield data type — e.g. single_line_text_field, number_integer, list.product_reference. Required to create; it can't be changed afterwards. |
| Description | Free-text description shown in the admin. |
| Pinned | true / false — whether the definition is pinned in the admin. Reconciled on every run (pins or unpins to match). |
| Use as collection condition | true / false — whether the definition can be used in automated collection rules. |
| Validations | Advanced validation rules as a JSON array of {name, value} objects, e.g. [{"name":"max","value":"15"}]. Round-trips from an EcomSolo export. Leave blank to leave validations untouched. |
| Delete all associated metafields | Delete only. true / false (default false). When deleting a definition, also erase all the metafield values that use it. Off by default, so deleting a definition orphans its values rather than wiping them. Required to be true when deleting $app-namespace definitions. |
Common export headers map automatically: Owner / Resource → Owner type,
Display name → Name, Type name → Type, Pin → Pinned.
How definitions are matched
Every row is matched to an existing definition by (owner type, namespace, key) in the target store:
- If a definition with that key exists, it is updated (name, description, validations, collection-condition flag) and its pinned state is reconciled.
- If no definition matches, a new one is created (needs Name + Type).
The dry run shows the create/update split before anything is written.
Operations
Pick the operation in Step 1. The default is Upsert — the behavior above.
- Create — only adds definitions. A row whose key already exists fails.
- Update — only changes existing definitions. A row whose key isn't found fails.
- Upsert — creates missing definitions, updates existing ones. The safe default.
- Delete — removes definitions by key (see below).
Pinning
The Pinned column drives the pinned state on every create/update run: set
true to pin the definition in the admin, false to unpin it. Leave the column
blank (or unmapped) to leave the current pin state alone.
Deleting definitions
Pick the Delete operation in Step 1 (permission-gated) and upload a file with just the identity columns — Owner type, Namespace, Key. Each is resolved to its definition and removed from Shopify. A key that matches no definition is skipped (a no-op), so re-running the same delete file is safe.
By default, deleting a definition keeps the metafield values that used it
(they become orphaned but are not erased). To also erase every associated value,
set Delete all associated metafields to true on the row. Deletion
permanently removes the definition from Shopify — it cannot be undone.
A ready-to-run delete sample lives at
features/importing/examples/metafield-definitions-delete-sample.csv — it
targets the same keys the upsert sample creates, so you can round-trip
create → delete:
OwnerType,Namespace,Key,DeleteAllAssociatedMetafields
PRODUCT,specs,material,
PRODUCT,specs,warranty_years,
COLLECTION,specs,featured,
CUSTOMER,custom,loyalty_tier,true
The last row also erases the values that used the definition. Keys that match no definition are skipped (safe).
Importing from another store
On the wizard's Source step, pick From another store to copy definitions from a connected store — no file needed. Owner type, namespace, key, type, validations, and pinned state come across, matched by the natural key. Combined with a schedule this becomes a recurring one-way schema sync.
Results and freshness
Definitions you create or update take effect in Shopify immediately, and EcomSolo's Metafield Definitions dashboard refreshes within seconds of the run.
Sample file
A ready-to-run sample lives at
features/importing/examples/metafield-definitions-sample.csv:
OwnerType,Namespace,Key,Name,Type,Description,Pinned,UseAsCollectionCondition,Validations
PRODUCT,specs,material,Material,single_line_text_field,,,,
PRODUCT,specs,warranty_years,Warranty (years),number_integer,Warranty length in years,false,false,"[{""name"":""min"",""value"":""0""},{""name"":""max"",""value"":""10""}]"
COLLECTION,specs,featured,Featured,boolean,Featured collection flag,true,false,
CUSTOMER,,loyalty_tier,Loyalty tier,single_line_text_field,Tier in the default namespace,false,false,
The four rows cover the cases: a minimal row (required fields only), a fully populated row with validations, a pinned collection-condition row, and a row in the default (blank) namespace. Dry run: will create 4 (or update for keys that already exist).
Troubleshooting
| Error in the report | What it means / what to do |
|---|---|
row requires an OwnerType | Every row needs an owner type (e.g. PRODUCT). |
row requires a Key | Every row needs the definition's key. |
row requires a Name / row requires a Type | Creating a definition needs both. Updates don't. |
definition '… …' already exists | You ran Create on a key that exists — use Update or Upsert. |
cannot update: no existing definition | You ran Update on a key that doesn't exist — use Create or Upsert. |
| A delete row reported skipped | No definition matched that key — nothing to delete (safe). |