Metafields - Matrixify App

Metafields for Import and Export

Shopify Metafields are available as additional columns in the following Excel sheets or CSV files:

For Metafield that is set up as a definition to show up in the exported file, make sure that the value in it is set for at least one of the exported items.

Column Names

Metafield column headers are constructed in the following template: Metafield: namespace.key [type].
The column will start with Metafield: except for Variant Metafields where it will start with Variant Metafield: .

Namespace and key

After this, the column header will have the namespace.key combination which is used to identify the Metafield that is being imported.

If Metafield definitions have been set up in the store, then you can see the Metafields namespace and key in that definition:

If there is no namespace defined in the column header, then the global namespace is used.

You can have almost unlimited Metafields per item – just add them as additional columns.
If there is a dot already in Metafields namespace or key then in the exported and import files it is escaped with a backslash: \..

Metafield type

The last part of the Metafield column header is the Metafield type. It is always set in square brackets [].
You can also import Metafield column without the type specified. In that case, Matrixify app will try to find a definition with that namespace and key and assume the type from it.

When exporting Metafields – in Excel those types will be reflected as cell value types. If the value is a number_integer type, then in the Excel cell that will also be visible as an integer. And if that’s a single_line_text_field, then, of course, it will also be visible as a text type, even if it will contain a numeric value.

Example columns headers with specified types:

for number_integer: Metafield: specs.mu_number [number_integer]
for boolean: Metafield: specs.is_it_cool [boolean]
for product_reference: Metafield: specs.other_products [product_reference]
etc…

Each Metafield for each item can have one of the types:

List of Metafield Types

We have complied a list of all Metafield types to see what is correct type to use in the import file and example of the value that would need to be set to import.

You can also see Shopify Metafields manual page for metafield type descriptions.

Date and Time

Type	Description / Example Value
date	A date in ISO 8601 format without a presumed timezone. Allowed Values Date Example 2021-10-25
date_time	A date and time in ISO 8601 format without a presumed timezone. Allowed Values Text Example 2021-10-25T14:30:00

Type

Description / Example Value

date

A date in ISO 8601 format without a presumed timezone.

Allowed Values

Date

Example

2021-10-25

date_time

A date and time in ISO 8601 format without a presumed timezone.

Allowed Values

Text

Example

2021-10-25T14:30:00

Measurement

Type	Description / Example Value
weight	A value and a unit of weight. Valid unit values: `oz`, `lb`, `g`, `kg` Allowed Values JSON Example { "unit": "kg", "value": 2.5 }
list.weight	A laist of value and a unit of weight combinations in JSON format. Valid unit values: `oz`, `lb`, `g`, `kg` Allowed Values JSON Example [{"value":1100.0,"unit":"g"},{"value":600.0,"unit":"kg"}]
volume	A value and a unit of volume. Valid unit values: `ml`, `cl`, `l`, `m3` (cubic meters), `us_fl_oz,` `us_pt`, `us_qt`, `us_gal`, `imp_fl_oz`, `imp_pt`, `imp_qt`, `imp_gal`. Allowed Values JSON Example { "unit": "ml", "value": 20.0 }
list.volume	A list of values and a unit of volume combinations in JSON format. Valid unit values: `ml`, `cl`, `l`, `m3` (cubic meters), `us_fl_oz,` `us_pt`, `us_qt`, `us_gal`, `imp_fl_oz`, `imp_pt`, `imp_qt`, `imp_gal`. Allowed Values JSON Example [{"value":1.0,"unit":"ml"},{"value":0.001,"unit":"l"}]
dimension	A value and a unit of length. Valid unit values: `in`, `ft`, `yd`, `mm`, `cm`, `m` Allowed Values JSON Example { "unit": "cm", "value": 25.0 }
list.dimension	A list of value and a unit of length combinations in JSON format. Valid unit values: `in`, `ft`, `yd`, `mm`, `cm`, `m` Allowed Values JSON Example [{"value":1000.0,"unit":"mm"},{"value":54.0,"unit":"mm"}]

Number

Type	Description / Example Value
number_integer	A whole number in the range of from `-9007199254740991` till `9007199254740991`. Will round decimal numbers. Allowed Values Number Example 10
list.number_integer	A list of whole numbers in the range of from `-9007199254740991` till `9007199254740991`. In this field, you need to add a list of numbers in JSON format. Allowed Values Text Example [8,2,3]
number_decimal	A number with decimal places in the range from `-9999999999999.999999999` till `9999999999999.999999999`. Allowed Values Number Example 10.545
list.number_decimal	A list of numbers with decimal places in the range from `-9999999999999.999999999` till `9999999999999.999999999`. In this field, you need to add a list of numbers in JSON format. Allowed Values Text Example ["1.123","2.545","3.987"]

Reference

Type	Description / Example Value
product_reference	A reference to a product from this online store. In this field, you need to list the GID of your Product. You can construct the GID by exporting Products with the Matrixify app and combining text `gid://shopify/Product/` with the product ID from the exported file. Allowed Values Text Example gid://shopify/Product/4613633671235
list.product_reference	A reference to a product from this online store. In this field, you need to add a list of GIDs of your Products. You can construct the GID by exporting Products with the Matrixify app and combining text `gid://shopify/Product/` with the product ID from the exported file. Allowed Values Text Example ["gid://shopify/Product/4613633671235","gid://shopify/Product/2079945457731","gid://shopify/Product/1531574943811"]
collection_reference	A reference to a product from this online store. In this field, you need to list the GID of your Product. You can construct the GID by exporting Custom Collections or Smart Collections with the Matrixify app and combining text `gid://shopify/Collection/` with the collection ID from the exported file. Allowed Values Text Example gid://shopify/Collection/4613633671235
list.collection_reference	A reference to a product from this online store. In this field, you need to add a list of GIDs of your Collections. You can construct the GID by exporting Custom Collections or Smart Collections with the Matrixify app and combining text `gid://shopify/Collection/` with the collection ID from the exported file. Allowed Values Text Example ["gid://shopify/Collection/4613633671235","gid://shopify/Collection/2079945457731","gid://shopify/Collection/1531574943811"]
variant_reference	A reference to a product variant from this online store. In this field, you need to list the GID of your Product Variant. You can construct the GID by exporting Products with Variants with the Matrixify app and combining text `gid://shopify/ProductVaraint/` with the Variant ID from the exported file. Allowed Values Text Example gid://shopify/ProductVariant/39627628838979
list.variant_reference	A reference to a product from this online store. In this field, you need to add a list of GID of your Product Variants. You can construct the GID by exporting Products with Variants with the Matrixify app and combining text `gid://shopify/ProductVaraint/` with the Variant ID from the exported file. Allowed Values Text Example ["gid://shopify/ProductVariant/4613633671235","gid://shopify/ProductVariant/2079945457731","gid://shopify/ProductVariant/1531574943811"]
file_reference	A reference to a file from this online store. In this field, you need to list the GID of the File. You can get the File GID by exporting Files using the Matrixify app and copying it from the Files ID column. Allowed Values Text Example gid://shopify/GenericFile/21151855542339
list.file_reference	A reference to a file from this online store. In this field, you need to add a list of GID of your Files. You can get the File GID by exporting Files using the Matrixify app and copying it from the Files ID column. Allowed Values Text Example ["gid://shopify/GenericFile/4613633671235","gid://shopify/GenericFile/2079945457731","gid://shopify/GenericFile/1531574943811"]
metaobject_reference	A reference to a product from this online store. In this field, you need to list the GID of your MetaObject Entry. You can construct the GID by exporting MetaObjects with the Matrixify app and combining text `gid://shopify/Metaobject/` with the Metaobject entry ID from the exported file. Allowed Values Text Example gid://shopify/Metaobject/2927034435
list.metaobject_reference	A reference to a product from this online store. In this field, you need to list the GID of your MetaObject Entries. You can construct the GID by exporting MetaObjects with the Matrixify app and combining text `gid://shopify/Metaobject/` with the Metaobject entry ID from the exported file. Allowed Values Text Example ["gid://shopify/Metaobject/4613633671235","gid://shopify/Metaobject/2079945457731","gid://shopify/Metaobject/1531574943811"]
page_reference	A reference to a page from this online store. To reference page outside of this store, use the URL field. In this field, you need to insert the GID of your Page. You can construct the GID by exporting Pages with the Matrixify app and combining text `gid://shopify/OnlineStorePage/` with the page ID from the exported file. Allowed Values Text Example gid://shopify/OnlineStorePage/80516808771
list.page_reference	A reference to a page from this online store. To reference page outside of this store, use the URL field. In this field, you need to insert the GID of your Pages. You can construct the GID by exporting Pages with the Matrixify app and combining text `gid://shopify/OnlineStorePage/` with the page ID from the exported file. Allowed Values Text Example ["gid://shopify/OnlineStorePage/4613633671235","gid://shopify/OnlineStorePage/2079945457731","gid://shopify/OnlineStorePage/1531574943811"]
order_reference	A reference to order from this online store. In this field, you need to list the GID of your Order. You can construct the GID by exporting Order with the Matrixify app and combining text `gid://shopify/Order/` with the order ID from the exported file. Allowed Values Text Example gid://shopify/Order/4613631234535
customer_reference	A reference to a customer from this online store. In this field, you need to list the GID of your Customer. You can construct the GID by exporting Customer with the Matrixify app and combining text `gid://shopify/Customer/` with the customer ID from the exported file. Allowed Values Text Example gid://shopify/Customer/1234531234535

