WooCommerce custom fields (post meta) were untyped strings — you could store any data in any format. Shopify metafields are typed — each field has a declared type that determines how the value is stored, validated, displayed in the Theme Editor, and queried. Choosing the right type when creating metafield definitions is important: it affects storefront display, Liquid access, Admin UI editing experience, and whether the field can be used as a filter in Search & Discovery. This is the complete reference for every Shopify metafield type.

Text types

Type	Use case	Character limit	Liquid access
`single_line_text_field`	Short labels, specs, names	Unlimited	{{ product.metafields.ns.key }}
`multi_line_text_field`	Paragraphs, care instructions, notes	Unlimited	{{ product.metafields.ns.key \| newline_to_br }}

single_line_text_field: Best for short labels, classification values, codes. Stored as a plain string. Displayed as a single-line text input in Admin. Can be used as a Search & Discovery filter.
multi_line_text_field: For longer text with line breaks. Stored with newline characters. Use {{ value | newline_to_br }} in Liquid to render line breaks as HTML. Cannot be used as a Search & Discovery filter.

Number types

Type	Use case	Example value
`number_integer`	Counts, ages, years, whole units	42
`number_decimal`	Weights, prices, measurements	14.5

Both types stored as strings internally but validated as numbers
In Liquid: {{ product.metafields.ns.weight | times: 1 }} to do arithmetic
Use number_integer for things that are always whole numbers (age in months, quantity, year)
Use number_decimal for measurements (weight in kg, dimensions, ABV percentage)

Boolean type

boolean: true or false. Use for yes/no flags: vegan, dishwasher safe, award winner, in stock, free shipping.
Liquid: {% if product.metafields.ns.vegan.value %} — note: .value needed for boolean access in Liquid
Admin display: shows as a checkbox in the product editor
Use for anything that's a binary condition — not for things with 3+ states (use single_line_text for those)

Date and time types

Type	Format	Use case
`date`	YYYY-MM-DD	Launch date, vintage year, expiry date
`date_time`	ISO 8601 with time	Event datetime, timestamp

Liquid: {{ product.metafields.ns.launch_date | date: "%B %d, %Y" }} — use date filter for formatting
Use date for dates without time component (vintage year, manufacturing date)
Admin shows a date picker for both types

Color type

color: Stores a hex color value (#RRGGBB). Use for product colour when the specific hex is needed for display (e.g., showing a colour swatch).
Liquid: {{ product.metafields.ns.primary_color }} → "#3a8c9c"
Use in style attribute: style="background: {{ product.metafields.ns.color }}"
Distinct from a colour name (use single_line_text for "Midnight Navy" — colour names are text)

URL type

url: Stores a URL string with validation. Use for external links, PDF document links, video links.
Liquid: <a href="{{ product.metafields.ns.guide_url }}">Download guide</a>
Validated as a URL format — Admin won't accept non-URL strings

JSON type

json: Stores arbitrary JSON. Use only when no other type fits and you need structured data.
Liquid: {{ product.metafields.ns.specs | json }} — outputs raw JSON string
To access specific keys: requires custom JavaScript or server-side processing
Avoid for simple data — use typed fields instead. JSON is harder to display in Liquid and harder for merchants to edit in Admin.

Dimension types

Type	Format	Use case
`dimension`	{ value: 150, unit: "cm" }	Height, width, depth
`volume`	{ value: 500, unit: "ml" }	Liquid volume, capacity
`weight`	{ value: 1.5, unit: "kg" }	Product weight (different from variant weight)

Liquid: {{ product.metafields.ns.height.value }}{{ product.metafields.ns.height.unit }}
Admin shows unit selector alongside the value input
Use these when unit flexibility matters. For fixed-unit measurements (always in cm), number_decimal with unit in the key name (height_cm) is simpler.

Rating type

rating: Stores a rating with a scale. Format: { value: "4.5", scale_min: "0", scale_max: "5" }
Use for: difficulty ratings, technical ratings, curated quality scores
Distinct from product reviews (those are in the review app, not metafields)

File reference types

Type	Use case
`file_reference`	Any file — PDF, image, video
`image_reference`	Images only (renders via Shopify CDN)
`page_reference`	Link to a Shopify page
`product_reference`	Link to another Shopify product
`variant_reference`	Link to a specific product variant
`collection_reference`	Link to a Shopify collection
`metaobject_reference`	Link to a metaobject record

file_reference in practice

{% assign pdf = product.metafields.ns.manual.value %}
{% if pdf != blank %}
  <a href="{{ pdf | file_url }}" download>Download product manual (PDF)</a>
{% endif %}

product_reference in practice (related product)

{% assign related = product.metafields.ns.compatible_product.value %}
{% if related != blank %}
  <div class="related-product">
    <a href="{{ related.url }}">{{ related.title }}</a>
    {{ related.price | money }}
  </div>
{% endif %}

List types

Every type (except JSON, rating, file types) can be prefixed with list. to store multiple values:

List type	Use case	Example values
`list.single_line_text_field`	Tags, categories, compatible models	["Cotton", "Polyester", "Elastane"]
`list.number_integer`	Multiple numeric values	[38, 39, 40, 41, 42]
`list.product_reference`	Multiple related products	List of product GIDs
`list.color`	Available colour swatches	["#2c2926", "#ffffff", "#3a8c9c"]

{% comment %} Rendering a list metafield in Liquid {% endcomment %}
{% for material in product.metafields.ns.materials.value %}
  <li>{{ material }}</li>
{% endfor %}

Metaobject reference

Metaobjects are custom structured records — think custom post types in WordPress. A metaobject_reference metafield links a product to a metaobject record:

Use case: brands as metaobjects. Each brand has: name, logo, description, website URL. Products reference their brand metaobject.
Liquid: {{ product.metafields.ns.brand.value.fields.name.value }}
Benefits: update the brand record once, all products referencing it update automatically

Choosing the right type: quick guide

Data	Recommended type	Why
Colour name ("Midnight Navy")	single_line_text	Text, not a hex value
Colour hex for display swatch	color	Validates as hex, renders correctly
Dimensions (H×W×D)	single_line_text "75 × 43 × 33 cm"	Simpler than dimension type for display
Weight (always in kg)	number_decimal key: weight_kg	Simpler than weight type
PDF manual	file_reference	Stored in Shopify Files, CDN-served
Multiple compatible items	list.single_line_text	Array of text values
Yes/No flag	boolean	Explicit true/false, renders as checkbox
Year (e.g., 1987)	number_integer or single_line_text	Integer if you need to sort; text if display-only
External URL	url	Validated format, clean in Liquid
Related product	product_reference	Links to actual product object in Liquid

Storefront access setting

Each metafield definition must have "Storefront access" enabled to be readable via the Storefront API or by the Shopify Liquid templating engine in themes
Enable: Admin → Settings → Custom data → [metafield namespace] → edit definition → toggle "Storefront access"
Without storefront access: the metafield value is NOT available in product.metafields.namespace.key in Liquid or Storefront API. The field is admin-only.
Enable storefront access for all product-facing metafields. Only admin-internal fields (internal notes, cost price) should remain storefront-restricted.

The most common metafield type mistake is using single_line_text for everything — it's safe but misses type-specific features. A product_reference metafield gives you the full product object in Liquid (title, price, URL, images) rather than just a product handle string. A file_reference metafield gives you a Shopify CDN URL automatically. A boolean metafield renders as a checkbox in the Admin product editor, which is far less error-prone for merchant editing than a single_line_text field where they have to type "true" or "false". Spend ten minutes on type selection when creating metafield definitions — it pays dividends in both merchant editing experience and Liquid template simplicity.

Shopify metafield types: complete reference for WooCommerce migrators (2026)