Start Free Trial
Start Free Trial

Metafields

Metafields for Import and Export

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

Column Names

Each new column represents specific Metafield – its Column name starts with “Metafield: “, and whatever follows after that, is the metafield name saved in Shopify.

To specify a Metafield namespace, include it in the name, and split with a dot (.). For example: “Metafield: namespace.key“.

If there is no namespace defined, 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 Types

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.

If you want to force the field type, regardless of the Excel column type, you can specify the type in the column name by putting type in the square brackets [type] at the end.

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

Type Description / Example Value
single_line_text_field A single-line text field.
Will not allow importing text with line breaks/newlines in it.Text

This item contains dairy products.
multi_line_text_field A multi-line text field.

Text

Ingredients:
Flour
Water
Milk
Eggs
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.Text

gid://shopify/OnlineStorePage/80516808771
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 Pages with the Matrixify app and combining text gid://shopify/Product/ with the product ID from the exported file.

Text

gid://shopify/Product/6611776405571
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 the Matrixify app and combining text gid://shopify/Product/ with the Variant ID from the exported file.

Text

gid://shopify/ProductVariant/39627628838979
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.

Text

gid://shopify/GenericFile/21151855542339
number_integer A whole number in the range of from -9007199254740991 till 9007199254740991.

Number

10
number_decimal A number with decimal places in the range from  -9999999999999.999999999 till 9999999999999.999999999.

Number

10.545
date A date in ISO 8601 format without a presumed timezone.

Date

2021-10-25
date_time A date and time in ISO 8601 format without a presumed timezone.

Text

2021-10-25T14:30:00
url A URL with one of the allowed schemes: https, http, mailto, sms, tel.

Text

https://matrixify.app/
json A JSON-formatted string.

JSON

[{ "k": "v1" }, { "k": "v2" }]
boolean A true or false value.

TRUE
FALSE

TRUE
color The hexadecimal code for a color.

Text

#fff123
weight A value and a unit of weight. Valid unit values: oz, lb, g, kg

JSON

{ "unit": "kg", "value": 2.5 }
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_galimp_fl_oz, imp_pt, imp_qt, imp_gal.

JSON

{ "unit": "ml", "value": 20.0 }
dimension A value and a unit of length. Valid unit values: in, ft, yd, mm, cm, m

{ "unit": "cm", "value": 25.0 }
rating A rating measured on a set scale.

Text

{ "value": "3.5", "scale_min": "1.0", "scale_max": "5.0" }

Deprecated/old metafield types

Type Description / Example Value
integer A number.

10
string A text.

This is red shirt.
json_string JSON format code.

[{ "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).
  • If the type of the Metafield column is different from what it is in Shopify, then it will get re-created (deleted and created) with the new type from import file.
  • If the type is not specified in the import file, then – if this Metafield already exists in Shopify for this item, then it will be converted to the same type that is in Shopify; but if it doesn’t exist, then the type will be “inferred” from the value in the cell. For example, if it is a whole number, then it will be inferred as “number_integer“, and so on.

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.

Text

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.

Text

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.

Text or Number

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.

Text or Number

Anything can be written here.
Metafield: birthday If you want to save Customer birthdate, and use it in the Store.

Text or Number

1980-11-18

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: ****
  • 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?