• How it works
  • Supported types
  • Next steps

List of data types

Each metafield and metafield definition has a type, which defines the type of information that it can store. The metafield types have built-in validation and Liquid support.

How it works

Anchor link to section titled "How it works"

For metafield definitions, the type is enforced across every instance of the resource that owns the metafield definition. For example, if you create a metafield definition called "Ingredients" with the type multi_line_text_field with an owner type of PRODUCT, then the metafield's type will be multi_line_text_field for every product resource.

When using the Admin API to read and write metafields, the value is always entered and stored as a string, regardless of type.

Supported types

Anchor link to section titled "Supported types"

Metafields and metafield definitions can have any of the types specified in the following table.

Type Description Example value Value type Translatable Market localizable
boolean A true or false value. 
true
 boolean no no
color The hexadecimal code for a color. String value types can store up to five million characters. 
#fff123
 string no no
date A date in ISO 8601 format without a presumed timezone. String value types can store up to five million characters. 
2022-02-02
 string no no
date_time A date and time in ISO 8601 format without a presumed timezone. Defaults to Greenwich Mean Time (GMT). String value types can store up to five million characters. 
2024-01-01T12:30:00
 string no no
dimension A value and a unit of length. Valid unit values: in, ft, yd, mm, cm, m 
{ 
 "value": 25.0, 
 "unit": "cm"
}
JSON object no no
json A JSON-serializable value. This can be an object, an array, a string, a number, a boolean, or a null value. JSON data value types can store up to two million characters. 
{ 
 "ingredient": "flour", 
 "amount": 0.3
}
JSON data yes no
link A text and URL pairing that can be used to store link content. 
{ 
 "text": "Learn more", 
 "url": "https://shopify.com"
}
JSON data yes no
money A numeric amount, with a currency code that matches the store's currency.

You can localize money metafields to a market, but you can't translate them to a different language or locale.		 
{
 "amount": "5.99", 
 "currency_code": "CAD"
}
 JSON object no yes
multi_line_text_field A multi-line text field. String value types can store up to five million characters. 
Ingredients
Flour
Water
Milk
Eggs
 string yes no
number_decimal A number with decimal places in the range of +/-9999999999999.999999999. String value types can store up to five million characters. 
10.4
 string no no
number_integer A whole number in the range of +/-9,007,199,254,740,991. 
10
 integer no no
rating A rating measured on a specified scale. Validations are required for ratings. 
{ 
 "value": "3.5", 
 "scale_min": "1.0", 
 "scale_max": "5.0"
}
JSON object no
rich_text_field

A rich text field supporting headings, lists, links, bold, and italics.

Learn more about rich text formatting.

 
{
 "type": "root",
 "children": [
  {
   "type": "paragraph",
   "children": [
    {
     "type": "text",
     "value": "Bold text.",
     "bold": true
    }
   ]
  }
 ]
}
 JSON object yes no
single_line_text_field A single-line text field. String value types can store up to five million characters. 
VIP shipping method
 string yes no
url A URL with one of the allowed schemes: https, http, mailto, sms, tel. String value types can store up to five million characters. 
https://www.shopify.com
 string yes no
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. 
{ 
 "value": 20.0, 
 "unit": "ml"
}
JSON object no no
weight A value and a unit of weight. Valid unit values: oz, lb, g, kg 
{ 
 "value": 2.5, 
 "unit": "kg"
}
JSON object no no

Reference types

Anchor link to section titled "Reference types"

Reference metafields enable you to store references to Shopify resources.

Type Description Example value Value type Translatable Market localizable
collection_reference A reference to a collection on the online store. 
gid://shopify/
Collection/1
 string no yes
file_reference A reference to a file on the online store. The default value is GenericFile. You can use validations to add other file types (for example, Image). 
gid://shopify/
MediaImage/123
 string yes no
metaobject_reference A reference to a metaobject entry. You can use validations to set which metaobject definition the metaobject must be. 
gid://shopify/Metaobject/123
 string no yes
mixed_reference A reference to one of many metaobject definitions. Unlike metaobject_reference which only allows for a single metaobject definition to be set, mixed references allow for metaobjects that belong to different definitions. 
gid://shopify/Metaobject/123
 string no no
page_reference A reference to a page on the online store. 
gid://shopify/
Page/1
 string no yes
product_reference A reference to a product on the online store. 
gid://shopify/
Product/1
 string no yes
variant_reference A reference to a product variant on the online store. 
gid://shopify/
ProductVariant/1
 string no yes

List types

Anchor link to section titled "List types"

List metafields enable you to store multiple values in a single metafield. The value must be provided as a JSON array.

You can implement list metafields on the online store using sections and blocks. The type of list determines the implementation. For example, you could add a list of product references as a dynamic source to a custom block, or you could add a list of single line text fields to a text or rich text section.

Note

If you delete a product or variant from a store, then the product or variant is automatically removed from all list metafields that reference it.

The following list types are supported:

Type Description Example value Translatable Market localizable
list.collection_reference A list of collection references. 
[ 
"gid://shopify/Collection/1", 
"gid://shopify/Collection/2"
]
no no
list.color A list of hexadecimal color codes. 
[ 
"#FFF123", 
"#E6E6FA", 
"#00FF00"
]
no no
list.date A list of dates in ISO 8601 format without presumed timezones. 
[ 
"2022-01-01", 
"2022-05-05"
]
no no
list.date_time A list of dates and times in ISO 8601 format without presumed timezones. Defaults to Greenwich Mean Time (GMT). 
[ 
"2024-01-01T12:30:00", 
"2024-05-01T12:30:00"
]
no no
list.dimension A list of values and a unit of length. Valid unit values: in, ft, yd, mm, cm, m. 
[ 
 { 
 "value": 25.0, 
 "unit": "cm"
 },
 { 
 "value": 35.0, 
 "unit": "cm"
 } 
]
no no
list.file_reference A list reference to a file on the online store. The default value is GenericFile. You can use validations to add other file types (for example, Image) 
[ 
"gid://shopify/
MediaImage/123
", 
"gid://shopify/
MediaImage/456 
]
yes no
list.link A list of text and URL pairings that can be used to store a collection of links. 
[
 { 
 "text": "Start a business", 
 "url": "https://shopify.com"
 }, 
 { 
 "text": "Read the docs", 
 "url": "https://shopify.dev/docs" 
 }
]
yes no
list.metaobject_reference A list reference to one or more metaobject entries that belong to a single metaobject definition. Unlike list.mixed_reference, all metaobject entries referenced must be of the same definition. 
[ 
"gid://shopify/Metaobject/123", 
"gid://shopify/Metaobject/456"
]
 no no
list.mixed_reference A list reference to one or more metaobject entries that may belong to different metaobject definitions. 
[ 
"gid://shopify/Metaobject/123", 
"gid://shopify/Metaobject/456"
]
no no
list.number_integer A list of whole numbers in the range of +/-9,007,199,254,740,991. 
[ 
"10", 
"20", 
"30"
]
no no
list.number_decimal A list of numbers with decimal places in the range of +/-9999999999999.999999999. 
[ 
"10.4", 
"20.5",
"30.6" 
]
no no
list.page_reference A list of references to pages on the online store. 
[
"gid://shopify/
Page/1", 
"gid://shopify/
Page/2"
]
 no no
list.product_reference A list of product references. 
[ 
"gid://shopify/Product/1", 
"gid://shopify/Product/2"
]
no no
list.rating A list of ratings measured on a specified scale. Validations are required for ratings. 
[
 { 
 "value": "3.5", 
 "scale_min": "1.0", 
 "scale_max": "5.0"
 }, 
 { 
 "value": "4.5", 
 "scale_min": "1.0", 
 "scale_max": "5.0"
 }
]
no no
list.single_line_text_field A list of single-line text fields. 
[ 
"VIP shipping method", 
"Standard shipping method"
] 		yes no
list.url A list of URLs with one of the allowed schemes: https, http, mailto, sms, tel. 
[ 
"https://www.shopify.com", 
"https://www.shopify.dev"
]
yes no
list.variant_reference A list of references to a product variant on the online store. 
[ 
"gid://shopify/ProductVariant/1",
"gid://shopify/ProductVariant/2"
]
 no no
list.volume A list of values 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. 
[ 
 {
 "value": 20.0, 
 "unit": "ml"
 }, 
 {
 "value": 40.0, 
 "unit": "ml"
 }
]
no no
list.weight A list of values and a unit of weight. Valid unit values: oz, lb, g, kg 
[ 
 { 
 "value": 2.5, 
 "unit": "kg"
 },
 { 
 "value": 4.5, 
 "unit": "kg"
 } 
]
 no no

Lists type limits

Anchor link to section titled "Lists type limits"

The following table indicates the maximum number of values that each list type metafield can reference:

List type Maximum items
Collection reference 128
Customer reference 128
Date and time 128
Decimal 128
Dimension 128
File reference 128
Integer 128
JSON 128
Link 128
Metaobject reference 256
Mixed reference 128
Money 128
Multi line text 128
Page reference 128
Product reference 128
Product taxonomy reference 128
Rating 128
Single line text 128
URL 128
Variant reference 128
Volume 128
Weight 128

Rich text formatting

Anchor link to section titled "Rich text formatting"

The rich_text_field metafield type accepts a JSON object that uses the following general structure:

The rich text editor, showing the words 'This is italicized text and' in italics, and the words 'a bolded hyperlink' as bolded hyperlink to another website.

Refer to the following code samples for examples of the objects that can be used to represent fragments of rich text:

Next steps

Anchor link to section titled "Next steps"
  • Learn how to manage metafields using the GraphQL Admin API.
  • Learn how to create metafield definitions to include data validation for metafield values.
  • Learn how to migrate metafields from using value_type to type.

On this page

  • How it works
  • Supported types
  • Next steps