How to Use Shopify Metafields to Enrich Your Product Pages

Every Shopify store has the same default product fields: title, description, price, images, and variants. That is fine for a basic store, but the moment you need to display wash instructions, technical specifications, delivery estimates, or ingredient lists, you hit a wall.

Metafields solve this problem. They let you attach structured custom data to products, variants, collections, and other resources — then display that data anywhere in your theme. No apps required, no code hacks, no stuffing everything into the product description.

This guide walks through the entire process from planning your metafield structure to displaying the data on your storefront. We use metafields on every Shopify store we build, and the difference in product page quality is significant.

What are Shopify metafields?

Metafields are custom data fields that extend Shopify's default data model. Think of them as extra columns in a spreadsheet — each product already has columns for title, price, and description, but metafields let you add columns for anything else your store needs.

Shopify supports metafields on these resources:

• Products — specifications, care instructions, materials, certifications
• Variants — variant-specific sizing data, unique identifiers, lead times
• Collections — featured product references, collection-specific banners
• Customers — loyalty tier, account manager, preferences
• Orders — special handling instructions, gift messages
• Pages and blog posts — custom layout data, related content references
• Shop — store-wide data like delivery cut-off times or promotion banners

Each metafield has a namespace, a key, a type, and a value. The type determines what kind of data it holds — single-line text, rich text, number, date, URL, colour, file reference, product reference, or a JSON object.

When should you use metafields?

Use metafields any time you need to store and display structured data that does not fit into Shopify's default fields. Here are the most common use cases we implement for clients:

Product specifications

Rather than burying specifications in the product description as free-form text, create dedicated metafields for dimensions, weight, material, country of origin, and other specs. This makes the data consistent, filterable, and easy to display in a structured layout.

Care instructions

Fashion and homeware brands benefit from standardised care instruction metafields. Create a metafield with a predefined list of values (machine wash, hand wash, dry clean only) and each product page displays the appropriate icons and text automatically.

Delivery information

Some products have different delivery timescales. A made-to-order item might take 4-6 weeks whilst a stock item ships next day. A metafield on the product or variant level lets you display the correct estimate without manual updates to the description.

Cross-selling references

Product reference metafields let you manually curate "complete the look" or "frequently bought together" sections. This gives you more control than algorithmic recommendations and is particularly effective for brands with small, curated catalogues.

Compliance and certifications

If you sell products that require specific certifications — organic, vegan, cruelty-free, FSC-certified — metafields let you attach these as structured data rather than just text in the description. You can then display certification badges consistently across all product pages.

Step 1: Plan your metafield structure

Before you create anything in Shopify admin, plan your metafield structure on paper or in a spreadsheet. This step prevents the mess that comes from creating metafields ad hoc.

For each metafield, define:

1. Resource type — which Shopify resource does this attach to? (product, variant, collection)
2. Namespace — a grouping label, typically "custom" for admin-created metafields
3. Key — the specific field name (e.g., "wash_instructions", "weight_kg")
4. Type — what data type? (single-line text, number, rich text, file, reference)
5. Validation — any constraints? (minimum value, maximum length, required values)
6. Where it displays — which theme section or template will render this data?

Here is an example planning table for a fashion brand:

Resource	Key	Type	Purpose
Product	fabric_composition	Single-line text	Display fabric percentages
Product	care_instructions	List of single-line text	Wash/care icons and labels
Product	size_guide	Metaobject reference	Link to category size guide
Variant	lead_time_days	Number (integer)	Variant-specific delivery estimate
Product	complementary_products	List of product references	Complete the look section

Spending thirty minutes on this planning step will save you hours of rework later. We have seen stores with dozens of redundant or poorly named metafields because nobody planned the structure upfront.

Step 2: Create metafield definitions

With your plan in hand, create the metafield definitions in Shopify admin.

Navigate to metafield settings

1. Go to Settings > Custom data in your Shopify admin
2. Select the resource type (Products, Variants, Collections, etc.)
3. Click Add definition

Fill in the definition

1. Name — a human-readable name (e.g., "Fabric Composition"). Shopify auto-generates the namespace and key from this.
2. Namespace and key — review the auto-generated values. The default namespace is "custom" and the key is a snake_case version of the name. You can change the key before saving but not after.
3. Description — add a clear description so your team knows what data goes here. This is especially important if multiple people manage products.
4. Type — select the appropriate data type from the dropdown.
5. Validation — add any validation rules. For numbers, set minimum and maximum values. For text, set character limits. For lists, define the accepted values.

