Shopify Metafields: creating, maintaining and correctly displaying them in the theme (OS 2.0)

Direct solution coming soon

• First, create a metafield definition: Settings → User-defined data .
• Then maintain values ​​on the object (e.g., product): Products → (Open product) → Metafields .
• Output the metafield in the theme: in the theme editor via Dynamic Source or via Liquid with blank check .
• Use the correct type (text, number, file, reference) and pay attention to namespace + key .

When does this occur?

• You want to maintain additional product information (e.g., material, care instructions, manufacturer data) that does not exist in standard fields.
• You don't see a suitable field under "Dynamic Source" in the theme editor.
• Nothing appears in the store, or it displays a "Liquid error" message , even though a value has been entered.
• You have an OS 2.0 theme, but the Metafield is not selectable in the Section/Block.

Technical background: Why does this happen?

• Shopify distinguishes between metafield definition (schema: name, namespace/key, type, validation) and metafield value (concrete content of the object).
• The theme editor (Dynamic Source) only displays meta fields if a definition exists and the field type matches the input field.
• In Liquid, the output depends on the type: many metafields return an object; often .value must be used (especially with structured types, lists, references).
• OS 2.0 themes use JSON templates and sections. Whether a metafield is clickable depends on whether the section/block supports a dynamic source.

Step-by-step: Here's how to implement it

1. Create a metafield definition

   • Open Settings → Custom Data .
   • Select the resource, e.g., products (or variants, collections, customers, orders).
   • Click Add definition .
   • Give it a name and set the namespace and key (e.g., custom.material ).
   • Choose the appropriate content type (e.g., "Single-line text", "Multi-line text", "Number", "File", "Product reference").
   • Optional: Validation (e.g., maximum length) and whether the field should be visible for storefronts (depending on Shopify UI/version).
   • Save.

2. Maintain Metafield value on the product

   • Open Products → (Select product) .
   • Scroll to the Metafields section (appears after creating the definition).
   • Enter the value (e.g. "100% cotton") and save the product.

3. Output in the Theme Editor (Dynamic Source) – preferred for OS 2.0

   • Go to Online Shop → Themes → Customize .
   • Open a product page (template) where you want to display the field.
   • Add a block/section that supports dynamic content (e.g., "Text", "Collapsible row", "Rich text" – depending on the theme).
   • Click the Dynamic Source icon in the text input field and select your metafield (e.g., "Material").
   • Save and check in the frontend.

4. Output via Liquid (if Dynamic Source is not possible)

   • Go to Online Shop → Themes → … → Edit Code .
   • Open the relevant template/section (e.g., sections/main-product.liquid or a snippet file, depending on the theme).
   • Add an output with blank check (example of a product metafield custom.material ):

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

   • Save and check the product page. If you don't see a value: make sure that a value is set on the product and that the namespace/key matches exactly.

5. Type-specific testing

   • File : Output is usually via a file object; check if your theme expects this. Dynamic Source is often simpler than Liquid.
   • Lists (e.g., a list of texts): you need a loop over metafield.value .
   • References (product/variant/page): .value provides an object (e.g., product) that you need to render further.

Common mistakes

• Metafield does not appear in the theme editor – Cause: No definition created or incorrect resource type (e.g., definition under "Variants," but value expected on the product). Fix: Create the definition under the correct resource and update the value on the appropriate object.
• Nothing is displayed in the frontend – cause: the value is empty, or Liquid is not checking for blank content and is rendering empty content. Fix: Set the value on the product and use Liquid with blank checking.
• Liquid displays the object instead of its content / outputs nothing – cause: .value is missing (common with structured types, lists, references). Fix: Use {{ metafield.value }} in Liquid and iterate for lists.
• The namespace/key combination is not an exact match – cause: typo or a different namespace (e.g., custom vs. globals ). Fix: Check the definition and copy it exactly: product.metafields.<namespace>.<key> .
• Theme/Section does not support Dynamic Sources – Reason: Not every input field/theme element is "dynamic" (theme-dependent). Fix: Use a different block (e.g., Collapsible Row) or add Liquid output in a suitable section.

Best Practices

• Namespace convention : group custom fields under custom (e.g., custom.material , custom.care ) instead of mixing different namespaces.
• Choose the correct type : avoid "multi-line text" fields for structured data; use references/files/lists appropriately so that the theme editor and validation work properly.
• Encapsulate output logic : move reusable metafield outputs into a snippet (theme-dependent) instead of duplicating them multiple times in sections.
• Define fallbacks : if the metafield is empty, either display nothing (blank check) or set a clear default (only if technically correct).
• Prefer OS 2.0 : if possible, use Dynamic Source instead of code; this reduces merge conflicts during theme updates.

Brief summary

• Without a metafield definition, the field is neither easy to maintain nor reliably usable in the theme.
• Definition: Settings → User-defined data ; Value maintenance: directly on the object (e.g., product).
• OS-2.0: Output preferably via Dynamic Source in the Theme Editor.
• When outputting liquid, almost always use blank check and use .value depending on the type.
• The most common problems are incorrect resource type, incorrect namespace/key, and unsupported dynamic sources.