Metafields in Aqua / Liquid

Every owner that supports metafields exposes a metafields drop on its Aqua/Liquid object. Access follows the standard {owner}.metafields.{namespace}.{key} pattern, so theme code that reads metafields stays portable. For the full data model (types, owners, validations, REST API), see Metafields Overview.

The basic pattern

{{ product.metafields.custom.badge }}                  {# scalar value, type-aware toString #}
{{ product.metafields.custom.warranty_years }}         {# 5 #}
{{ product.metafields.custom.warranty_years.value }}   {# 5 (decoded) #}
{{ product.metafields.custom.warranty_years.type }}    {# "number_integer" #}
{{ product.metafields.custom.does_not_exist }}         {# (empty, no error) #}

{{ … }} triggers toString() on the metafield drop, which renders type-aware (see render rules below). .value returns the decoded value (number, array, object, …). .type returns the type string. Missing namespaces and missing keys return an empty drop — {{ … }} prints empty string, {% if … %} is falsy, no exception is thrown. This makes it safe to reference fields that may not exist on every resource.

Owners

Owner	Drop
Account / store	`shop.metafields`
Product	`product.metafields`
Variant	`variant.metafields`
Collection	`collection.metafields`
Customer	`customer.metafields`
Order	`order.metafields`
Page	`page.metafields`
Blog	`blog.metafields`
Article	`article.metafields`

Render rules per type

{{ metafield }} (without .value) calls a type-aware toString:

Type	`{{ mf }}` renders	`{{ mf.value }}` returns
`single_line_text_field` / `multi_line_text_field`	string	string
`rich_text_field` (alias `rich_text`)	raw HTML, unescaped	raw HTML string
`number_integer`	integer	number
`number_decimal`	decimal	number
`boolean`	`"true"` or `"false"`	bool
`color`	`"#RRGGBB"`	string
`date` / `date_time`	ISO string	string
`url`	URL string	string
`weight` / `dimension` / `volume`	`"<value> <unit>"`	`{ unit, value }`
`money`	`{amount, currency_code}` (use `\| money` filter)	object
`rating`	`{value, scale_min, scale_max}`	object
`file_reference`	URL string	URL string
`*_reference` (other)	id string	id string (or resolved drop, if resolver wired)
`list.*`	iterable array of value-drops	array
`json` / `json_string`	stringified JSON	parsed value

Examples

Text and numbers

{% if product.metafields.custom.badge %}
  <span class="badge">{{ product.metafields.custom.badge }}</span>
{% endif %}

<p>Warranty: {{ product.metafields.custom.warranty_years }} years</p>

Rich text (HTML)

The rich_text_field type renders the stored HTML unescaped — perfect for care instructions, warnings, formatted descriptions:

<div class="care">
  {{ product.metafields.custom.care_instructions }}
</div>

Boolean conditionals

{% if product.metafields.custom.is_featured %}
  <div class="featured-banner">Featured product</div>
{% endif %}

Lists

{% for tag in product.metafields.custom.tags %}
  <span class="tag">{{ tag }}</span>
{% endfor %}

{% for review in product.metafields.reviews.list %}
  <article>
    <strong>{{ review.author }}</strong>
    <p>{{ review.body }}</p>
  </article>
{% endfor %}

Money

<p>Deposit: {{ product.metafields.custom.deposit | money }}</p>

Measurements

<dl>
  <dt>Weight</dt>
  <dd>{{ product.metafields.specs.weight }}</dd>     {# "1.2 KILOGRAMS" #}
  <dt>Dimensions</dt>
  <dd>{{ product.metafields.specs.dimension }}</dd>  {# "30 CENTIMETERS" #}
</dl>

Color

<style>
  .product-card {
    border-color: {{ product.metafields.custom.brand_color }};
  }
</style>

Date

{% if product.metafields.events.launches_on %}
  <p>Launching {{ product.metafields.events.launches_on | date: "%B %d, %Y" }}</p>
{% endif %}

Reference (file)

{% if product.metafields.custom.spec_sheet %}
  <a href="{{ product.metafields.custom.spec_sheet }}">Download spec sheet</a>
{% endif %}

JSON

{% assign specs = product.metafields.custom.specifications.value %}
<dl>
  <dt>Width</dt><dd>{{ specs.dimensions.width }}cm</dd>
  <dt>Weight</dt><dd>{{ specs.weight }}</dd>
</dl>

Defensive access

Use {% if %} to guard optional fields — missing keys are falsy:

{% if product.metafields.custom.warranty_years %}
  <p>Warranty: {{ product.metafields.custom.warranty_years }} years</p>
{% endif %}

Or fall back with default:

<p>Color: {{ product.metafields.custom.brand_color | default: "#000000" }}</p>

Across owner types

Same access pattern, every owner:

{{ shop.metafields.legal.tos_url }}
{{ collection.metafields.layout.banner_color }}
{{ customer.metafields.loyalty.tier }}
{{ order.metafields.fulfilment.gift_message }}
{{ page.metafields.seo.canonical }}
{{ blog.metafields.brand.theme_color }}
{{ article.metafields.editorial.byline }}
{{ variant.metafields.specs.weight }}

Performance

Metafields are bulk-loaded server-side alongside the parent resource — one query loads the resource, one query loads all its metafields, and both are cached together. There is no per-field network round-trip from Liquid. When a metafield is written via the REST API, the relevant caches are invalidated automatically. The next render sees the new value within ~1 second.

​Metafields in Aqua / Liquid

​The basic pattern

​Owners

​Render rules per type

​Examples

​Text and numbers

​Rich text (HTML)

​Boolean conditionals

​Lists

​Money

​Measurements

​Color

​Date

​Reference (file)

​JSON

​Defensive access

​Across owner types

​Performance

​See also