How to bulk import Shopify Metaobject Entries

Metaobjects are custom data structures in Shopify, and each Metaobject entry holds the values for the fields of its Metaobject Definition, for example one entry per manufacturer with its name and website. Here we will create Metaobject entries in bulk by Importing them from an Excel file with Matrixify, together with their Metaobject Definitions if the store does not have them yet.

Let’s dive in!

Steps in short to bulk import Shopify Metaobject entries

1. Set up the Metaobject Definitions in Shopify Admin, or Import them in bulk with the Matrixify Metaobject Definitions sheet.
2. Prepare your Excel import file with the necessary columns in the Matrixify Metaobject template.
3. Import Metaobjects into your Shopify store with the Matrixify app.

1. Set up Metaobject Definitions

Each Metaobject entry is linked to a specific Metaobject Definition, so the definitions need to exist in the store before you Import the entries. Note that the types you set in the definition fields will change how the values are written in the Metaobject entries.

You can create the Metaobject Definitions one by one in your Shopify Admin -> Settings -> Custom Data section, with the fields and their types as you need, or Import definitions with Matrixify as shown below.

You can see Shopify Metaobject manuals for more details about how to set up definitions, what types you might need, and other data.
It is important to first understand what fields and types you need and only then import your entries.

For this example, we will create the Metaobject Definition “Manufacturer” with two fields: “Name” as Single line text type and “Website” as URL type.

Import Metaobject Definitions in bulk

When you need many definitions, or the same definitions as in another store, you can Import them with the Matrixify Metaobject Definitions sheet. It has one row per field of a definition, so the “Manufacturer” definition takes two rows.

Minimum columns to create a new Metaobject Definition are:

• Type – unique identifier of the definition, the same in all rows of the definition, for example manufacturer,
• Field: Key – key of the field, for example name or website,
• Field: Type – type of the field, for example single_line_text_field or url, see all Metafield types.

Add also the Name and Field: Name columns to set the names you will see in Shopify Admin, such as “Manufacturer” and “Website”. Without them, the app uses the Type and Field: Key values as the names.

The Metaobject Definitions sheet can also be in the same file as the Metaobjects sheet with your entries. The app imports the definition sheets before the other sheets of the file, in any sheet order, so the entries already find their new definition.

Export the Metaobject Definitions sheet to see the definitions you already have in your Shopify store.

Once you have definition/s set up, we can move into creating an import file.

2. Prepare your Metaobject entries import file

To create your Metaobject entries import file first download the Matrixify Metaobjects demo template file.
In this file, you see one example, with only fields that are required for this import.

Now you can start filling in the file with your own data.

Data structure

The structure of the file is simple – for each entry, you need to have as many rows as there are fields set up in the definition.
Our example definition had two fields, then the import file also will have two rows per entry.

As an example, we will import 10 entries. In the file, we will have 20 rows filled with Metaobject entry data + 1 row for the column headers.

Filling in your own data

From there we can now fill data in Command, Status, Definition: Handle and Field columns (See Matrixify Metaobjects documentation page where each column from our template is explained).

• Command column would be set to value MERGE as the default value.
• Status would be set to Active as we want for all those definitions to already be active.
• Definition: Handle would be filled in all rows to the value that is linked to the entries. You can find this value in the Metaobject Definition under “Name” section, field called “Type”, or in the Type column of the Metaobject Definitions sheet. In our example, the definitions handle will be manufacturer.
• Field column would have both fields listed repeating so that both rows from the same entry are next to each other.

Then we can fill in the data for the Handle and Value columns.

In the Handle column, you need to set what will be the entry’s unique identifier.
Shopify by default will set the Handle and Display name from the value filled in the field that is assigned as “Display name” in the Metaobjects definition.

In our example, this is the Name field so let’s fill the Handle columns with manufacturer names.
Note that in the Handle column, you cannot have special characters or spaces. If you see the error, Handle is invalid returned when importing, then likely you have some special characters or spaces left in the Handle for that Metaobject entry.

For the Value column we need to fill in the actual values for each Shopify Metaobject entry:

Once you have your data filled in the file, you need to do a last step before importing – making sure that sheet name is set correctly.

If using Demo file as per this tutorial, then sheet/tab name in the Excel file should already be Metaobjects.
If using CSV file, then make sure that file name contains word “metaobjects”.

This will help the app to correctly detect the import as a Metaobject entity sheet. In case you use a different name, you might need to re-select the correct entity Metaobjects and re-analyze the uploaded file.

3. Import Shopify Metaobject entries

Now that file is set up, go into the Matrixify app in your Shopify store.

In the app Home page Import section, you can upload your file.
Wait for the app to analyze the file’s data and ensure that app correctly detected the import as Metaobjects and that the Metaobject entry count is correct.

If all looks correct, press the “Import” button and start the import.
Once your import is finished, head into your Shopify Admin -> Content -> Metaobjects section and enjoy your newly bulk-created Metaobject entries.

Good to know

• If you see errors returned for your Metaobject entries in the import file, you can download the Import Results file and in it see an exact error message and for what Metaobject is the error. Fix the issue in the same Results file and import back to update those that imported and create those that did not.
• When importing Metaobject entries with fields that are reference type (product reference, variant reference, etc.) – we check if this reference already exists in your store. If that does not exist, we assume that it will probably be imported later with the other sheets in the same file. So we automatically generate a new sheet “Generated Metaobjects” and add those Metaobject entries as rows to that new sheet. When all the other sheets are imported, then we again import the Generated Metaobjects sheet, with the assumption that now when all the data is imported, we will find those references for those particular Metaobject entries. This feature allows you to properly migrate Metaobjects between different Shopify stores, including Metaobject entries with reference type fields.
• With Matrixify you can also migrate or clone Metaobjects together with their Metaobject Definitions to another Shopify store. Export the Metaobject Definitions and Metaobjects sheets from one store and Import the file into the other store. The app Imports the Metaobject Definitions first, and references to other Metaobject Definitions are written by their Type, so they work in the new store. See how to clone a Shopify store.
• If your Metaobject entry Import has an error “Capability is not enabled: publishable”, it means that you are importing Status column value, but the Metaobject Definition has “Active-draft status” option disabled. To resolve the issue either ensure that the Status column is not in the Import file or has an empty value, or enable the “Active-draft status” option for the Metaobject Definition in Shopify Admin. In the Metaobject Definitions sheet this option is the Option: Publishable column, and TRUE enables it.
• In Shopify, you can use Metafields, instead of Metaobjects, to save your custom data at an item level. See our Tutorial on how to bulk manage Shopify Metafields.