Shopify UnitPriceSpecification Schema — Per-Unit Pricing for Grocery, Bulk & Fabric Stores

Why Shopify Stores Miss Unit Pricing in Structured Data

Shopify has native unit pricing built into the Liquid theme layer: variant.unit_price returns the price per unit (e.g., $2.99), and variant.unit_price_measurement returns the measurement object (e.g., 100g). But this information lives entirely in the HTML price display layer and is never output in the product JSON-LD that structured data crawlers consume.

The consequence for AI shopping agents is significant: a query like "cheapest ground coffee per 100g under $3" requires comparing unit prices across a 250g bag at $6.49, a 500g bag at $11.99, and a 1kg bag at $21.99. Without UnitPriceSpecification in JSON-LD, an AI agent must either parse the product description for weight information and calculate the unit price itself (error-prone), or exclude your products from comparison entirely.

Store types that need UnitPriceSpecification

UnitPriceSpecification vs. Standard Offer Price

The standard Offer price is the total amount a buyer pays at checkout — it drives the transaction. UnitPriceSpecification is an additional price specification that normalizes the price to a standard reference unit for comparison shopping. Both coexist on the same product: the standard price for the transaction, the unit price for comparison.

Schema.org allows two ways to attach UnitPriceSpecification to a product:

1. priceSpecification on the Offer — attach a UnitPriceSpecification object alongside the standard price field. This is the cleaner pattern when the product has a single selling unit.
2. offers array with a dedicated Offer of type UnitPriceSpecification — output a second Offer object where @type is UnitPriceSpecification. This pattern is required when the unit price is the primary price (e.g., fabric sold strictly by the metre).

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Single-Origin Ethiopian Coffee Beans — Medium Roast — 500g",
  "description": "Washed Yirgacheffe coffee beans, medium roast. Floral and bright with notes of jasmine, bergamot, and stone fruit. Third-wave roasted weekly.",
  "sku": "COFFEE-ETH-500G",
  "brand": { "@type": "Brand", "name": "Bright Grounds Roastery" },
  "offers": {
    "@type": "Offer",
    "price": "16.99",
    "priceCurrency": "USD",
    "availability": "https://schema.org/InStock",
    "url": "https://example.com/products/ethiopian-coffee-500g",
    "priceSpecification": [
      {
        "@type": "UnitPriceSpecification",
        "price": "3.40",
        "priceCurrency": "USD",
        "referenceQuantity": {
          "@type": "QuantitativeValue",
          "value": "100",
          "unitCode": "GRM",
          "unitText": "100g"
        },
        "unitCode": "GRM",
        "unitText": "per 100g"
      }
    ]
  }
}
</script>

In this example: the Offer price $16.99 is the checkout price for the 500g bag. The UnitPriceSpecification price $3.40 is the normalized price per 100g, computed from 16.99 / 5 = 3.398 ≈ $3.40. AI shopping agents use the $3.40 figure to compare this product against a 250g bag at $9.49 (= $3.80/100g) and a 1kg bag at $29.99 (= $3.00/100g).

UN/CEFACT Unit Code Reference

Important: UN/CEFACT unit codes are case-sensitive and must be uppercase — KGM not kgm, LTR not ltr. Schema.org validators will accept lowercase, but Google's structured data processing and AI agent parsers trained on the official vocabulary expect the canonical uppercase form. Always pair unitCode with unitText for human-readable display fallback.

Fabric Store Pattern: Metre-Based Unit Pricing

Fabric sold by the metre is a specialized case where the per-unit (per-metre) price IS the primary pricing unit — buyers select how many metres they want, and the total price is calculated at checkout. This requires a different schema pattern: the Offer itself uses @type: "UnitPriceSpecification" as the primary price type.

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Belgian Linen Fabric — Natural Undyed — 150cm Width",
  "description": "100% Belgian linen, natural undyed, 150cm wide. Prewashed and preshrunk. Suitable for clothing, home décor, and upholstery.",
  "sku": "FABRIC-LINEN-BE-NATURAL-150",
  "brand": { "@type": "Brand", "name": "Atelier Textile" },
  "offers": {
    "@type": "UnitPriceSpecification",
    "price": "18.50",
    "priceCurrency": "USD",
    "availability": "https://schema.org/InStock",
    "url": "https://example.com/products/belgian-linen-natural",
    "referenceQuantity": {
      "@type": "QuantitativeValue",
      "value": "1",
      "unitCode": "MTR",
      "unitText": "metre"
    },
    "unitCode": "MTR",
    "unitText": "per metre",
    "billingIncrement": 0.1,
    "description": "Minimum order 0.5m. Sold in 0.1m increments. Enter number of metres required in quantity field."
  }
}

The billingIncrement: 0.1 signals that buyers can purchase in 0.1-metre steps (10cm increments). The minimum purchase is 0.5 metres, which would be expressed separately via a QuantitativeValue on an eligibleQuantity property if needed for procurement queries. For most fabric stores, the billingIncrement and the description field covering minimum order requirements provide sufficient context for AI shopping agents.

Multi-Size Product: Unit Price Across Variants

When a single product is available in multiple sizes (250g, 500g, 1kg), each variant has a different unit price. In Shopify structured data, each size variant should be a separate Offer with its own UnitPriceSpecification. Wrap all size variants in a ProductGroup to signal that they are the same product in different sizes.

{
  "@context": "https://schema.org",
  "@type": "ProductGroup",
  "name": "Grass-Fed Whey Protein Isolate — Natural Flavour",
  "description": "Grass-fed whey protein isolate, 90% protein content, unflavoured. Cold-processed, no artificial sweeteners.",
  "brand": { "@type": "Brand", "name": "Clean Protein Co." },
  "variesBy": "https://schema.org/size",
  "hasVariant": [
    {
      "@type": "Product",
      "name": "Grass-Fed Whey Protein Isolate — 500g",
      "sku": "WPI-NATURAL-500G",
      "size": "500g",
      "offers": {
        "@type": "Offer",
        "price": "34.99",
        "priceCurrency": "USD",
        "availability": "https://schema.org/InStock",
        "priceSpecification": [{
          "@type": "UnitPriceSpecification",
          "price": "7.00",
          "priceCurrency": "USD",
          "referenceQuantity": { "@type": "QuantitativeValue", "value": "100", "unitCode": "GRM", "unitText": "100g" },
          "unitText": "per 100g"
        }]
      }
    },
    {
      "@type": "Product",
      "name": "Grass-Fed Whey Protein Isolate — 1kg",
      "sku": "WPI-NATURAL-1KG",
      "size": "1kg",
      "offers": {
        "@type": "Offer",
        "price": "59.99",
        "priceCurrency": "USD",
        "availability": "https://schema.org/InStock",
        "priceSpecification": [{
          "@type": "UnitPriceSpecification",
          "price": "6.00",
          "priceCurrency": "USD",
          "referenceQuantity": { "@type": "QuantitativeValue", "value": "100", "unitCode": "GRM", "unitText": "100g" },
          "unitText": "per 100g"
        }]
      }
    },
    {
      "@type": "Product",
      "name": "Grass-Fed Whey Protein Isolate — 2kg",
      "sku": "WPI-NATURAL-2KG",
      "size": "2kg",
      "offers": {
        "@type": "Offer",
        "price": "104.99",
        "priceCurrency": "USD",
        "availability": "https://schema.org/InStock",
        "priceSpecification": [{
          "@type": "UnitPriceSpecification",
          "price": "5.25",
          "priceCurrency": "USD",
          "referenceQuantity": { "@type": "QuantitativeValue", "value": "100", "unitCode": "GRM", "unitText": "100g" },
          "unitText": "per 100g"
        }]
      }
    }
  ]
}

With this markup, an AI agent responding to "best value protein powder per 100g" can compute: 500g = $7.00/100g, 1kg = $6.00/100g, 2kg = $5.25/100g — and correctly identify the 2kg option as the best unit value. Without the UnitPriceSpecification, the agent sees $34.99, $59.99, and $104.99 — total prices that cannot be compared without knowing each product's weight.

Dawn Liquid Snippet: UnitPriceSpecification from Shopify Unit Pricing

Shopify exposes unit pricing via variant.unit_price (the per-unit price in cents / smallest currency unit) and variant.unit_price_measurement (an object with measured_type, quantity_value, quantity_unit, reference_value, reference_unit). Map these to UnitPriceSpecification properties.

{% comment %} unit-price-schema.liquid — UnitPriceSpecification from Shopify native unit pricing {% endcomment %}
{% assign v = product.selected_or_first_available_variant %}

{% if v.unit_price_measurement %}
{% assign m = v.unit_price_measurement %}

{% comment %} Map Shopify measurement units to UN/CEFACT codes {% endcomment %}
{% assign unit_code = 'C62' %}
{% assign unit_display = m.reference_unit %}
{% case m.reference_unit %}
  {% when 'g' %}{% assign unit_code = 'GRM' %}{% assign unit_display = 'g' %}
  {% when 'kg' %}{% assign unit_code = 'KGM' %}{% assign unit_display = 'kg' %}
  {% when 'mg' %}{% assign unit_code = 'MGM' %}{% assign unit_display = 'mg' %}
  {% when 'ml' %}{% assign unit_code = 'MLT' %}{% assign unit_display = 'ml' %}
  {% when 'l' %}{% assign unit_code = 'LTR' %}{% assign unit_display = 'l' %}
  {% when 'm' %}{% assign unit_code = 'MTR' %}{% assign unit_display = 'm' %}
  {% when 'cm' %}{% assign unit_code = 'CMT' %}{% assign unit_display = 'cm' %}
  {% when 'fl_oz' %}{% assign unit_code = 'OZA' %}{% assign unit_display = 'fl oz' %}
  {% when 'oz' %}{% assign unit_code = 'ONZ' %}{% assign unit_display = 'oz' %}
  {% when 'lb' %}{% assign unit_code = 'LBR' %}{% assign unit_display = 'lb' %}
  {% when 'ft' %}{% assign unit_code = 'FOT' %}{% assign unit_display = 'ft' %}
{% endcase %}

{% assign unit_price_decimal = v.unit_price | money_without_currency %}

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": {{ product.title | json }},
  "offers": {
    "@type": "Offer",
    "price": {{ v.price | money_without_currency | json }},
    "priceCurrency": {{ cart.currency.iso_code | json }},
    "availability": {% if product.available %}"https://schema.org/InStock"{% else %}"https://schema.org/OutOfStock"{% endif %},
    "priceSpecification": [
      {
        "@type": "UnitPriceSpecification",
        "price": {{ unit_price_decimal | json }},
        "priceCurrency": {{ cart.currency.iso_code | json }},
        "referenceQuantity": {
          "@type": "QuantitativeValue",
          "value": {{ m.reference_value | json }},
          "unitCode": {{ unit_code | json }},
          "unitText": {{ unit_display | json }}
        },
        "unitCode": {{ unit_code | json }},
        "unitText": {{ "per " | append: m.reference_value | append: unit_display | json }}
      }
    ]
  }
}
</script>
{% endif %}
		

Save as snippets/unit-price-schema.liquid. Render from your product template alongside your existing product JSON-LD. The snippet fires only when the variant has unit pricing enabled in Shopify admin — it self-suppresses for products where unit pricing is not applicable.

5 Common UnitPriceSpecification Mistakes

Related Resources

• Shopify Wholesale & B2B Pricing Schema — MOQ, Volume Tiers & MAP
• E-commerce Installment Payment Schema
• Shopify Food & Beverage Nutrition Schema
• Shopify ProductGroup & Variant Schema
• Shopify Metafield Types Reference
• CatalogScan Blog — AI Shopping Agent Optimization