Shopify Metafields Beginner Tutorial

When standard fields are not enough

Product titles and descriptions cover catalog basics. Metafields store structured extras—material, care instructions, size charts, collection banner copy—that templates read via Liquid. A practical implementation usually needs a definition in admin, a namespace/key contract, and blank guards in templates.

Definitions: namespace and key

Create definitions under Settings → Custom data. Each field has a namespace and key. In Liquid:

{{ product.metafields.custom.care_guide }}

During theme customization, empty output often means the metafield was never filled, the namespace changed after migration, or the definition targets variants while the template reads product level.

Types and safe output

• Single line text: output with | escape inside a blank guard
• Rich text: use | metafield_tag—not raw output
• List types: loop .value in modern Liquid

{% if product.metafields.custom.care_guide != blank %}
  <div class="care-guide rte">
    {{ product.metafields.custom.care_guide | metafield_tag }}
  </div>
{% endif %}

Fallback handling

Never assume a metafield exists on every product. Use {% if != blank %} or provide a section setting fallback when data is optional.

{% assign material = product.metafields.custom.material %}
{% if material != blank %}
  <p>Material: {{ material | escape }}</p>
{% endif %}

Collections and articles

{{ collection.metafields.custom.banner_text | escape }}
{{ article.metafields.custom.series_name | escape }}

Takeaway

Metafields extend Shopify objects—document namespace keys like an API, guard blanks, and match output filters to field types. Layout toggles belong in Dynamic Settings.

Metafields fail silently in production

The most common "bug" is an empty metafield—not wrong Liquid. Merchant never filled the field, namespace changed after migration, or the definition targets variants but the template reads product level. Always {% if != blank %} before output and verify definitions in admin on staging.

Namespace discipline on agency projects

One namespace contract per client—document custom.ingredients, custom.care_guide, etc. in handoff docs. Mixing global and custom namespaces across snippets causes rescue projects where half the templates reference obsolete keys.

List and metaobject metafields

{% for item in product.metafields.custom.highlights.value %}
  <li>{{ item }}</li>
{% endfor %}

List types need .value in modern Liquid. Metaobjects power complex content models—start simple with product metafields before jumping to metaobject templates.

Connecting schema to metafields

Dynamic sources let section settings bind to metafields—when the binding breaks, settings look frozen. Document which sections use dynamic sources at handoff. Deeper patterns: metafields on client stores.

Troubleshooting

• Blank output → check definition namespace/key in admin
• HTML stripped → use metafield_tag for rich text types
• Works in admin preview, not storefront → wrong template or market scope