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 |
{ |
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/ |
string | yes |
json |
A JSON-serializable value. This can be an object, an array, a string, a number, a boolean, or a null value. | { |
JSON data | yes |
multi_line_text_field |
A multi-line text field. | Ingredients |
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/ |
string | no |
product_reference |
A reference to a product on the online store. | gid://shopify/ |
string | no |
rating |
A rating measured on a specified scale. Validations are required for ratings. | { |
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/ |
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 . |
{ |
JSON object | no |
weight |
A value and a unit of weight. Valid unit values: oz , lb , g , kg |
{ |
JSON object | no |
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. | [ |
list.product_reference |
A list of product references. | [ |
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 thevalue_type
property in theMetafield
resource. - In the GraphQL Admin API, the
type
field replaces thevalue_type
field in theMetafield
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
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: