Install
Install
Documentation

Metafield Definitions

Metafield Definitions

With the Matrixify app, you can bulk Export and Import Shopify Metafield Definitions – the definitions you see in Shopify Admin -> Settings -> Custom data.

A Metafield Definition is the template that Shopify uses for a Metafield. It sets which part of the store the Metafield belongs to (its Owner, for example Products), its namespace and key, its type, and the validation rules that every value has to follow. The Metafield Definitions sheet has one row per definition, so you can copy the definitions of one store to another store or edit many definitions at once.

The Metafield values are not in this sheet. They are exported and imported with the sheet of their entity, for example Products – see the Metafields documentation. Metaobject definitions have their own Metaobject Definitions sheet.

See what each column of the “Metafield Definitions” template means, including allowed values and examples. Columns marked as “Export Only” cannot be imported but can be exported with a Matrixify Export.

Excel Sheet Name

Metafield Definitions

When importing a file, the sheet/tab name tells the app that you are importing Metafield Definitions. The name can be in any letter case, with _ or - instead of the space, or with the last word singular, for example Metafield Definition or metafield_definitions.

  • If using a CSV file then the file name can be “my-shopify-metafield-definitions.csv”.
  • If using an XLSX file then the sheet/tab name would be set to “Metafield Definitions”. The file name for the XLSX file does not matter.

The sheet needs at least one of the columns ID, Handle or Name, otherwise it is not imported. If a sheet named “Metafield Definitions” has the columns of the Metafields sheet instead, the app reads it as a Metafields sheet.

Even if the sheet/tab name is not set correctly, you can manually change the entity of the sheet after uploading the file in the app.

See more on the Matrixify app Import process and Import user interface.

Need a quick start?

See Tutorials about Metafields.

Columns Available For Export And Import

Basic Columns

Column Description / Example Value
ID The ID is a Shopify automatically-generated internal ID number to identify the Metafield Definition. It is filled in by Export.
Can be used for Import to identify and update existing Metafield Definitions. If no definition has that ID, the app looks for it by Owner and Handle, so a file exported from another store still finds the definitions.
When importing new Metafield Definitions, leave this column empty.

Allowed Values

Number

Example
523457658947
Owner The part of the store the Metafield Definition is for. Owner and Handle together identify the definition. Required when creating a new definition.
When updating, the column can be empty – then the app looks for the Handle on every Owner and uses the definition when exactly one Owner has it.
Definitions of Transfers need the read_inventory_transfers access scope authorized in Matrixify Settings. Definitions of Locations are exported, but are changed only in Shopify Admin.

Allowed Values
Products
Variants
Collections
Customers
Orders
Draft Orders
Companies
Company Locations
Locations
Transfers
Pages
Blogs
Blog Posts
Markets
Shop
Example
Products
Handle The namespace and key of the definition joined by a dot. Together with Owner it identifies the definition.
When creating a new definition, you can fill Handle, or Namespace and Key – an empty Handle is built from them. If a filled Handle differs from them, the Handle is used.
The Handle of an existing definition cannot be changed.

Allowed Values

Text in the format namespace.key

Example
custom.material
Command When importing a Metafield Definition row – tell the app what to do with it:

  • NEW: will try to create a new Metafield Definition. If a definition with the same ID, or the same Owner and Handle, already exists, then the result will be Failed.
  • MERGE: will try to find the existing Metafield Definition and update it. If it is not found, then a new one is created.
  • UPDATE: will find the existing Metafield Definition and update it. If it cannot be found, then the row will be Failed.
  • REPLACE: will delete the existing Metafield Definition and create it again only from the data in the row. The delete works the same as for DELETE. If the app can tell that Shopify would refuse to create the definition again, for example because the row has no Handle or Namespace and Key, the row fails before anything is deleted.
  • DELETE: will delete the Metafield Definition, found by ID or by Owner and Handle. The Metafield values stay on the items, unless Delete Associated Metafields is TRUE. Definitions of reference types, such as product_reference, can only be deleted together with their values.
  • IGNORE: the app will skip this row.

If no Command is specified, then the app will assume the MERGE command.

Allowed Values
NEW
MERGE
UPDATE
REPLACE
DELETE
IGNORE
Default
MERGE
Example
MERGE
Name The name of the Metafield Definition as shown in Shopify Admin.
When ID, Handle, Namespace and Key are all empty, the app finds the existing definition by Name, ignoring letter case. If several definitions have that Name, the row fails.

Allowed Values

Text

Example
Material
Type The type of the Metafield values, with the same type names as in the Metafield columns of other sheets – see all Metafield types.
Shopify cannot change the type of an existing definition, so a different Type for an existing definition fails the row.

Allowed Values

Metafield type

Example
single_line_text_field
Description The description of the Metafield Definition as shown in Shopify Admin.

Allowed Values

Text

Example
Main fabric of the Product.
Namespace A logical container or group used to organize similar metafields or prevent naming conflicts.

It acts like a folder name. For custom fields you create in the Shopify admin, the default namespace is usually custom (e.g., custom.color for namespace.key value). Apps also use their own custom namespaces to store app-specific data without colliding with your fields.

