[{"value":"Base types","id":"base-types","hLevel":2,"level":1},{"value":"Base type code examples","id":"base-type-code-examples","hLevel":2,"level":1},{"value":"Reference types","id":"reference-types","hLevel":2,"level":1},{"value":"Reference type code examples","id":"reference-type-code-examples","hLevel":2,"level":1},{"value":"List types","id":"list-types","hLevel":2,"level":1},{"value":"List type code examples","id":"list-type-code-examples","hLevel":2,"level":1},{"value":"Rich text format","id":"rich-text-format","hLevel":2,"level":1,"children":[{"value":"Bold and italic","id":"bold-and-italic","hLevel":3,"level":2},{"value":"Headings","id":"headings","hLevel":3,"level":2},{"value":"Links","id":"links","hLevel":3,"level":2},{"value":"Lists","id":"lists","hLevel":3,"level":2}]}]

Data types

Metafields use data types to define the content that can be stored. Each data type has built-in format validation. Regardless of the data type, metafield values are passed and stored as strings. In theme templates, you can access metafields through the metafield object.

Base types

Base type metafields store text, numbers, dates, and measurements with units.

Type	Description	Value type
`boolean`	A boolean value (`true` or `false`).	boolean
`color`	A hexadecimal color code.	string
`date`	A date in ISO 8601 format without a time zone.	string
`date_time`	A date and time in ISO 8601 format without a time zone. Greenwich Mean Time (GMT) is used by default.	string
`dimension`	A numeric length value and unit. Valid units are: `mm`: Millimeters `cm`: Centimeters `m`: Meters `in`: Inches `ft`: Feet `yd`: Yards	JSON object
`json`	A JSON-serializable value, which can be an object, array, string, number, boolean value, or `null`.	JSON object
`link`	A combination of text and a URL for storing link content.	JSON object
`money`	A monetary amount with a currency code that matches the store currency.	JSON object
`multi_line_text_field`	A multiline text field with a maximum size of 65 KB.	string
`number_decimal`	A decimal number ranging from -9,999,999,999,999.999999999 to 9,999,999,999,999.999999999.	string
`number_integer`	An integer ranging from -9,999,999,999,999 to 9,999,999,999,999.	integer
`rating`	A rating within a specified range. The `scale_min` and `scale_max` validation parameters are required.	JSON object
`rich_text_field`	A rich text field that supports headings, lists, links, bold text, and italic text.	JSON object
`single_line_text_field`	A single-line text field with a maximum size of 65 KB.	string
`url`	A URL that supports the following protocols: `https`, `http`, `mailto`, `sms`, and `tel`.	string
`volume`	A numeric volume value and unit. Valid units are: `ml`: Milliliters `cl`: Centiliters `l`: Liters `m3`: Cubic meters `us_fl_oz`: US fluid ounces `us_pt`: US pints `us_qt`: US quarts `us_gal`: US gallons `imp_fl_oz`: Imperial fluid ounces `imp_pt`: Imperial pints `imp_qt`: Imperial quarts `imp_gal`: Imperial gallons	JSON object
`weight`	A numeric weight value and unit. Valid units are: `kg`: Kilograms `g`: Grams `lb`: Pounds `oz`: Ounces	JSON object

Base type code examples

The following examples show the expected value format for each base type:

Type	Example
`boolean`	`true`
`color`	`#e84c3d`
`date`	`2026-04-24`
`date_time`	`2026-04-24T12:30:00`
`dimension`	`{ "value": 25.5, "unit": "cm" }`
`json`	`{ "title": "Summer collection", "stock": 100 }`
`link`	`{ "text": "Learn more", "url": "https://www.shopline.com" }`
`money`	`{ "amount": "5.99", "currency_code": "CNY" }`
`multi_line_text_field`	`Ingredients Flour Water Milk`
`number_decimal`	`9.99`
`number_integer`	`42`
`rating`	`{ "value": "4.0", "scale_min": "1.0", "scale_max": "5.0" }`
`rich_text_field`	`{ "type": "root", "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Bold text.", "bold": true } ] } ] }`
`single_line_text_field`	`Express shipping`
`url`	`https://www.shopline.com`
`volume`	`{ "value": 20.5, "unit": "ml" }`
`weight`	`{ "value": 2.5, "unit": "kg" }`

Reference types

Reference type metafields store references to store resources.

Type	Description	Value type
`collection_reference`	A reference to a product collection.	string
`file_reference`	A reference to a file.	string
`metaobject_reference`	A reference to a metaobject entry.	string
`page_reference`	A reference to a page.	string
`product_reference`	A reference to a product.	string
`variant_reference`	A reference to a product variant.	string
`article_reference`	A reference to an article.	string

Reference type code examples

Type	Example
`collection_reference`	`gid://shopline/collections/1`
`file_reference`	`gid://shopline/MediaImage/123`
`metaobject_reference`	`gid://shopline/Metaobject/2`
`page_reference`	`gid://shopline/Page/1`
`product_reference`	`gid://shopline/Product/1`
`variant_reference`	`gid://shopline/ProductVariant/1`
`article_reference`	`gid://shopline/Article/1`

List types

List type metafields store multiple values in a single metafield. Values are represented as JSON arrays. Each list type metafield can contain up to 128 elements.

Type	Description
`list.color`	A list of hexadecimal color codes.
`list.collection_reference`	A list of product collection references.
`list.date`	A list of dates in ISO 8601 format.
`list.date_time`	A list of dates and times in ISO 8601 format.
`list.dimension`	A list of numeric length values and units. Valid units are: `mm`: Millimeters `cm`: Centimeters `m`: Meters `in`: Inches `ft`: Feet `yd`: Yards
`list.file_reference`	A list of file references.
`list.link`	A list of text and URL combinations for storing multiple links.
`list.metaobject_reference`	A list of metaobject entry references.
`list.number_decimal`	A list of decimal numbers.
`list.number_integer`	A list of integers.
`list.page_reference`	A list of page references.
`list.article_reference`	A list of article references.
`list.product_reference`	A list of product references.
`list.rating`	A list of ratings within a specified range.
`list.single_line_text_field`	A list of single-line text fields.
`list.url`	A list of URLs that support the `https`, `http`, `mailto`, `sms`, and `tel` protocols.
`list.variant_reference`	A list of product variant references.
`list.volume`	A list of numeric volume values and units. Valid units are: `ml`: Milliliters `cl`: Centiliters `l`: Liters `m3`: Cubic meters `us_fl_oz`: US fluid ounces `us_pt`: US pints `us_qt`: US quarts `us_gal`: US gallons `imp_fl_oz`: Imperial fluid ounces `imp_pt`: Imperial pints `imp_qt`: Imperial quarts `imp_gal`: Imperial gallons
`list.weight`	A list of numeric weight values and units. Valid units are: `kg`: Kilograms `g`: Grams `lb`: Pounds `oz`: Ounces

List type code examples

Type	Example
`list.color`	`["#e84c3d", "#3498db", "#2ecc71"]`
`list.collection_reference`	`["gid://shopline/collections/1", "gid://shopline/collections/2"]`
`list.date`	`["2026-01-01", "2026-05-01"]`
`list.date_time`	`["2026-01-01T12:30:00", "2026-05-01T12:30:00"]`
`list.dimension`	`[ { "value": 25.5, "unit": "cm" }, { "value": 35.5, "unit": "cm" } ]`
`list.file_reference`	`["gid://shopline/MediaImage/123", "gid://shopline/GenericFile/456", "gid://shopline/video/789"]`
`list.link`	`[ { "text": "Get started", "url": "https://shopline.com" }, { "text": "View documentation", "url": "https://developer.shopline.com/docs" } ]`
`list.metaobject_reference`	`["gid://shopline/Metaobject/123", "gid://shopline/Metaobject/456"]`
`list.number_decimal`	`["9.99", "19.9", "99.0"]`
`list.number_integer`	`["1", "5", "42"]`
`list.page_reference`	`["gid://shopline/Page/1", "gid://shopline/Page/2"]`
`list.article_reference`	`["gid://shopline/Article/1", "gid://shopline/Article/2"]`
`list.product_reference`	`["gid://shopline/Product/1", "gid://shopline/Product/2"]`
`list.rating`	`[ { "value": "4.0", "scale_min": "1.0", "scale_max": "5.0" }, { "value": "2.5", "scale_min": "1.0", "scale_max": "5.0" } ]`
`list.single_line_text_field`	`["Express shipping", "Standard shipping"]`
`list.url`	`["https://www.shopline.com", "https://developer.shopline.com"]`
`list.variant_reference`	`["gid://shopline/ProductVariant/1", "gid://shopline/ProductVariant/2"]`
`list.volume`	`[ { "value": 20.5, "unit": "ml" }, { "value": 40.5, "unit": "ml" } ]`
`list.weight`	`[ { "value": 2.5, "unit": "kg" }, { "value": 4.5, "unit": "kg" } ]`