Naming convention matters. Use descriptive, consistent keys. "wash_care" and "care_wash" and "washing_instructions" on different projects is a maintenance nightmare. Pick a convention and stick with it.

Understanding metafield types

Choosing the right type is critical because it affects how the data is validated, stored, and rendered:

• Single-line text — short text values like brand names or fabric compositions
• Multi-line text — longer text without formatting
• Rich text — formatted text with headings, bold, lists (renders as HTML)
• Integer — whole numbers (stock count, lead time in days)
• Decimal — numbers with decimal places (weight, dimensions)
• True or false — boolean values (is_gift_wrappable, is_made_to_order)
• Date — date values (launch date, expiry date)
• URL — web addresses (external documentation, certification links)
• Colour — hex colour values (for colour swatches)
• File reference — images, PDFs, or videos uploaded to Shopify Files
• Product reference — links to other products (for cross-selling)
• Collection reference — links to collections
• Metaobject reference — links to metaobject entries (for shared content like size guides)
• JSON — structured JSON data (for complex data structures)

For list values (e.g., multiple care instructions), enable the "List" option when creating the definition. This lets you store multiple values in a single metafield.

Step 3: Populate metafields with data

Once definitions are created, you need to fill in the data for each product. There are three approaches depending on your catalogue size.

Option A: Manual entry in Shopify admin

For small catalogues (under 100 products), manual entry works fine:

1. Open a product in Shopify admin
2. Scroll down to the Metafields section
3. Fill in each metafield value
4. Save the product

Option B: Bulk import via CSV

For larger catalogues, use Shopify's bulk editor or a CSV import:

1. Go to Products in Shopify admin
2. Select all products (or filter to a subset)
3. Click Edit products to open the bulk editor
4. Click Columns and add your metafield columns
5. Edit values inline or export, update in a spreadsheet, and re-import

For CSV imports, the column header format is product.metafields.custom.your_key. Getting this format right is essential — Shopify silently ignores columns with incorrect headers.

Option C: Shopify API

For very large catalogues or automated data pipelines, use the Shopify Admin API to set metafield values programmatically. This is the approach we use for stores with thousands of SKUs where metafield data comes from an ERP or PIM system.

// Example: Setting a metafield via the Shopify Admin API
const response = await fetch(
  `https://${shop}/admin/api/2024-01/products/${productId}/metafields.json`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Shopify-Access-Token': accessToken
    },
    body: JSON.stringify({
      metafield: {
        namespace: 'custom',
        key: 'fabric_composition',
        value: '95% organic cotton, 5% elastane',
        type: 'single_line_text_field'
      }
    })
  }
);

Step 4: Connect metafields to your theme

Creating metafields and populating them with data is only half the job. You need to connect them to your theme so they actually appear on your storefront.

Using the theme editor (no code)

If your theme supports Online Store 2.0 (all modern Shopify themes do), you can connect metafields through the theme editor:

1. Go to Online Store > Themes and click Customise
2. Navigate to a product page template
3. Add a section or block that accepts dynamic content (e.g., a text block, an image block)
4. Click the field you want to make dynamic — you will see a small database icon
5. Click the icon and select Product metafield
6. Choose the specific metafield definition from the list
7. Save

This approach works for straightforward display — showing text, images, or single values. For more complex layouts, you will need Liquid.

Using Liquid code

For custom layouts, conditional display logic, or metafield types that your theme sections do not natively support, you will need to edit your theme's Liquid templates.

Access a product metafield in Liquid with this syntax:

{{ product.metafields.custom.fabric_composition.value }}

{%- comment -%} Check if a metafield has a value before displaying {%- endcomment -%}
{% if product.metafields.custom.care_instructions.value != blank %}
  <div class="care-instructions">
    <h3>Care Instructions</h3>
    <ul>
      {% for instruction in product.metafields.custom.care_instructions.value %}
        <li>{{ instruction }}</li>
      {% endfor %}
    </ul>
  </div>
{% endif %}