Allowed Values

Text

Example
custom
Key The specific name or label of the individual data field within that namespace.

It identifies the exact piece of data you are storing. For example, in metafields handle custom.color, the value color is the key.

Allowed Values

Text

Example
material
Pinned Position Shows whether the definition is pinned in Shopify Admin. A number means the definition is pinned, an empty cell means it is not.
On Import a number pins the definition and an empty cell unpins it. The order of pinned definitions cannot be changed with an Import – only in Shopify Admin.

Allowed Values

Number or empty

Example
1
Usage Count

Export Only

 How many items have a value for this Metafield Definition. For example, a Products definition with a value on 12 Products has 12 in this column.

Allowed Values

Number

Example
12
Delete Associated Metafields Used with the DELETE and REPLACE commands. TRUE deletes the Metafield values of the definition together with it. An empty cell keeps the values on the items.
Definitions of reference types, such as product_reference, can only be deleted with TRUE.
The column is exported empty by default. In the Export setup you can customize it to Export TRUE on every row.

Allowed Values
TRUE

or empty

Default

empty

Example
TRUE
Row #

Export Only

 Will have row number from 1 till the end for each row. So that if you change the sorting in your exported file, you can sort it back by Row #. The Import ignores this column.

Allowed Values

Number

Options

The Options columns hold the API access settings and the capabilities of the Metafield Definition.

The TRUE / FALSE columns are always exported as TRUE or FALSE, so importing an exported file into another store also turns off there what is off in the source store. On Import, an empty cell leaves the setting as it is.

Shopify allows each capability only for some types and Owners. If a row turns on a capability that its Type and Owner do not take, the row fails before anything is sent to Shopify.

Column Description / Example Value
Option: Access to Storefront API Whether the Metafield values can be read through Shopify’s Storefront API.

Allowed Values
Public Read
None
Example
Public Read
Option: Access to Customer Account API Whether the Metafield values can be read or changed through Shopify’s Customer Account API.

Allowed Values
None
Read
Read Write
Example
Read
Option: Access to Admin API

Export Only

 The Admin API access of the Metafield Definition. The Import ignores this column.

Allowed Values

Text

Example
Public Read Write
Option: Usable in Collection Condition Turns on the Shopify capability to use the Metafield as a condition in automated Collections.

Allowed Values
TRUE
FALSE
Example
TRUE
Option: Filterable in Admin API Turns on Shopify’s admin filterable capability for the Metafield Definition.

Allowed Values
TRUE
FALSE
Example
FALSE
Option: Queryable in Analytics Turns on Shopify’s analytics queryable capability for the Metafield Definition.

Allowed Values
TRUE
FALSE
Example
FALSE
Option: Copy Values From Cart Metafield Turns on the Shopify capability to copy the value of the cart Metafield to the Order.

Allowed Values
TRUE
FALSE
Example
FALSE
Option: Assigned Categories The Product categories the Metafield Definition is assigned to. In Shopify Admin these Metafields show in the Category Metafields card of the Product. Shopify takes a value of this Metafield only for Products whose Category is one of the assigned categories.
A category ID followed by a space and * means that category and every category under it. The Export writes the shortest list: when a category is assigned together with all its subcategories, only that category is written, with *.
On Import, a category can also be written as GID, as ID | path, as the full path or as the name, each with * when needed. A long list can exceed the 32,767 character limit of an Excel cell – such a file should not be saved in Excel before importing it back.

Allowed Values

Category IDs separated by a comma, each optionally followed by *

Example
aa-1-13 *, aa-2-17

Validations

The Validations columns hold the rules that every Metafield value of the definition has to follow. Which columns apply depends on the Type – for example Validation: Choices applies to single_line_text_field and Validation: Allowed Domains to url.

The column names are close to the labels in Shopify Admin. See the Shopify list of validation options for which validation each type takes.

Column Description / Example Value
Validation: Min The minimum value. Depending on the type, it is the minimum text length, number, date, date and time, or the minimum weight, volume or dimension with its unit. For a rating, Validation: Min and Validation: Max are the scale.

Allowed Values

Number, date, or number with unit

Example
1 kg
Validation: Max The maximum value, in the same format as Validation: Min.

Allowed Values

Number, date, or number with unit

Example
100 kg
Validation: Precision The maximum number of decimal places stored for a number_decimal value.

Allowed Values

Number

Example
2
Validation: Regex A regular expression that text values have to match. Shopify supports RE2 syntax.

Allowed Values

Text

Example
^[0-9]+$
Validation: Choices The predefined values allowed for a single_line_text_field, separated by a comma. Shopify allows up to 128 choices.

Allowed Values

Text values separated by a comma

Example
Small, Medium, Large
Validation: Allowed Domains The domains allowed in a url value, separated by a comma.

Allowed Values

Domains separated by a comma

Example
example.com, shopify.com
Validation: File Types The file types allowed in a file_reference value. An empty cell allows all files.

Allowed Values
Image
Video

or both, separated by a comma

