Variant Descriptions

Scale & Enterprise Plans

A complete guide to generating, storing, and displaying per-variant AI descriptions on your Shopify storefront.

1. Overview

Most Shopify stores display a single product description that covers every variant. That works when variants differ only by size or colour, but it falls short when each variant is a genuinely different item—different specifications, materials, use-cases, or supplier data.

Variant descriptions solve this by giving every variant its own unique, AI-generated description. When a customer selects a specific variant (for example, a particular colour or model), the storefront can display a description tailored to that exact item instead of a generic overview.

Benefits include:

• Better product detail – Each variant can highlight its own unique specifications, materials, or features.
• Improved SEO – Unique content per variant helps search engines index your products more thoroughly.
• Higher conversion rates – Customers get relevant information for the exact item they are considering, reducing uncertainty.
• Reduced returns – Accurate, variant-specific details help customers make better purchasing decisions.

2. How Importier Creates Them

During the import flow, toggle on Variant Descriptions in the Variants step. When enabled, Importier does the following:

1. The parent product receives a full AI-generated description as usual.
2. Each variant is then processed individually. Importier uses the variant's specific barcode data, SKU, option values (such as colour, size, or model), and any enriched data to generate a unique description.
3. The generated description is stored as a metafield on each Shopify ProductVariant resource, using the namespace and key custom.variant_description.

Metafield details: Namespace: custom | Key: variant_description | Type: rich_text_field (stores formatted HTML content)

Because the description is a standard Shopify metafield, it is accessible in the theme editor, via the Storefront API, and in any Liquid template—no third-party app blocks required.

3. Displaying in Your Theme

There are several ways to display variant descriptions on your storefront, ranging from no-code to developer-level. Choose the method that best fits your comfort level.

Method 1: Custom Liquid Block (Recommended)

This is the simplest approach and requires no theme file editing. It works with any Online Store 2.0 theme.

Steps:

1. In your Shopify admin, go to Online Store → Themes.
2. Click Customize on your active theme.
3. Navigate to a Product page template using the page selector dropdown at the top.
4. In the left sidebar, find the product information section. Click Add block.
5. Select Custom Liquid from the block list.
6. Paste the following Liquid code into the Custom Liquid field:

{% if product.selected_or_first_available_variant.metafields.custom.variant_description %}
  <div class="variant-description">
    {{ product.selected_or_first_available_variant.metafields.custom.variant_description | metafield_tag }}
  </div>
{% endif %}

7. Drag the block to your preferred position (typically below the product description or below the variant selector).
8. Click Save.

Why metafield_tag? The metafield_tag Liquid filter renders a rich_text_field metafield as proper HTML. Without it, raw JSON or escaped HTML tags may appear on the page. Never use | raw for rich text metafields—always use | metafield_tag.

Limitation: This method displays the description for the first available variant (or the currently selected variant in the URL) when the page loads. If a customer selects a different variant using the on-page selectors, the description will not update automatically. For dynamic switching, use Method 2 below.

Method 2: Dynamic Variant Switching with JavaScript

When a customer clicks a different variant option (colour, size, model), the default Custom Liquid block does not update the variant description. This method adds a small JavaScript snippet that listens for variant changes and swaps the description in real time.

Add a Custom Liquid block (same steps as Method 1) and paste the following code:

<div id="variant-description-container">
  {% if product.selected_or_first_available_variant.metafields.custom.variant_description %}
    {{ product.selected_or_first_available_variant.metafields.custom.variant_description | metafield_tag }}
  {% endif %}
</div>

<script>
  (function() {
    // Build a map of variant ID -> description HTML
    var variantDescriptions = {};
    {% for variant in product.variants %}
      {% if variant.metafields.custom.variant_description %}
        variantDescriptions[{{ variant.id }}] = {{ variant.metafields.custom.variant_description | metafield_tag | json }};
      {% endif %}
    {% endfor %}

    function updateVariantDescription(variantId) {
      var container = document.getElementById('variant-description-container');
      if (!container) return;
      if (variantDescriptions[variantId]) {
        container.innerHTML = variantDescriptions[variantId];
        container.style.display = '';
      } else {
        container.innerHTML = '';
        container.style.display = 'none';
      }
    }

    // Listen for Shopify's variant change event
    document.addEventListener('variant:changed', function(event) {
      if (event.detail && event.detail.variant) {
        updateVariantDescription(event.detail.variant.id);
      }
    });

    // Also listen for URL changes (some themes use URL-based variant switching)
    var observer = new MutationObserver(function() {
      var params = new URLSearchParams(window.location.search);
      var variantId = params.get('variant');
      if (variantId) updateVariantDescription(parseInt(variantId));
    });
    observer.observe(document.querySelector('body'), { childList: true, subtree: true });
  })();
</script>

How it works:

1. Server-side rendering: On page load, Liquid renders the initial variant description inside the container div, so the page is never empty.
2. Description map: A Liquid for loop builds a JavaScript object mapping each variant ID to its pre-rendered description HTML. This happens at page-build time, so there are no additional API calls at runtime.
3. Event listener: The script listens for the variant:changed custom event, which most Shopify themes dispatch when the customer selects a different variant.
4. URL observer: As a fallback, a MutationObserver watches for DOM changes and checks the URL ?variant= parameter. This covers themes that switch variants by updating the URL rather than dispatching events.