Rich text format

The rich_text_field type accepts JSON objects with the following structure:

{
  "type": "root",
  "children": [
    {
      "type": "paragraph",
      "children": [
        {
          "type": "text",
          "value": "This is regular text.",
          "bold": true,
          "italic": true
        },
        {
          "type": "link",
          "url": "https://example.com",
          "title": "Example link",
          "children": [
            {
              "type": "text",
              "value": "Learn more",
              "bold": true
            }
          ]
        }
      ]
    }
  ]
}

Bold and italic

Text nodes use bold and italic to set text styles. The fields are described as follows:

Field	Required	Description
`type`	Yes	Fixed as `text`.
`value`	Yes	The content of the text node.
`bold`	No	Whether the text is bold. The default value is `false`.
`italic`	No	Whether the text is italic. The default value is `false`.

Example

{
  "type": "root",
  "children": [
    {
      "type": "paragraph",
      "children": [
        {
          "type": "text",
          "value": "This text is bold and italic.",
          "bold": true,
          "italic": true
        }
      ]
    }
  ]
}

Headings

The fields of a heading node are described as follows:

Field	Required	Description
`type`	Yes	Fixed as `heading`.
`level`	Yes	The heading level. Supported values range from `1` to `6`.
`children`	Yes	An array of `text` nodes.

Example

{
  "type": "root",
  "children": [
    {
      "type": "heading",
      "level": 2,
      "children": [
        {
          "type": "text",
          "value": "This is a level 2 heading"
        }
      ]
    }
  ]
}

Links

The fields of a link node are described as follows:

Field	Required	Description
`type`	Yes	Fixed as `link`.
`url`	Yes	The destination URL of the link.
`title`	No	The link title, which can be used for accessibility and search engine optimization (SEO).
`target`	No	The target for opening the link. For example, `_blank` opens the link in a new tab.
`children`	Yes	An array of `text` nodes.

Example

{
  "type": "root",
  "children": [
    {
      "type": "paragraph",
      "children": [
        {
          "type": "link",
          "url": "https://example.com",
          "title": "Link to example.com",
          "target": "_blank",
          "children": [
            {
              "type": "text",
              "value": "View details"
            }
          ]
        }
      ]
    }
  ]
}

Lists

The fields of list nodes and list item nodes are described as follows.

List node:

Field	Required	Description
`type`	Yes	Fixed as `list`.
`listType`	Yes	The list type. Supported values are `ordered` and `unordered`.
`children`	Yes	An array of nodes with `type` set to `list-item`.

List item node:

Field	Required	Description
`type`	Yes	Fixed as `list-item`.
`children`	Yes	An array of `text` nodes.

Example

{
  "type": "root",
  "children": [
    {
      "type": "list",
      "listType": "unordered",
      "children": [
        {
          "type": "list-item",
          "children": [
            {
              "type": "text",
              "value": "First item"
            }
          ]
        },
        {
          "type": "list-item",
          "children": [
            {
              "type": "text",
              "value": "Second item"
            }
          ]
        }
      ]
    }
  ]
}