Metafields for Import and Export
Matrixify app allows you to bulk manage, export, import, and update almost all entity Metafield values that Shopify supports natively:
- Product Metafields
- Product Variant Metafields
- Smart Collection Metafields
- Custom Collection Metafields
- Customer Metafields
- Order Metafields
- Draft Order Metafields
- Company Metafields
- Company Location Metafields
- Page Metafields
- Blog Post Metafields
- Shop Metafields (These are Metafields that are attached to your Shop itself. They cannot be seen in admin natively and do not have definitions in Shopify).
Metafield values are managed within the entity they exist in, for example, to export or import B2B Company Metafields, you would need to do this through the Companies export/import sheet.
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:
All Metafield Types
We have compiled all possible Metafield types to see what is the correct type value to use in the import file and an 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 ValuesDate Example2021-10-25 |
date_time | A date and time in ISO 8601 format without a presumed timezone.
Allowed ValuesText Example2021-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 ValuesJSON 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 ValuesJSON 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 ValuesJSON 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 ValuesJSON 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 ValuesJSON 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 ValuesJSON 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 ValuesNumber Example10 |
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 ValuesText Example[8,2,3] |
number_decimal | A number with decimal places in the range from -9999999999999.999999999 till 9999999999999.999999999 .
Allowed ValuesNumber Example10.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 ValuesText Example["1.123","2.545","3.987"] |
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 ValuesText ExampleThis 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 ValuesExample["this","is","list", "with 4 list values"] |
multi_line_text_field | A multi-line text field.
Allowed ValuesText ExampleIngredients: Flour Water Milk Eggs |
rich_text_field | Rich text field.
Allowed ValuesJSON 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"}]}]} |
Reference
Type | Description / Example Value |
---|---|
product_reference | A reference to a product from this online store.
When exporting, the value will show as a product Handle. (Can ask Matrixify Support to set up for specific store to export reference Metafields as Shopify internal GID). When importing, you can use both products Handle and Shopify Product GID. Allowed ValuesText Examplesummer-jacket |
list.product_reference | A reference to a product from this online store.
When exporting, the value will show as a product Handle. (Can ask Matrixify Support to set up for specific store to export reference Metafields as Shopify internal GID). When importing, you can use both products Handle and Shopify Product GID. Allowed ValuesText Examplesummer-jacket, winter-coat, colorful-shirt |
collection_reference | A reference to a collection from this online store.
When exporting, the value will show as a collection Handle. (Can ask Matrixify Support to set up for specific store to export reference Metafields as Shopify internal GID). When importing, you can use both collection Handle and Shopify collection GID. Allowed ValuesText Examplesummer-sale-collection |
list.collection_reference | A reference list of collections from this online store.
When exporting, the value will show as a collection Handle. (Can ask Matrixify Support to set up for specific store to export reference Metafields as Shopify internal GID). When importing, you can use both collection Handle and Shopify collection GID. Allowed ValuesText Examplesummer-sale-collection, branded-clothes |
variant_reference | A reference to a product variant from this online store.
When exporting, the value will show as When importing, you can use both Allowed ValuesText Examplesummer-shirt.Red Small |
list.variant_reference | A reference to a product variant from this online store.
When exporting, the value will show as When importing, you can use both Allowed ValuesText Examplesummer-shirt.Red Small, summer-hoodie.XL |
file_reference | A reference to a file from this online store.
When exporting, the value will show as a file name. (Can ask Matrixify Support to set up for specific store to export reference Metafields as Shopify internal GID). When importing, you can use both file name and Shopify file GID. Allowed ValuesText Example1230_20Single_20Door_20Wall.jpg |
list.file_reference | A reference to a file from this online store.
When exporting, the value will show as a file name. (Can ask Matrixify Support to set up for specific store to export reference Metafields as Shopify internal GID). When importing, you can use both file name and Shopify file GID. Allowed ValuesText Example1230_20Single_20Door_20Wall.jpg, 50002-102-02.jpg |
metaobject_reference | A reference to a metaobject entry from this online store.
When exporting, the value will show as a When importing, you can use both Allowed ValuesText Examplemanufacturer.Robert-Jones |
list.metaobject_reference | A reference to a metaobject entry from this online store.
When exporting, the value will show as a When importing, you can use both Allowed ValuesText Examplemanufacturer.Robert-Jones, manufacturer.July-Smith |
page_reference | A reference to a page from this online store.
When exporting, the value will show as a page Handle. (Can ask Matrixify Support to set up for specific store to export reference Metafields as Shopify internal GID). When importing, you can use both page Handle and Shopify Product GID. To reference page outside of this store, use the URL field. Allowed ValuesText Exampleabout-us |
list.page_reference | A reference to a page from this online store.
When exporting, the value will show as a page Handle. (Can ask Matrixify Support to set up for specific store to export reference Metafields as Shopify internal GID). When importing, you can use both page Handle and Shopify Product GID. To reference page outside of this store, use the URL field. Allowed ValuesText Exampleabout-us, contact-us |
order_reference | A reference to order from this online store.
When exporting, the value will show as an order name. (Can ask Matrixify Support to set up for specific store to export reference Metafields as Shopify internal GID). When importing, you can use both an order name and Shopify order GID. Allowed ValuesText Example#1234 |
customer_reference |
A reference to a customer from this online store.
When exporting, the value will show as a customer email. (Can ask Matrixify Support to set up for specific store to export reference Metafields as Shopify internal GID). When importing, you can use both a customer email and Shopify customer GID. Allowed ValuesText Example[email protected] |
Other
Type | Description / Example Value |
---|---|
color | The hexadecimal code for a color.
Allowed ValuesText Example#fff123 |
list.color | A list of hexadecimal codes for a color.
Allowed ValuesJSON Example["#44b144","#ff0000"] |
money | Amount of money in specific currency.
Allowed ValuesJSON Example{"amount":"15.0","currency_code":"EUR"} |
rating | A rating measured on a set scale.
Allowed ValuesJSON Example{ "value": "3.5", "scale_min": "1.0", "scale_max": "5.0" } |
list.rating | A of ratings each measured on a set scale.
Allowed ValuesJSON Example[{ "value": "3.5", "scale_min": "1.0", "scale_max": "5.0" },{ "value": "9.0", "scale_min": "1.0", "scale_max": "10.0" }] |
boolean | A true or false value.
Allowed ValuesTRUE FALSE ExampleTRUE |
url | A URL with one of the allowed schemes: https , http , mailto: , sms: , tel: .
Allowed ValuesText Examplehttps://matrixify.app/ |
list.url | List of URLs with one of the allowed schemes: https , http , mailto: , sms: , tel: .
Allowed ValuesJSON Example["https://matrixify.app/","https://shopify.com/"] |
link | A link with text. Links value must be prefixed with: https , http , mailto: , sms: , tel: .
Allowed ValuesJSON Example{"text":"Matrixify Tutorials page","url":"https://matrixify.app/tutorials/"} |
list.link | A list of links with text. Links value must be prefixed with: https , http , mailto: , sms: , tel: .
Allowed ValuesJSON Example[{"text":"Matrixify website","url":"https://matrixify.app"},{"text":"Shopify website","url":"https://shopify.com"}] |
Advanced
Type | Description / Example Value |
---|---|
json | A JSON-formatted string.
Allowed ValuesJSON Example[{ "k": "v1" }, { "k": "v2" }] |
mixed_reference | A reference to a metaobject entry from this online store. Can be used to specify entries from multiple different metaobjects.When exporting, the value will show as a metaobject.entry . (Can ask Matrixify Support to set up for specific store to export reference Metafields as Shopify internal GID).When importing, you can use both metaobject.entry and Shopify metaboject entry GID.
Allowed ValuesText Examplemanufacturer.Robert-Jones, style.Summer |
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 ValuesNumber Example10 |
string | A text.
Allowed ValuesText ExampleThis is red shirt. |
json_string | JSON format code.
Allowed ValuesJSON 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 ValuesText ExampleMom 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 ValuesText ExampleThose 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 ValuesText or Number Example234876234 |
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 ValuesText or Number ExampleAnything can be written here. |
Metafield: birthday | If you want to save Customer birthdate, and use it in the Store.
Allowed ValuesText or Number Example1980-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.
Metafield values with more than 32767 characters
The problem
Microsoft Excel has some limitations that can sometimes cause trouble when working with large amounts of data. One of those limitations is 32767 character limit for a single cell.
Multiple other apps use Metafields to store various information and it can get quite large over time. If some Metafield value is over this Excel limit of 32767 characters, then it will still be all exported, but when opening the file in Excel it will first display error:
"We found a problem with some content in 'Export_2019-06-18_1659.xlsx'. Do you want us to try to recover as much as we can?".
When Excel has recovered the data it will cut all cell values over the limit to 32767 characters. Saving this file and importing back into the Shopify will result in the Metafield being saved with these 32767 characters, thus cutting the rest off information in that cell.
Note that it will cut it off only if you open the exported .xlsx or .csv file in Excel, and save it. If you will not save the file, and import it by just exporting, then nothing will be cut off – you will be all good.
Solution
We have made the Matrixify app to locate this possible issue and not update any Metafields whose values are exactly 32767 characters (the cut-off cell size).
If the cell value is over 32767 Characters that means that Excel has not cut it and it’s good to import.
If the cell value is under 32767 Characters that again means that Excel has not forcefully cut anything and Metafield will bet set/updated as usually.
Once the Matrixify will detect Metafield with this exact length it will not fail the item, but in the Import Results file a warning will be returned:
"Warning: [Metafield: namespace.key [type]] is not saved. It may be cut off by the Excel because of the 32767 character limit."
Good To Know
- To update existing Metafields or add new, minimum required columns are:
- ID
- Handle (if you want it to identify item by Handle)
- 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?