Example
Image, Video
Validation: List Min The minimum number of items in a list type value.

Allowed Values

Number

Example
1
Validation: List Max The maximum number of items in a list type value.

Allowed Values

Number

Example
5
Validation: Metaobject Definitions The Type of the Metaobject definition that a Metaobject reference has to point to. A metaobject_reference takes one Type, a mixed_reference can take several, separated by a comma.
The Export writes the Type, not the ID, so the value works in another store too.

Allowed Values

Metaobject definition Types separated by a comma

Example
shopify--color-pattern
Validation: JSON Schema The JSON format that a json value has to follow.

Allowed Values

JSON schema

Example
{"type":"object","properties":{"size":{"type":"string"}},"required":["size"]}
Validation: Product Taxonomy Attribute The Product taxonomy attribute that a product_taxonomy_value_reference value has to point to.

Allowed Values

Text

Example
color
Validation: Unique Values Turns on Shopify’s unique values capability, so every value of this Metafield Definition has to be different.

Allowed Values
TRUE
FALSE
Example
FALSE

Export Filters

In the Matrixify app, you can apply filters to Export only specific Metafield Definitions. When creating a new Export, select the Metafield Definitions sheet, and under it click on the Filters button.

Filter Description
Owner Allows you to select one or more Owners to Export only their Metafield Definitions, for example only Products and Variants.

Possible Conditions
  • Products
  • Variants
  • Collections
  • Customers
  • Orders
  • Draft Orders
  • Companies
  • Company Locations
  • Locations
  • Transfers
  • Pages
  • Blogs
  • Blog Posts
  • Markets
  • Shop
Namespace Allows you to list specific namespaces to Export, separated by a comma.

Possible Conditions
  • equals to any of
  • starts with any of
Example
custom, my_fields
Key Allows you to list specific keys to Export, separated by a comma.

Possible Conditions
  • contains any of
  • equals to any of
  • not equal to any of
  • starts with any of
  • matches pattern
Example
material, color
Name Allows you to list specific Metafield Definition names to Export, separated by a comma.

Possible Conditions
  • contains any of
  • equals to any of
  • not equal to any of
  • starts with any of
  • matches pattern
Example
Material, Care guide

Good To Know

  • A row with the namespace and key of a Shopify standard definition, for example descriptors.subtitle, enables that standard definition in the store instead of creating a custom one.
  • App-owned definitions, created by other apps, are exported for reference. The Import fails these rows, and they still count towards the plan limit.
  • Metafields without definitions have no row in this sheet. They are exported in the Metafield columns of their entity sheet, for example Products.
  • When one file has both the Metafield Definitions and the Metaobject Definitions sheet, the Metaobject Definitions are imported first. The definition sheets are imported before the other sheets of the file, so the Metafields and Metaobjects in the same file can use the definitions it creates.
  • Each Export or Import job can have up to 10 Metafield Definitions on the Demo plan, 50 on Basic, 500 on Big and any number on Enterprise – see Pricing.
  • Metafield Definitions is a separate sheet in Settings > Sheet Permissions. If your store has customized Sheet Permissions, enable it there. Deleting a definition together with its values also needs the Import permission of the Owner’s sheet – see Sheet Permissions.
  • In an Excel Export the ID, Owner and Handle columns stay in view while you scroll to the right.

Frequently asked questions

How do I copy Metafield Definitions to another Shopify store?

Export the Metafield Definitions sheet from the source store and Import the file in the other store. Matrixify finds existing definitions by Owner and Handle, creates the missing ones and updates the rest. When your definitions reference Metaobjects, Export the Metaobject Definitions sheet in the same file – the app Imports it first, and references are written by Type, so they work in the new store.

Can I Import Metafield Definitions and Metafield values in the same file?

Yes. The app Imports the definition sheets before the other sheets of the file, so the Metafields and Metaobjects sheets in the same file already find the definitions that the file creates.

How do I Export all Metafield Definitions from Shopify?

In the Matrixify app Home create a new Export, select the Metafield Definitions sheet and the column groups you need, and press Export. You get the definitions of all Owners in one Excel or CSV file. Use the Export filters to get only some Owners or namespaces.

How do I edit Metafield Definitions in bulk?

Export the definitions, change the name, description, options, validations or Pinned Position in the spreadsheet, and Import the file back. The Handle and Type of an existing definition cannot be changed.

How do I assign Metafield Definitions to Product categories in bulk?

Fill the Option: Assigned Categories column with the category IDs and Import the file. One cell like aa-1-13 * assigns a category together with every category under it. In Shopify Admin the assigned Metafields then show in the Category Metafields card of Products in those categories.

How do I delete Metafield Definitions in bulk?

Set Command to DELETE on the rows to delete and Import the file. The Metafield values stay on the items, unless Delete Associated Metafields is TRUE – then the values are deleted together with the definition.

Start managing your Shopify data today!

Install
Excelify Facebook channel Excelify Twitter channel Excelify Youtube channel
Newsletter
Thank you for subscribing!
© 2026 Matrixify.app
Made in Latvia Latvia