Metafield 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 the following types:

Type	Description	Example value	Value type	Translatable
`boolean`	A true or false value.	true	boolean	no
`collection_reference`	A reference to a collection on the online store.	gid://shopify/ Collection/1	string	no
`color`	The hexadecimal code for a color.	#fff123	string	no
`date`	A date in ISO 8601 format without a presumed timezone.	2022-02-02	string	no
`date_time`	A date and time in ISO 8601 format without a presumed timezone	2022-01-01T12:30:00	string	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
`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
`json`	A JSON-serializable value. This can be an object, an array, a string, a number, a boolean, or a null value.	{ "ingredient": "flour", "amount": 0.3 }	JSON data	yes
`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
`multi_line_text_field`	A multi-line text field.	Ingredients Flour Water Milk Eggs	string	yes
`number_decimal`	A number with decimal places in the range of +/-9999999999999.999999999.	10.4	string	no
`number_integer`	A whole number in the range of +/-9,007,199,254,740,991.	10	integer	no
`page_reference`	A reference to a page on the online store.	gid://shopify/ OnlineStorePage/1	string	no
`product_reference`	A reference to a product on the online store.	gid://shopify/ Product/1	string	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
`single_line_text_field`	A single-line text field.	VIP shipping method	string	yes
`url`	A URL with one of the allowed schemes: `https`, `http`, `mailto`, `sms`, `tel`.	https://www.shopify.com	string	yes
`variant_reference`	A reference to a product variant on the online store.	gid://shopify/ ProductVariant/1	string	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
`weight`	A value and a unit of weight. Valid unit values: `oz`, `lb`, `g`, `kg`	{ "value": 2.5, "unit": "kg" }	JSON object	no

List types

Anchor link to section titled "List types"

List metafields enable you to store multiple values in a single metafield. The maximum number of values that can be stored in a metafield list is 128. 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.

The following list types are supported:

Type	Description	Example value	Translatable
`list.collection_reference`	A list of collection references.	[ "gid://shopify/Collection/1", "gid://shopify/Collection/2" ]	no
`list.color`	A list of hexadecimal color codes.	[ "#FFF123", "#E6E6FA", "#00FF00" ]	no
`list.date`	A list of dates in ISO 8601 format without presumed timezones.	[ "2022-01-01", "2022-05-05" ]	no
`list.date_time`	A list of dates and times in ISO 8601 format without presumed timezones.	[ "2022-01-01T12:30:00", "2022-05-01T12:30:00" ]	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
`list.file_reference`	A list references 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 ]	no
`list.number_integer`	A list of whole numbers in the range of +/-9,007,199,254,740,991.	[ "10", "20", "30" ]	no
`list.number_decimal`	A list of numbers with decimal places in the range of +/-9999999999999.999999999.	[ "10.4", "20.5", "30.6" ]	no
`list.page_reference`	A list of references to pages on the online store.	[ "gid://shopify/ OnlineStorePage/1", "gid://shopify/ OnlineStorePage/2" ]	no
`list.product_reference`	A list of product references.	[ "gid://shopify/Product/1", "gid://shopify/Product/2" ]	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
`list.single_line_text_field`	A list of single-line text fields.	[ "VIP shipping method", "Standard shipping method" ]	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" ]	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
`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
`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

Next steps

Anchor link to section titled "Next steps"

Learn how to create metafield definitions to include data validation for metafield values.
Learn how to migrate metafields from using value_type to type.

Metafield types

How it works

Supported types

List types

Next steps

On this page