Each [metafield](/docs/apps/build/custom-data/metafields) and [metafield definition](/docs/apps/build/custom-data/metafields/definitions) has a type, which defines the type of information that it can store. The metafield types have built-in validation and [Liquid](/docs/api/liquid/objects/metafield) support.
## 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
Metafields and metafield definitions can have any of the types specified in the following table.
| Type | Description | Example value | Value type | [Translatable](/docs/api/admin-graphql/latest/mutations/translationsRegister) | [Market localizable](/docs/api/admin-graphql/latest/mutations/marketLocalizationsRegister) | 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](https://www.iso.org/iso-8601-date-and-time-format.html) format without a presumed timezone. |
2022-02-02
| string | no | no | 65k |
| `date_time` | A date and time in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) 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` |
{ "value": 25.0, "unit": "cm" }
| JSON object | no | no | 65k |
| `id` | A unique single-line text field. You can add [validations](/docs/apps/build/custom-data/metafields/list-of-validation-options) for `min`, `max`, and `regex`. |
1234
| string | no | no | 2048 |
| `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 | 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](https://help.shopify.com/manual/markets/languages/translate-adapt-app#create-custom-content-for-a-market), but you can't translate them to a different language or locale. |
| 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](/docs/apps/build/custom-data/metafields/list-of-validation-options) are required for ratings and support `min` and `max`. |
| 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`. |
{ "value": 20.0, "unit": "ml" }
| JSON object | no | no | 65k |
| `weight` | A value and a unit of weight. Valid unit values: `oz`, `lb`, `g`, `kg` |
{ "value": 2.5, "unit": "kg" }
| JSON object | no | no | 65k |
### Reference types
Reference metafields enable you to store references to Shopify resources.
| Type | Description | Example value | Value type | [Translatable](/docs/api/admin-graphql/latest/mutations/translationsRegister) | [Market localizable](/docs/api/admin-graphql/latest/mutations/marketLocalizationsRegister) |
|---|---|---|---|---|---|
| `collection_reference` | A reference to a collection on the online store. |
gid://shopify/ Collection/1
| string | no | yes |
| `customer_reference` | A reference to a customer on the online store. |
gid://shopify/Customer/1
| string | no | no |
| `file_reference` | A reference to a file on the online store. The default value is `GenericFile`. You can use [validations](/docs/apps/build/custom-data/metafields/list-of-validation-options) 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](/docs/apps/build/custom-data/metafields/list-of-validation-options) 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 |
| `product_taxonomy_value_reference` | A reference to a product taxonomy value. You can add [validations](/docs/apps/build/custom-data/metafields/list-of-validation-options) to limit which taxonomy values can be selected. Refer to [Shopify Standard Product Taxonomy](https://shopify.github.io/product-taxonomy) for available values. |
gid://shopify/TaxonomyValue/1
| string | no | no |
| `variant_reference` | A reference to a product variant on the online store. |
gid://shopify/ ProductVariant/1
| string | no | yes |
### 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](/docs/storefronts/themes/best-practices/templates-sections-blocks#metafields). 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](/docs/api/admin-graphql/latest/mutations/translationsRegister) | [Market localizable](/docs/api/admin-graphql/latest/mutations/marketLocalizationsRegister) |
|---|---|---|---|---|
| `list.collection_reference` | A list of collection references. |
| no | no |
| `list.date` | A list of dates in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format without presumed timezones. |
[ "2022-01-01", "2022-05-05" ]
| no | no |
| `list.date_time` | A list of dates and times in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) 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`. |
| no | no |
| `list.file_reference` | A list reference to a file on the online store. The default value is `GenericFile`. You can use [validations](/docs/apps/build/custom-data/metafields/list-of-validation-options) to add other file types (for example, `Image`) |
[ "gid://shopify/ MediaImage/123
",
"gid://shopify/ MediaImage/456 ]
| yes | no |
| `list.id` | A list of unique single-line text fields. You can add [validations](/docs/apps/build/custom-data/metafields/list-of-validation-options) for `min`, `max`, and `regex`. |
[ "1234", "5678" ]
| string | no | 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_decimal` | A list of numbers with decimal places in the range of +/-9999999999999.999999999. |
[ "10.4", "20.5", "30.6" ]
| 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.page_reference` | A list of references to pages on the online store. |
| no | no |
| `list.product_taxonomy_value_reference` | A list of references to product taxonomy values. You can add [validations](/docs/apps/build/custom-data/metafields/list-of-validation-options) to limit which taxonomy values can be selected. Refer to [Shopify Standard Product Taxonomy](https://shopify.github.io/product-taxonomy) for available values. |
| string | no | no |
| `list.rating` | A list of ratings measured on a specified scale. [Validations](/docs/apps/build/custom-data/metafields/list-of-validation-options) are required for ratings and support `min` and `max`.|
| 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 |
### 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 |
> Note:
> - Each item in the list has the same character limits as its corresponding single value type (for example, each text field in a list.single_line_text_field can store up to 65k characters).
> - You can use the `list.min` and `list.max` validations through the Shopify Admin API to set custom minimum and maximum limits for the number of items in a list, as long as they don't exceed the maximum items shown above.
### 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:
## Next steps
- Learn how to [manage metafields](/docs/apps/build/custom-data/metafields/manage-metafields) using the GraphQL Admin API.
- Learn how to create [metafield definitions](/docs/apps/build/custom-data/metafields/definitions) to include data validation for metafield values.