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 | Max length (characters) |
---|---|---|---|---|---|---|
boolean |
A true or false value. | true |
boolean | no | no | 65k |
color |
The hexadecimal code for a color. | #fff123 |
string | no | no | 65k |
date |
A date in ISO 8601 format without a presumed timezone. | 2022-02-02 |
string | no | no | 65k |
date_time |
A date and time in ISO 8601 format without a presumed timezone. Defaults to Greenwich Mean Time (GMT). | 2024-01-01T12:30:00 |
string | no | no | 65k |
dimension |
A value and a unit of length. Valid unit values: in , ft , yd , mm , cm , m |
{ |
JSON object | no | no | 65k |
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 | no | 2M |
link |
A text and URL pairing that can be used to store link content. | { |
JSON data | yes | no | 65k |
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. |
{ |
JSON object | no | yes | 65k |
multi_line_text_field |
A multi-line text field. | Ingredients |
string | yes | no | 65k |
number_decimal |
A number with decimal places in the range of +/-9999999999999.999999999. | 10.4 |
string | no | no | 65k |
number_integer |
A whole number in the range of +/-9,007,199,254,740,991. | 10 |
integer | no | no | 65k |
rating |
A rating measured on a specified scale. Validations are required for ratings. | { |
JSON object | no | no | 65k |
rich_text_field |
A rich text field supporting headings, lists, links, bold, and italics. Learn more about rich text formatting. |
{ |
JSON object | yes | no | 65k |
single_line_text_field |
A single-line text field. | VIP shipping method |
string | yes | no | 65k |
url |
A URL with one of the allowed schemes: https , http , mailto , sms , tel . |
https://www.shopify.com |
string | yes | no | 2,048 |
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 | no | 65k |
weight |
A value and a unit of weight. Valid unit values: oz , lb , g , kg |
{ |
JSON object | no | no | 65k |
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/ |
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/ |
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/ |
string | no | yes |
product_reference |
A reference to a product on the online store. | gid://shopify/ |
string | no | yes |
variant_reference |
A reference to a product variant on the online store. | gid://shopify/ |
string | no | yes |
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.
The following list types are supported:
Type | Description | Example value | Translatable | Market localizable |
---|---|---|---|---|
list.collection_reference |
A list of collection references. | [ |
no | no |
list.color |
A list of hexadecimal color codes. | [ |
no | no |
list.date |
A list of dates in ISO 8601 format without presumed timezones. | [ |
no | no |
list.date_time |
A list of dates and times in ISO 8601 format without presumed timezones. Defaults to Greenwich Mean Time (GMT). | [ |
no | no |
list.dimension |
A list of values and a unit of length. Valid unit values: in , ft , yd , mm , cm , m . |
[ |
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/ |
yes | no |
list.link |
A list of text and URL pairings that can be used to store a collection of links. | [ |
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. |
[ |
no | no |
list.mixed_reference |
A list reference to one or more metaobject entries that may belong to different metaobject definitions. | [ |
no | no |
list.number_integer |
A list of whole numbers in the range of +/-9,007,199,254,740,991. | [ |
no | no |
list.number_decimal |
A list of numbers with decimal places in the range of +/-9999999999999.999999999. | [ |
no | no |
list.page_reference |
A list of references to pages on the online store. | [ |
no | no |
list.product_reference |
A list of product references. | [ |
no | no |
list.rating |
A list of ratings measured on a specified scale. Validations are required for ratings. | [ |
no | no |
list.single_line_text_field |
A list of single-line text fields. | [] |
yes | no |
list.url |
A list of URLs with one of the allowed schemes: https , http , mailto , sms , tel . |
[ |
yes | no |
list.variant_reference |
A list of references to a product variant on the online store. | [ |
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 . |
[ |
no | no |
list.weight |
A list of values and a unit of weight. Valid unit values: oz , lb , g , 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:
Refer to the following code samples for examples of the objects that can be used to represent fragments of rich text:
- 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
totype
.