Shopify Metaobject Definitions Import/Export

With the Matrixify app, you can bulk Export and Import Shopify Metaobject Definitions – the definitions you set up in Shopify Admin -> Settings -> Custom data. A Metaobject Definition is the group of fields that defines the structure of the Metaobject entries, for example a Designer with a name, a photo and a website.

Export the Metaobject Definitions sheet to get the definitions of a store in one Excel or CSV file, Import it into another store to copy them, or add fields and change options and validations for many definitions in the spreadsheet and Import the file back.

A Metaobject Definition takes one row per field: the first row describes the first field, the next row the second field, and so on. The ID, Type, Name and Option: columns repeat on every row of the definition. The Metaobject entries themselves are exported and imported with the Metaobjects sheet, and Metafield definitions with the Metafield Definitions sheet.

See what each column of the “Metaobject 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

Metaobject Definitions

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

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

The sheet needs at least one of the columns ID, Type or Name, otherwise it is not imported.

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?

Download the Metaobject Definitions Demo Import file.

See Tutorials about Metaobjects.

Columns Available For Export And Import

Basic Columns

The rows of one Metaobject Definition follow each other in the file. The app reads consecutive rows with the same ID, or else the same Type, or else the same Name, as one definition. A row with ID, Type and Name all empty continues the definition above it.

Column Description / Example Value

Column	Description / Example Value
ID	The ID is a Shopify automatically-generated internal ID number to identify the Metaobject Definition. It is filled in by Export. Can be used for Import to identify and update existing Metaobject Definitions. If no definition has that ID, the app looks for it by `Type`, so a file exported from another store still finds the definitions. When importing new Metaobject Definitions, leave this column empty. Allowed Values Number Example 37701124163
Type	The unique identifier of the Metaobject Definition, shown as Type in Shopify Admin. It is the value the `Definition: Handle` column of the Metaobjects sheet uses. Required when creating a new definition. The Type of an existing definition cannot be changed. Allowed Values Text Example designer
Command	When importing a Metaobject Definition – tell the app what to do with it: `NEW`: will try to create a new Metaobject Definition. If a definition with the same `ID` or `Type` already exists, then the result will be Failed. `MERGE`: will try to find the existing Metaobject Definition and update it. If it is not found, then a new one is created. Fields that are in the file are added or updated, fields that the file leaves out are kept. `UPDATE`: will find the existing Metaobject Definition and update it the same way as `MERGE`. If it cannot be found, then the rows will be Failed. `REPLACE`: will delete the existing Metaobject Definition and create it again only from the rows in the file. The delete works the same as for `DELETE`. A definition that has entries cannot be replaced – change it with `MERGE`, or delete it with `DELETE` and Import it with `NEW` a few minutes later. `DELETE`: will delete the Metaobject Definition, found by `ID` or `Type`. Shopify deletes its entries together with it, and also the Metafield definitions that reference it, with their values. `IGNORE`: the app will skip this definition. 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 Metaobject definition as shown in Shopify Admin. When `ID` and `Type` are 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 Designer
Description	The description of the Metaobject Definition. The Export writes it on the first row of the definition only. Allowed Values Text Example Designers of our Products.
Updated At *Export Only*	Date and time in the store’s timezone when the Metaobject Definition was last updated. Every `MERGE` or `UPDATE` Import of the definition changes it, even when no value is different. Allowed Values Date & Time Example 2026-11-02 16:55:50 +0200
Usage Count *Export Only*	The number of Metaobject entries of this definition. Allowed Values Number Example 12
Top Row *Export Only*	It will have value `TRUE` for the first row of each Metaobject Definition. That can help you filter in Excel to get one row per definition. Allowed Values TRUE FALSE
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 rows of a definition need to stay together. The Import ignores this column. Allowed Values Number

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

Allowed Values

Number

Example

37701124163

Type

The unique identifier of the Metaobject Definition, shown as Type in Shopify Admin. It is the value the Definition: Handle column of the Metaobjects sheet uses.
Required when creating a new definition. The Type of an existing definition cannot be changed.

Allowed Values

Text

Example

designer

Command

When importing a Metaobject Definition – tell the app what to do with it:

NEW: will try to create a new Metaobject Definition. If a definition with the same ID or Type already exists, then the result will be Failed.
MERGE: will try to find the existing Metaobject Definition and update it. If it is not found, then a new one is created. Fields that are in the file are added or updated, fields that the file leaves out are kept.
UPDATE: will find the existing Metaobject Definition and update it the same way as MERGE. If it cannot be found, then the rows will be Failed.
REPLACE: will delete the existing Metaobject Definition and create it again only from the rows in the file. The delete works the same as for DELETE. A definition that has entries cannot be replaced – change it with MERGE, or delete it with DELETE and Import it with NEW a few minutes later.
DELETE: will delete the Metaobject Definition, found by ID or Type. Shopify deletes its entries together with it, and also the Metafield definitions that reference it, with their values.
IGNORE: the app will skip this definition.

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 Metaobject definition as shown in Shopify Admin.
When ID and Type are 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

Designer

Description

The description of the Metaobject Definition. The Export writes it on the first row of the definition only.

Allowed Values

Text

Example

Designers of our Products.

Updated At

Export Only

Date and time in the store’s timezone when the Metaobject Definition was last updated. Every MERGE or UPDATE Import of the definition changes it, even when no value is different.

Allowed Values

Date & Time

Example

2026-11-02 16:55:50 +0200

Usage Count

Export Only

The number of Metaobject entries of this definition.

Allowed Values

Number

Example

Top Row

Export Only

It will have value TRUE for the first row of each Metaobject Definition. That can help you filter in Excel to get one row per definition.

Allowed Values

TRUE
FALSE

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 rows of a definition need to stay together. The Import ignores this column.

Allowed Values

Number

Options

The Options columns hold the settings of the whole Metaobject Definition – the access settings and the options from Shopify Admin, such as Active-draft status, Translations and web pages. See the Shopify manual on custom data options.

The Export writes the Options columns on every row of a definition, so an Excel filter on any of them shows all rows of the definition. On Import, the app reads them from the first row: leave the other rows empty or give them the same value, otherwise the definition fails.

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.

Column	Description / Example Value
Option: Access to Storefront API	Whether the Metaobject entries can be used in the Online Store, through Liquid or the Storefront API. Allowed Values Public Read None Example Public Read
Option: Access to Customer Account API	Whether the Metaobject entries can be read through Shopify’s Customer Account API. Allowed Values Read None Example None
Option: Access to Admin API *Export Only*	The Admin API access of the Metaobject Definition. The Import ignores this column. Allowed Values Text Example Public Read Write
Option: Publishable	The Active-draft status option: `TRUE` lets entries be Active or Draft. When it is off, importing the `Status` column on the Metaobjects sheet fails for this definition. Allowed Values TRUE FALSE Example TRUE
Option: Translatable	The Translations option: `TRUE` lets the entries be translated into other languages. Allowed Values TRUE FALSE Example TRUE
Option: Online Store URL Handle	The URL handle under which the entries are published as web pages in the Online Store. It is exported only when the definition is published to the Online Store. Shopify needs `Option: Access to Storefront API` set to `Public Read` for web pages. On Import, a filled cell publishes the entries under that URL handle or changes it. An empty cell turns the web pages off. If the file has no such column, the setting is left as it is. When an Import changes the URL handle, the Import option `Generate Redirects if changing Handles` decides whether the old URLs of the published entries are redirected. Allowed Values Text Example designers
Option: Renderable	Turns on Shopify’s renderable capability for the Metaobject Definition. Allowed Values TRUE FALSE Example TRUE
Option: Renderable Meta Title Field	The `Field: Key` of the field used as the meta title of the entry pages. Allowed Values Field key of the definition Example name
Option: Renderable Meta Description Field	The `Field: Key` of the field used as the meta description of the entry pages. Allowed Values Field key of the definition Example summary
Option: Field for Display Name	The `Field: Key` of the field that Shopify uses as the display name of the entries. An empty cell sets the display name to Auto-generated. If the file has no such column, the setting is left as it is. Allowed Values Field key of the definition, or empty Example name

Fields

Each row of a Metaobject Definition describes one field. On a new definition, the fields are created in the order of the rows. On an existing definition, a row with a new Field: Key adds that field, and fields that the file leaves out are kept.

Column	Description / Example Value
Field: Position *Export Only*	The position of the field in the definition, from 1. The Import ignores this column. Allowed Values Number Example 1
Field: Key	The key of the field. It identifies the field within the definition and is the value of the `Field` column on the Metaobjects sheet. Allowed Values Text Example website
Field: Name	The name of the field as shown in Shopify Admin. Allowed Values Text Example Website
Field: Description	The description of the field. Allowed Values Text Example Link to the designer's own website.
Field: Type	The type of the field values, with the same type names as Metafields – see all Metafield types. A `metaobject_reference` field points to entries of another Metaobject Definition, set in `Field Validation: Metaobject Definitions`. Allowed Values Metafield type Example url
Field: Required	`TRUE` makes the field required, so every entry needs a value in it. Allowed Values TRUE FALSE Example TRUE
Field: Filterable	`TRUE` lets the field be used as a filter in the Metaobject index in Shopify Admin. If Shopify reports that an existing field cannot be filterable, the row fails before anything is sent to Shopify. Allowed Values TRUE FALSE Example FALSE

Field Validations

The Field Validations columns hold the rules that the values of a field have to follow. Which columns apply depends on the Field: Type – for example Field Validation: Choices applies to single_line_text_field. See the Shopify list of validation options.

Column	Description / Example Value
Field 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. Allowed Values Number, date, or number with unit Example 2
Field Validation: Max	The maximum value, in the same format as `Field Validation: Min`. Allowed Values Number, date, or number with unit Example 255
Field Validation: Precision	The maximum number of decimal places stored for a `number_decimal` value. Allowed Values Number Example 2
Field Validation: Regex	A regular expression that text values have to match. Shopify supports RE2 syntax. Allowed Values Text Example ^[A-Za-z ]+$
Field 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 Latvia, Estonia, Lithuania
Field 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
Field 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
Field Validation: List Min	The minimum number of items in a list type value. Allowed Values Number Example 1
Field Validation: List Max	The maximum number of items in a list type value. Allowed Values Number Example 5
Field Validation: Metaobject Definitions	The Type of the Metaobject Definition that a Metaobject reference field has to point to. A `mixed_reference` field 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 designer
Field 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"]}
Field Validation: Product Taxonomy Attribute	The Product taxonomy attribute that a `product_taxonomy_value_reference` value has to point to. Allowed Values Text Example color

Export Filters

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

Filter Description

Filter	Description
Type	Allows you to list specific Metaobject Definition Types 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 designer, faq
Name	Allows you to list specific Metaobject 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 Designer, FAQ

Type

Allows you to list specific Metaobject Definition Types 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

designer, faq

Name

Allows you to list specific Metaobject 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

Designer, FAQ

Good To Know

Importing Metaobject Definitions needs the write_metaobject_definitions access scope. If your store has not approved it yet, approve the “Update Shopify API Permissions” banner in the Matrixify app, or authorize it in Matrixify Settings -> Shopify API Access Scopes.
When one file has both the Metaobject Definitions and the Metafield Definitions sheet, the Metaobject Definitions are imported first. The definition sheets are imported before the other sheets of the file, so the Metaobjects in the same file can use the definitions the file creates.
Definitions that reference each other, for example Author and Book, are imported together: the app creates them first and adds the reference fields after that.
Shopify standard Metaobject Definitions, such as shopify--color-pattern, are enabled instead of created.
App-owned definitions, created by other apps, are exported for reference. The Import fails these rows, and they still count towards the plan limit.
Each Export or Import job can have up to 10 Metaobject Definitions on the Demo plan, 50 on Basic, 500 on Big and any number on Enterprise – see Pricing.
Metaobject Definitions is a separate sheet in Settings > Sheet Permissions. If your store has customized Sheet Permissions, enable it there. Deleting a Metaobject Definition also needs the Import permission of the Metaobjects sheet – see Sheet Permissions.
In an Excel Export the ID and Type columns stay in view while you scroll to the right.

Frequently asked questions

How do I copy Metaobject Definitions to another Shopify store?

Export the Metaobject Definitions sheet from the source store and Import the file in the other store. Matrixify finds existing definitions by Type, creates the missing ones and adds missing fields to the rest. References to other Metaobject Definitions are written by Type, so they work in the new store.

Can I Import Metaobject Definitions and entries in the same file?

Yes. Put the Metaobject Definitions sheet and the Metaobjects sheet in one file. The app Imports the definitions first, so the entries find the definitions that the same file creates.

How do I add fields to Metaobject Definitions in bulk?

Import a row for each new field with the definition’s Type, the new Field: Key, Field: Name and Field: Type, and the MERGE command. The existing fields stay as they are, so the file needs only the new rows.

How do I publish Metaobject entries as web pages with Matrixify?

Fill Option: Online Store URL Handle with the URL handle, for example designers, and Import the file. The app publishes the entries of the definition as web pages under that handle. An empty cell turns the web pages off again.

How do I delete Metaobject Definitions in bulk?

Set Command to DELETE on one row of each definition and Import the file. Shopify deletes the entries of the definition together with it, and the Metafield definitions that reference it.

What is the difference between Metafield and Metaobject Definitions?

A Metafield definition adds one field to an Owner, such as a Material field on every Product. A Metaobject Definition describes a store-level object with several fields, such as a Designer, and Metafields can reference its entries. In Matrixify, Metafield definitions have one row each, and Metaobject Definitions one row per field.