Theme compatibility note: Some themes dispatch variant:changed, while others use different event names such as shopify:variant:change or fire a custom callback. If the description does not update on variant selection, inspect your theme's JavaScript to find the correct event name and update the addEventListener call accordingly.

Method 3: Editing Theme Code Directly (Advanced)

For developers who prefer embedding variant descriptions directly in the product template rather than using a Custom Liquid block, you can edit the theme files. This approach gives you full control over placement and integration with existing template logic.

Steps:

1. In your Shopify admin, go to Online Store → Themes.
2. Click the three-dot menu (…) on your active theme and select Edit code.
3. Locate the product template file. Common locations include:
   • sections/main-product.liquid – Dawn and most Online Store 2.0 themes
   • sections/product-template.liquid – some third-party themes
   • templates/product.liquid – legacy (vintage) themes
4. Find the area where variant information or the product description is rendered. Look for references to product.description or the variant picker block.
5. Insert the following Liquid code immediately after the product description or variant selector block:

{% comment %} Variant Description - Importier {% endcomment %}
{% if product.selected_or_first_available_variant.metafields.custom.variant_description %}
  <div class="variant-description" id="variant-description-container">
    {{ product.selected_or_first_available_variant.metafields.custom.variant_description | metafield_tag }}
  </div>
{% endif %}

6. If you need dynamic switching, add the JavaScript from Method 2 in a <script> tag in the same file or in your theme's global JavaScript file.
7. Click Save.

Back up your theme first: Before editing theme code, always duplicate your theme as a backup. Go to Online Store → Themes, click the three-dot menu, and select Duplicate. This gives you a safe rollback point if anything goes wrong.

Styling the Description

Variant descriptions rendered via metafield_tag output standard HTML elements (paragraphs, headings, lists, etc.). Add the following CSS to style the description container. You can place this in a <style> tag within your Custom Liquid block, or add it to your theme's stylesheet (typically assets/base.css or similar).

.variant-description {
  margin-top: 16px;
  padding: 16px;
  border-top: 1px solid #e5e5e5;
  font-size: 14px;
  line-height: 1.6;
}
.variant-description h2,
.variant-description h3 {
  margin-top: 1em;
  margin-bottom: 0.5em;
}
.variant-description ul,
.variant-description ol {
  padding-left: 1.5em;
  margin-bottom: 1em;
}
.variant-description p {
  margin-bottom: 0.8em;
}

Feel free to adjust colours, spacing, and typography to match your theme. Common customisations include:

• Adding a background colour or card-style border to visually distinguish the variant description from the main product description.
• Using a smaller font size to create a visual hierarchy between the main description and the variant-specific details.
• Adding a heading such as "About this variant" above the container for clarity.
• Adding a smooth CSS transition (e.g., opacity or max-height) so the description fades in gracefully when the customer switches variants.

4. Troubleshooting

Problem	Solution
Description does not appear at all	Verify the metafield exists: in Shopify admin, go to Products → [Product] → [Variant] and scroll to the Metafields section. Confirm custom.variant_description has a value. Check that you used the exact metafield path: product.selected_or_first_available_variant.metafields.custom.variant_description. Ensure the Custom Liquid block is placed inside the Product information section, not in a standalone section outside the product template. Confirm that variant descriptions were enabled during import. The feature must be toggled on before importing; it does not retroactively generate descriptions for previously imported products.
Description does not change when selecting a different variant	The basic Custom Liquid method (Method 1) only renders the initially selected variant's description at page load time. You need the JavaScript-based approach from Method 2 to update the description dynamically when a customer selects a different variant.
HTML tags showing as plain text	You are likely outputting the metafield value directly or using | raw. Variant descriptions are stored as rich_text_field metafields, which require the | metafield_tag Liquid filter to render as proper HTML. Replace your output line with: {{ variant.metafields.custom.variant_description | metafield_tag }}
Description appears in the wrong location	In the theme editor, drag the Custom Liquid block to reposition it within the product information section. Blocks are rendered in the order they appear in the sidebar. Place it below the variant selector or below the main product description for the best user experience.
JavaScript variant switching does not work	Different themes emit different events when a variant is selected. Open your browser's developer console, switch a variant, and check for dispatched events. You may need to change variant:changed in the script to your theme's specific event name (e.g., shopify:variant:change or a theme-specific event).

5. Compatible Themes

Variant descriptions work with all Online Store 2.0 themes that support Custom Liquid blocks and variant metafields. This includes all free Shopify themes:

• Dawn (Shopify's default reference theme)
• Refresh
• Craft
• Sense
• Ride
• Taste
• Studio
• Publisher
• Crave
• Origin

Most third-party Online Store 2.0 themes from the Shopify Theme Store are also compatible. Legacy (vintage) themes that do not support sections or metafields may require additional customisation via Method 3.

6. Plan Requirement

Variant descriptions are available exclusively on the Scale and Enterprise plans. If you are on the Starter or Growth plan, the Variant Descriptions toggle will not appear during import.

To upgrade your plan, go to Settings → Billing in the Importier app, or visit the Importier listing on the Shopify App Store.