Text

Type	Description / Example Value
single_line_text_field	A single-line text field. Will not allow importing text with line breaks/newlines in it. Allowed Values Text Example This item contains dairy products.
list.single_line_text_field	A single-line text Metafield with “Accept list of values” selected in the definition. Will not allow importing text with line breaks/newlines in it. Allowed Values JSON array Example ["this","is","list", "with 4 list values"]
multi_line_text_field	A multi-line text field. Allowed Values Text Example Ingredients: Flour Water Milk Eggs
rich_text_field	Rich text field. Allowed Values JSON Example {"type":"root", "children":[{"type":"heading", "children":[{"type":"text", "value":"Text with formatting"}], "level":3}, {"type":"paragraph", "children":[{"type":"text", "value":"This is "}, {"type":"text", "value":"text with formatting", "italic":true}]}, {"type":"paragraph", "children":[{"type":"text", "value":"in multiple rows"}]}]}

Other

Type	Description / Example Value
color	The hexadecimal code for a color. Allowed Values Text Example #fff123
list.color	A list of hexadecimal codes for a color. Allowed Values JSON Example ["#44b144","#ff0000"]
money	Amount of money in specific currency. Allowed Values JSON Example {"amount":"15.0","currency_code":"EUR"}
rating	A rating measured on a set scale. Allowed Values JSON Example { "value": "3.5", "scale_min": "1.0", "scale_max": "5.0" }
boolean	A true or false value. Allowed Values TRUE FALSE Example TRUE
url	A URL with one of the allowed schemes: `https`, `http`, `mailto`, `sms`, `tel`. Allowed Values Text Example https://matrixify.app/

Advanced

Type	Description / Example Value
json	A JSON-formatted string. Allowed Values JSON Example [{ "k": "v1" }, { "k": "v2" }]
mixed_reference	Supports references of any type. Allowed Values Text Example gid://shopify/Customer/1234531234535

Type

Description / Example Value

json

A JSON-formatted string.

Allowed Values

JSON

Example

[{ "k": "v1" }, { "k": "v2" }]

mixed_reference

Supports references of any type.

Allowed Values

Text

Example

gid://shopify/Customer/1234531234535

Deprecated/old metafield types

If importing Metafield with the below listed old types, app would primarily check if there is Metafield definition in the store with he same Namespace and Key and if found then use the type from the definition ignoring the old type specified in the file.

Type	Description / Example Value
integer	A number. Allowed Values Number Example 10
string	A text. Allowed Values Text Example This is red shirt.
json_string	JSON format code. Allowed Values JSON Example [{ "k": "v1" }, { "k": "v2" }]

Type

Description / Example Value

integer

A number.

Allowed Values

Number

Example

string

A text.

Allowed Values

Text

Example

This is red shirt.

json_string

JSON format code.

Allowed Values

JSON

Example

[{ "k": "v1" }, { "k": "v2" }]

Cell Values

Each row cell is a Metafield value of that respective Metafield column.

In Shopify – Metafields are actually not columns, they are entries for each separate item. There can be some items with Metafields, and some without.

If the exported Metafield value is empty, then it means that this Metafield doesn’t exist. Shopify cannot have Metafields with empty values.

When the Metafield is imported:

If there is some value, then it will either create or update the existing Metafield in Shopify.
If the value is empty, then this Metafield for that item will be deleted (not set to empty value, but deleted).

Deleting Metafields

To delete Metafields, just set all values to empty, and import it.

Metafield Examples

Column Name	Description
Metafield: title_tag	SEO Title If the value will match exactly the same Product (or Collection) Title, then Shopify stores it as an empty value. Also, if the value is empty, then Shopify will serve SEO Title the same as Product (or Collection) Title. Therefore – SEO Title is never empty. When exporting, you will have some value only if it differs from the Product (or Collection) Title. Allowed Values Text Example Mom Strength Red T-shirt Slim Fit
Metafield: description_tag	SEO Description If the value will match exactly the same Product Description, then Shopify stores it as an empty value. Also, if the value is empty, then Shopify will serve SEO Description the same as Product Description. Therefore – SEO Description is never empty if Product has some description at all. When exporting, you will have some value only if it differs from the Product (or Collection) Description. Allowed Values Text Example Those t-shirts are the best ones for smart moms.
Metafield: some number	If you set the value in Excel as a number, it will be automatically saved as “integer” type. Allowed Values Text or Number Example 234876234
Metafield: namespace.name	If column name starts with “Metafield: “, then what comes next is treated as Metafield name. To set the namespace, prefix it before the name, and “.” (dot). If a namespace is not set, then it will be set to “global”. If column name has “[string]” or “[integer]” at the end, then it will force the type accordingly from that. If the Metafield value is empty, then it will not be updated at all – this item Metafield will be ignored. Allowed Values Text or Number Example Anything can be written here.
Metafield: birthday	If you want to save Customer birthdate, and use it in the Store. Allowed Values Text or Number Example 1980-11-18

Import Metafields by row

Matrixify app in export and import primarily uses Metfields by columns as explained above.
You can also import Metafields by row.

Metafields by row can also be mixed with Metafield columns from Matrixify template.

Column Name	Description
Metafield Namespace	A container for a set of metafields. You should define a custom namespace for your metafields to distinguish them from namespaces used by apps and Shopify (including the default `global`).
Metafield Key	The name of the metafield.
Metafield Value	The information to be stored as metadata. This column is required when other metafield columns are included.
Metafield Value Type	The metafield’s information type. See Metafield Types for valid type values.

For Products – this way you can import both Product and Variant Metafields. If the row is for Variant then app will save that Metafield as Variant Metafield, if there is no variant in the row then the app will save it as product Metafield. If you need to have multiple Metafields for the same variant then copy whole variant row for each additional Metafield row (or use Metafield columns from Matrixify template).
Above example, each variant would have 1 Metafield and the product itself would have 2 other Metafields.

Good To Know

To update existing Metafields or add new, minimum required columns are:
1. ID
2. Handle (if you want it to identify item by Handle)
3. Metafield: ****
When importing Metafields that you will need to use in definitions, it is best to set up the Metafield definitions first in your Shopify Admin -> Settings -> Custom Data. If definitions have not been set, then they will be imported as “Metafields without definitions”. Shopify limits what types of Metafield definitions can be created from “Metafields without definitions”, such as, you will not be able to then set up those definitions as Rich text or reference types.
The easiest way to learn Metafields is to export them and watch how they are in Excel (or in CSV). Then import them back, and see what changed. You can do those experiments with just one row.
Shopify allows probably unlimited Metafield values per item (at least we haven’t seen any real limit). If you need to export more than 10’000 columns of Metafields, then please use CSV file format because Excel will struggle with more columns.
See more about Metafields – what they are, and why there exist, in this tutorial: How to manage Shopify Metafields?