{%- comment -%} Display a rich text metafield {%- endcomment -%}
{% if product.metafields.custom.product_story.value != blank %}
  <div class="product-story">
    {{ product.metafields.custom.product_story.value }}
  </div>
{% endif %}

Always wrap metafield output in a conditional check. If a metafield has no value for a particular product, you do not want to render an empty section with a heading and no content.

Displaying product reference metafields

Product reference metafields are powerful for cross-selling. Here is how to render a "Complete the Look" section using a list of product references:

{% if product.metafields.custom.complementary_products.value != blank %}
  <section class="complete-the-look">
    <h2>Complete the Look</h2>
    <div class="product-grid">
      {% for ref_product in product.metafields.custom.complementary_products.value %}
        <div class="product-card">
          <a href="{{ ref_product.url }}">
            <img src="{{ ref_product.featured_image | image_url: width: 400 }}"
                 alt="{{ ref_product.title }}">
            <h3>{{ ref_product.title }}</h3>
            <p>{{ ref_product.price | money }}</p>
          </a>
        </div>
      {% endfor %}
    </div>
  </section>
{% endif %}

This is the kind of enrichment that transforms a basic product page into something that genuinely helps customers make buying decisions. For more on building effective product pages, see our metafields and metaobjects guide.

Step 5: Advanced metafield techniques

Variant-level metafields

Product-level metafields apply to the entire product, but sometimes you need data that varies by variant. A shirt might have different fabric compositions for different colours, or a furniture item might have different lead times depending on the finish.

Create variant metafield definitions under Settings > Custom data > Variants. Access them in Liquid with:

{{ product.selected_or_first_available_variant.metafields.custom.lead_time_days.value }}

Using metafields for SEO

Metafields can improve your search visibility when used strategically:

• Create a metafield for a unique meta description per product instead of auto-generating from the product description
• Add structured specification data that search engines can parse
• Use rich text metafields for additional content sections that target long-tail keywords
• Add FAQ metafields to product pages with structured data markup for FAQ rich results

We cover this in more depth in our custom theme development guide.

Metafields with Shopify Flow

You can use Shopify Flow to automate metafield updates. For example:

• Automatically set a "new_arrival" boolean metafield to true when a product is created, then set it to false after 30 days
• Update a "bestseller" metafield based on sales velocity
• Set a "low_stock" metafield when inventory drops below a threshold

Metafields vs metaobjects

A common source of confusion is the difference between metafields and metaobjects. The short version:

• Metafields attach data to an existing resource (product, collection, customer). They do not exist independently.
• Metaobjects are standalone content entries with their own structure. They exist independently and can be referenced by metafields on products or other resources.

Use metaobjects when you have shared, reusable content. A size guide that applies to multiple products should be a metaobject, not duplicated as a metafield on every product. A designer profile referenced by multiple products should be a metaobject.

Use metafields for data that is unique to each resource. Fabric composition, weight, and care instructions are typically unique per product — these should be metafields.

For a deeper exploration of both, read our product filters guide which covers how metafields integrate with filtering and navigation.

Common mistakes to avoid

1. Creating metafields without definitions

You can create metafields via the API without a definition, but these "orphaned" metafields will not appear in the Shopify admin UI or the theme editor. Always create definitions first.

2. Using the wrong data type

Storing a number as text means you cannot sort or filter by it. Storing a product reference as a text URL means you cannot access the referenced product's data in Liquid. Choose the correct type from the start.

3. Not validating data

If a weight metafield accepts any text, someone will eventually enter "about 2kg" instead of "2". Use validation rules to enforce data quality.

4. Ignoring performance

Each metafield reference in Liquid is a database query. If you have 20 product reference metafields and render all their images, titles, and prices, your product page will slow down. Be deliberate about what you load.

5. Forgetting mobile

Metafield-driven content sections need to work on mobile. A specification table that looks great on desktop might be unusable on a phone screen. Test your metafield layouts on mobile devices.

---

Metafields are one of Shopify's most powerful features, yet most stores barely use them. A well-planned metafield structure transforms your product pages from basic listings into rich, informative shopping experiences that build trust and drive conversions.

The key is planning before building. Map out your data structure, choose the right types, and connect everything to your theme in a way that enhances the customer experience without hurting performance.

If you would like help setting up metafields for your store — or you need a custom Shopify build that uses metafields from the ground up — get in touch. We build every store with structured data at its core.