---
title: List of data types
description: This page lists all the types supported by metafields.
source_url:
  html: 'https://shopify.dev/docs/apps/build/metafields/list-of-data-types'
  md: 'https://shopify.dev/docs/apps/build/metafields/list-of-data-types.md'
---

ExpandOn this page

* [How it works](https://shopify.dev/docs/apps/build/metafields/list-of-data-types.md#how-it-works)
* [Metafield type migration](https://shopify.dev/docs/apps/build/metafields/list-of-data-types.md#metafield-type-migration)
* [Basic types](https://shopify.dev/docs/apps/build/metafields/list-of-data-types.md#basic-types)
* [Basic type code samples](https://shopify.dev/docs/apps/build/metafields/list-of-data-types.md#basic-type-code-samples)
* [Reference types](https://shopify.dev/docs/apps/build/metafields/list-of-data-types.md#reference-types)
* [Reference type code samples](https://shopify.dev/docs/apps/build/metafields/list-of-data-types.md#reference-type-code-samples)
* [List types](https://shopify.dev/docs/apps/build/metafields/list-of-data-types.md#list-types)
* [List type code samples](https://shopify.dev/docs/apps/build/metafields/list-of-data-types.md#list-type-code-samples)
* [Rich text formatting details](https://shopify.dev/docs/apps/build/metafields/list-of-data-types.md#rich-text-formatting-details)
* [Next steps](https://shopify.dev/docs/apps/build/metafields/list-of-data-types.md#next-steps)

# List of data types

Each [metafield](https://shopify.dev/docs/apps/build/metafields) has a data type that determines what information it can store. All types have built-in validation and [Liquid](https://shopify.dev/docs/api/liquid/objects/metafield) support. Use this page to explore available types and their expected value formats.

Note

[Metaobjects](https://shopify.dev/docs/apps/build/metaobjects) use the same data types.

***

## How it works

When you create a metafield definition, the type applies to every instance of that resource. For example, if you create a definition called "Ingredients" with type `multi_line_text_field` for products, then every product will enforce that type for its "Ingredients" metafield.

## Example response

```json
{
  "data": {
    "product": {
      "metafield": {
        "namespace": "custom",
        "key": "ingredients",
        "value": "oat milk,\nsugar,\nchia seeds",
        "type": "multi_line_text_field",
        "definition": {
          "name": "Ingredients",
          "ownerType": "PRODUCT"
        }
      }
    }
  }
}
```

When using the Admin API to read and write metafields, the value is always entered and stored as a string, regardless of type.

For information about limits for each metafield type, refer to [metafield limits](https://shopify.dev/docs/apps/build/metafields/metafield-limits).

***

## Metafield type migration

You can change the type of a metafield, with some important considerations:

* Metafields cannot be migrated to type `id`.
* When migrating a metafield between incompatible types (for example, from `date_time` to `money`), the existing values become invalid. To fix this, use the Shopify admin to clear the invalid value, or use the API to clear the value or change the invalid definition to a compatible one.

***

## Basic types

Basic types store simple values like text, numbers, and dates. See [code samples](#basic-type-code-samples).

| Type | Description | Value type | [Translatable](https://shopify.dev/docs/api/admin-graphql/latest/mutations/translationsRegister) | [Market localizable](https://shopify.dev/docs/api/admin-graphql/latest/mutations/marketLocalizationsRegister) |
| - | - | - | - | - |
| `boolean` | A true or false value. | boolean | no | no |
| `color` | The hexadecimal code for a color. | string | no | no |
| `date` | A date in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format without a presumed timezone. | string | no | no |
| `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). | string | no | no |
| `dimension` | A value and a unit of length. Valid unit values: `in`, `ft`, `yd`, `mm`, `cm`, `m` | JSON object | no | no |
| `id` | A unique single-line text field. You can add [validations](https://shopify.dev/docs/apps/build/metafields/list-of-validation-options) for `min`, `max`, and `regex`. | string | no | no |
| `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 |
| `link` | A text and URL pairing that can be used to store link content. | JSON data | yes | no |
| `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. | JSON object | no | yes |
| `multi_line_text_field` | A multi-line text field. | string | yes | no |
| `number_decimal` | A number with decimal places in the range of +/-9999999999999.999999999. | string | no | no |
| `number_integer` | A whole number in the range of +/-9,007,199,254,740,991. | integer | no | no |
| `rating` | A rating measured on a specified scale. [Validations](https://shopify.dev/docs/apps/build/metafields/list-of-validation-options) are required for ratings and support `min` and `max`. | JSON object | no | no |
| `rich_text_field` | A rich text field supporting headings, lists, links, bold, and italics. Learn more about [rich text formatting](#rich-text-formatting-details). | JSON object | yes | no |
| `single_line_text_field` | A single-line text field. | string | yes | no |
| `url` | A URL with one of the allowed schemes: `https`, `http`, `mailto`, `sms`, `tel`. | string | yes | 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 | no |
| `weight` | A value and a unit of weight. Valid unit values: `oz`, `lb`, `g`, `kg` | JSON object | no | no |

***

## Basic type code samples

The following examples demonstrate the expected value format for each basic type:

| Type | Sample |
| - | - |
| `boolean` | ```text
true
``` |
| `color` | ```text
#fff123
``` |
| `date` | ```text
2022-02-02
``` |
| `date_time` | ```text
2024-01-01T12:30:00
``` |
| `dimension` | ```json
{
  "value": 25.0,
  "unit": "cm"
}
``` |
| `id` | ```text
1234
``` |
| `json` | ```json
{
  "ingredient": "flour",
  "amount": 0.3
}
``` |
| `link` | ```json
{
  "text": "Learn more",
  "url": "https://shopify.com"
}
``` |
| `money` | ```json
{
  "amount": "5.99",
  "currency_code": "CAD"
}
``` |
| `multi_line_text_field` | IngredientsFlourWaterMilkEggs |
| `number_decimal` | ```text
10.4
``` |
| `number_integer` | ```text
10
``` |
| `rating` | ```json
{
  "value": "3.5",
  "scale_min": "1.0",
  "scale_max": "5.0"
}
``` |
| `rich_text_field` | ```json
{
  "type": "root",
  "children": [
    {
      "type": "paragraph",
      "children": [
        {
          "type": "text",
          "value": "Bold text.",
          "bold": true
        }
      ]
    }
  ]
}
``` |
| `single_line_text_field` | ```text
VIP shipping method
``` |
| `url` | ```text
https://www.shopify.com
``` |
| `volume` | ```json
{
  "value": 20.0,
  "unit": "ml"
}
``` |
| `weight` | ```json
{
  "value": 2.5,
  "unit": "kg"
}
``` |

***

## Reference types

Reference metafields store references to Shopify resources. See [code samples](#reference-type-code-samples).

| Type | Description | Value type | [Translatable](https://shopify.dev/docs/api/admin-graphql/latest/mutations/translationsRegister) | [Market localizable](https://shopify.dev/docs/api/admin-graphql/latest/mutations/marketLocalizationsRegister) |
| - | - | - | - | - |
| `article_reference` | A reference to a [blog post](https://help.shopify.com/en/manual/online-store/blogs). | string | no | yes |
| `collection_reference` | A reference to a collection. | string | no | yes |
| `company_reference` | A reference to a company. | string | no | no |
| `customer_reference` | A reference to a customer. | string | no | no |
| `file_reference` | A reference to a file. The default value is `GenericFile`. You can use [validations](https://shopify.dev/docs/apps/build/metafields/list-of-validation-options) to add other file types (for example, `Image`). | string | yes | no |
| `metaobject_reference` | A reference to a metaobject entry. You can use [validations](https://shopify.dev/docs/apps/build/metafields/list-of-validation-options) to set which metaobject definition the metaobject must be. | 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. | string | no | no |
| `page_reference` | A reference to a page. | string | no | yes |
| `product_reference` | A reference to a product. | string | no | yes |
| `product_taxonomy_value_reference` | A reference to a product taxonomy value. You can add [validations](https://shopify.dev/docs/apps/build/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 |
| `variant_reference` | A reference to a product variant. | string | no | yes |

***

## Reference type code samples

The following examples demonstrate the expected value format for each reference type:

| Type | Sample |
| - | - |
| `article_reference` | ```text
gid://shopify/Article/1
``` |
| `collection_reference` | ```text
gid://shopify/Collection/1
``` |
| `company_reference` | ```text
gid://shopify/Company/1
``` |
| `customer_reference` | ```text
gid://shopify/Customer/1
``` |
| `file_reference` | ```text
gid://shopify/MediaImage/123
``` |
| `metaobject_reference` | ```text
gid://shopify/Metaobject/123
``` |
| `mixed_reference` | ```text
gid://shopify/Metaobject/123
``` |
| `page_reference` | ```text
gid://shopify/Page/1
``` |
| `product_reference` | ```text
gid://shopify/Product/1
``` |
| `product_taxonomy_value_reference` | ```text
gid://shopify/TaxonomyValue/1
``` |
| `variant_reference` | ```text
gid://shopify/ProductVariant/1
``` |

***

## List types

List metafields store multiple values in a single metafield as a JSON array. See [code samples](#list-type-code-samples).

You can implement list metafields on the online store [using sections and blocks](https://shopify.dev/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.

Info

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.

| Type | Description | [Translatable](https://shopify.dev/docs/api/admin-graphql/latest/mutations/translationsRegister) | [Market localizable](https://shopify.dev/docs/api/admin-graphql/latest/mutations/marketLocalizationsRegister) |
| - | - | - | - |
| `list.article_reference` | A list of references to [blog posts](https://help.shopify.com/en/manual/online-store/blogs). | no | no |
| `list.collection_reference` | A list of collection references. | no | no |
| `list.color` | A list of hexadecimal color codes. | no | no |
| `list.customer_reference` | A list of references to customers. | 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. | 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). | 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 of references to files. The default value is `GenericFile`. You can use [validations](https://shopify.dev/docs/apps/build/metafields/list-of-validation-options) to add other file types (for example, `Image`). | yes | no |
| `list.id` | A list of unique single-line text fields. You can add [validations](https://shopify.dev/docs/apps/build/metafields/list-of-validation-options) for `min`, `max`, and `regex`. | no | 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_decimal` | A list of numbers with decimal places in the range of +/-9999999999999.999999999. | no | no |
| `list.number_integer` | A list of whole numbers in the range of +/-9,007,199,254,740,991. | no | no |
| `list.page_reference` | A list of references to pages. | no | no |
| `list.product_reference` | A list of product references. | no | no |
| `list.product_taxonomy_value_reference` | A list of references to product taxonomy values. You can add [validations](https://shopify.dev/docs/apps/build/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. | no | no |
| `list.rating` | A list of ratings measured on a specified scale. [Validations](https://shopify.dev/docs/apps/build/metafields/list-of-validation-options) are required for ratings and support `min` and `max`. | 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 product variants. | 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 |

***

## List type code samples

The following examples demonstrate the expected value format for each list type:

| Type | Sample |
| - | - |
| `list.article_reference` | ```json
[
  "gid://shopify/Article/1",
  "gid://shopify/Article/2"
]
``` |
| `list.collection_reference` | ```json
[
  "gid://shopify/Collection/1",
  "gid://shopify/Collection/2"
]
``` |
| `list.color` | ```json
[
  "#FFF123",
  "#E6E6FA",
  "#00FF00"
]
``` |
| `list.customer_reference` | ```json
[
  "gid://shopify/Customer/1",
  "gid://shopify/Customer/2"
]
``` |
| `list.date` | ```json
[
  "2022-01-01",
  "2022-05-05"
]
``` |
| `list.date_time` | ```json
[
  "2024-01-01T12:30:00",
  "2024-05-01T12:30:00"
]
``` |
| `list.dimension` | ```json
[
  {"value": 25.0, "unit": "cm"},
  {"value": 35.0, "unit": "cm"}
]
``` |
| `list.file_reference` | ```json
[
  "gid://shopify/MediaImage/123",
  "gid://shopify/MediaImage/456"
]
``` |
| `list.id` | ```json
[
  "1234",
  "5678"
]
``` |
| `list.link` | ```json
[
  {"text": "Start a business", "url": "https://shopify.com"},
  {"text": "Read the docs", "url": "https://shopify.dev/docs"}
]
``` |
| `list.metaobject_reference` | ```json
[
  "gid://shopify/Metaobject/123",
  "gid://shopify/Metaobject/456"
]
``` |
| `list.mixed_reference` | ```json
[
  "gid://shopify/Metaobject/123",
  "gid://shopify/Metaobject/456"
]
``` |
| `list.number_decimal` | ```json
[
  "10.4",
  "20.5",
  "30.6"
]
``` |
| `list.number_integer` | ```json
[
  "10",
  "20",
  "30"
]
``` |
| `list.page_reference` | ```json
[
  "gid://shopify/Page/1",
  "gid://shopify/Page/2"
]
``` |
| `list.product_reference` | ```json
[
  "gid://shopify/Product/1",
  "gid://shopify/Product/2"
]
``` |
| `list.product_taxonomy_value_reference` | ```json
[
  "gid://shopify/TaxonomyValue/1",
  "gid://shopify/TaxonomyValue/2"
]
``` |
| `list.rating` | ```json
[
  {"value": "3.5", "scale_min": "1.0", "scale_max": "5.0"},
  {"value": "4.5", "scale_min": "1.0", "scale_max": "5.0"}
]
``` |
| `list.single_line_text_field` | ```json
[
  "VIP shipping method",
  "Standard shipping method"
]
``` |
| `list.url` | ```json
[
  "https://www.shopify.com",
  "https://www.shopify.dev"
]
``` |
| `list.variant_reference` | ```json
[
  "gid://shopify/ProductVariant/1",
  "gid://shopify/ProductVariant/2"
]
``` |
| `list.volume` | ```json
[
  {"value": 20.0, "unit": "ml"},
  {"value": 40.0, "unit": "ml"}
]
``` |
| `list.weight` | ```json
[
  {"value": 2.5, "unit": "kg"},
  {"value": 4.5, "unit": "kg"}
]
``` |

***

## Rich text formatting details

The `rich_text_field` metafield type accepts a JSON object that uses the following general structure:

```json
{
  "type": "root",
  // The root holds an array of paragraphs and lists. Each paragraph represents a section of text that's separated by a line break.
  "children": [
    {
      "type": "paragraph",
      // A paragraph holds an array of formatted text objects and URL objects, where the objects are concatenated to form the text within the paragraph.
      "children": [
        // Formatted text object
        {
          "type": "text",
          "value": "This is italicized text and ",
          "italic": true
        },
        // URL object
        {
          "url": "https://example.com",
          "title": "Link to example.com",
          "type": "link",
          "children": [
            // Formatted text object that's embedded in the URL object.
            {
              "type": "text",
              "value": "a bolded hyperlink",
              "bold": true
            }
          ]
        }
      ]
    }
  ]
}
```

![The rich text editor, showing the words](https://shopify.dev/assets/assets/images/apps/custom-data/example-rich-text-formatting-CV5Rivu5.png)

Refer to the following code samples for examples of the objects that can be used to represent fragments of rich text:

##### Bold and italics

```json
{
  "type": "root",
  "children": [
    {
      "type": "paragraph",
      "children": [
        {
          "type": "text",
          "value": "This text is bolded and italicized.",
          // To bold or italicize the text, set the "bold" or "italic" values to true. The default value is false.
          "bold": true,
          "italic": true
        }
      ]
    }
  ]
}
```

##### Heading

```json
{
  "type": "root",
  "children": [
    {
      "type": "paragraph",
      "children": [
        {
          "type": "heading",
          "children": [{
            "type": "text",
            "value": "This is an H1 heading"
          }],
          // The heading level
          "level": 1
        }
      ]
    }
  ]
}
```

##### Hyperlink

```json
{
  "type": "root",
  "children": [
    {
      "type": "paragraph",
      "children": [
        {
          "url": "https://example.com",
          // The URL title is used for accessibility and SEO purposes.
          "title": "Link to example.com",
          "type": "link",
          // The following array of formatted text represents the text that's visible to the user.
          "children": [{
            "type": "text",
            "value": "This is a hyperlink"
          }]
        }
      ]
    }
  ]
}
```

##### Lists

```json
{
  "type": "root",
  "children": [
    {
      // The listType accepts "ordered" or "unordered".
      "listType": "ordered",
      "type": "list",
      "children": [
        {
          "type": "list-item",
          // Each list item holds an array of formatted text.
          "children": [{
            "type": "text",
            "value": "This is the first list item."
          }]
        },
        {
          "type": "list-item",
          "children": [{
            "type": "text",
            "value": "This is the second list item."
          }]
        }
      ]

    }
  ]
}
```

***

## Next steps

* Learn how to [work with metafield values](https://shopify.dev/docs/apps/build/metafields/manage-metafields).
* Learn how to [work with metafield definitions](https://shopify.dev/docs/apps/build/metafields/definitions).
* Learn about [standard definitions](https://shopify.dev/docs/apps/build/metafields/list-of-standard-definitions).
* Learn about [validation options](https://shopify.dev/docs/apps/build/metafields/list-of-validation-options).

***

* [How it works](https://shopify.dev/docs/apps/build/metafields/list-of-data-types.md#how-it-works)
* [Metafield type migration](https://shopify.dev/docs/apps/build/metafields/list-of-data-types.md#metafield-type-migration)
* [Basic types](https://shopify.dev/docs/apps/build/metafields/list-of-data-types.md#basic-types)
* [Basic type code samples](https://shopify.dev/docs/apps/build/metafields/list-of-data-types.md#basic-type-code-samples)
* [Reference types](https://shopify.dev/docs/apps/build/metafields/list-of-data-types.md#reference-types)
* [Reference type code samples](https://shopify.dev/docs/apps/build/metafields/list-of-data-types.md#reference-type-code-samples)
* [List types](https://shopify.dev/docs/apps/build/metafields/list-of-data-types.md#list-types)
* [List type code samples](https://shopify.dev/docs/apps/build/metafields/list-of-data-types.md#list-type-code-samples)
* [Rich text formatting details](https://shopify.dev/docs/apps/build/metafields/list-of-data-types.md#rich-text-formatting-details)
* [Next steps](https://shopify.dev/docs/apps/build/metafields/list-of-data-types.md#next-steps)