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.

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 API to read and write metafields, the value is always entered and stored as a string, regardless of type.

If you need to update your metafields that use the deprecated value_type field, refer to Metafield value_type deprecation.

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	yes
`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.	{ "k": "v1", "k": "V2" }	JSON data	yes
`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. The following list types are supported:

Type	Description	Example value
`list.single_line_text_field`	A list of single-line text field values.	[ "flour", "butter", "sugar" ]
`list.product_reference`	A list of product references.	[ "gid://shopify/Product/1", "gid://shopify/Product/2" ]

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.

Metafield `value_type` deprecation

Anchor link to section titled "Metafield value_type deprecation"

In API version 2021-07, we introduced a commerce-oriented type system:

In the REST Admin API, the type property replaces the value_type property in the Metafield resource.
In the GraphQL Admin API, the type field replaces the value_type field in the Metafield object.

For backward compatibility, when metafields that use the new types are queried from API version 2021-04 or earlier, we return a backward-mapped value type. For example, the date type maps to the STRING value type.

To learn more about using the APIs to work with metafields, refer to the following documentation:

Migrating from `value_type` to `type`

Anchor link to section titled "Migrating from value_type to type"

For backward compatibility purposes, and to make API migration easier, the new type attribute also accepts deprecated value types. You can update the field name and keep the same value to avoid breaking other integrations (such as Liquid in themes). When adding new metafields, we recommend using the new types.

Follow the steps below to update metafields for REST or GraphQL:

Migrate your metafields in the REST API
Migrate your metafields in the GraphQL API

Migrate your metafields in the REST API

Anchor link to section titled "Migrate your metafields in the REST API"

Change the value_type property to type in your metafield resource, as shown below:

Migrate your metafields in the GraphQL API

Anchor link to section titled "Migrate your metafields in the GraphQL API"

Change the valueType field to type in your metafield object, as shown below: