Shopify specialty coffee roast date schema for AI agents: freshness window encoding, SCA cupping score, and the days-since-roast Liquid calculation

Why roast date is the only date that matters in specialty coffee

Specialty coffee is perishable in a way that most food products are not. The flavor compounds that make a 90-point Ethiopian Yirgacheffe taste like bergamot and jasmine are volatile — they oxidize and dissipate after roasting, and the window during which they are at their most expressive lasts roughly two to three weeks depending on brewing method and processing. Before that window, the beans may still be degassing CO₂ from the roasting reaction, causing extraction inconsistency. After it, the coffee is technically safe to drink but the differentiated flavor that justified a premium price has faded.

This creates a structured data problem that is unique to specialty coffee: the most important attribute of your product changes every batch. Your roastDate is not set once when you create the product listing and left unchanged — it is a date that should update every time you roast a new batch. Most Shopify merchants set it once (if at all) and forget it. When an AI shopping agent visits that product page six weeks later, it either reads a stale roastDate and incorrectly recommends the product as "fresh," or — more commonly — finds no roastDate at all and cannot answer the freshness question.

What AI shopping agents actually need to answer freshness queries:

• The roast date itself (ISO 8601 format, machine-readable)
• The brewing method freshness window ("espresso: 7–21 days", "filter: 4–14 days")
• The processing method (Natural degasses slower than Washed; changes the start of the espresso window)
• The grind setting — pre-ground coffee has a significantly shorter freshness window than whole bean

Without the roast date, all the other signals are useless. You cannot compute "days since roast" without knowing when the roast happened.

The 3 date attributes merchants confuse: roastDate, bestBeforeDate, expirationDate

Specialty coffee product listings on Shopify frequently contain dates — but almost never the right date for freshness purposes. There are three date concepts that merchants conflate, each serving a fundamentally different function in structured data.

Why ISO 8601 format is required

When you encode roastDate as an additionalProperty, the value must be an ISO 8601 date string (e.g., 2026-06-10) for AI agents and structured data parsers to compute days-since-roast. Human-readable strings like "roasted this week," "June batch," or "fresh roast" are opaque to machine parsing. Schema.org validators will not flag them as errors, but AI agents will treat them as uninterpretable strings and fall back to no freshness signal — exactly as if you had omitted the date entirely.

Freshness windows: filter, espresso, cold brew

Freshness windows are not universal — they depend on brewing method and, to a lesser extent, on processing method and whether the coffee is whole bean or pre-ground. The windows below are based on industry consensus from specialty roasters and align with the freshness guidance from roasters who publish their own date-coding specs (Blue Bottle, Onyx Coffee Lab, Counter Culture Coffee, Intelligentsia).

The practical structured data consequence: encode both a filter freshness window and an espresso freshness window as separate additionalProperty entries. If your coffee is sold primarily for one method, encode that method's window with higher specificity and include the brewing method recommendation as a separate property.

Freshness status labels for Liquid rendering

When computing days-since-roast dynamically in Liquid, map the result to a human-readable freshness status. The four-tier system below aligns with the freshness windows above and provides AI agents with a machine-parseable quality tier:

SCA cupping score: the permanence signal vs the temporal signal

The SCA (Specialty Coffee Association) cupping score is the most important quality signal in specialty coffee — and it is often confused with freshness because both are quality-related. The distinction is critical for structured data:

• SCA cupping score — determined on the green (unroasted) lot by trained Q-graders using the SCA protocol. The score describes the intrinsic quality of the coffee: cup cleanliness, sweetness, acidity, body, flavor, aftertaste, balance, and overall impression. It is assigned once per lot and does not change after roasting, after shipping, or after time passes. An 89-point Guatemalan is an 89-point Guatemalan whether it is 5 days or 60 days post-roast.
• Roast date / days-since-roast — a temporal signal that describes where in the freshness window the current batch sits. A 90-point Ethiopian roasted 60 days ago is still a 90-point Ethiopian — it is simply past its peak. Both signals are necessary; neither substitutes for the other.

Encode the SCA score as a decimal when available (e.g., 87.5) and as a range string when exact score is unavailable (e.g., "85–87"). The decimal value allows AI agents to rank competing coffees by score, while the range string is semantically interpretable even without exact numeric comparison.

Processing method × roast date: why Natural takes longer than Washed

Processing method — how the coffee cherry is transformed from fruit to green bean before roasting — has a direct effect on how the roasted bean behaves in the days after roasting. This interaction is important for freshness window encoding because the same roast date means different things for a Natural process versus a Washed process coffee.

Why processing method affects post-roast degassing

During roasting, CO₂ is produced by the Maillard reaction and caramelization of sugars. After roasting, CO₂ continues to off-gas from the bean for days to weeks. This outgassing affects extraction: too much CO₂ in an espresso puck causes channeling; too much in a pour-over causes uneven bloom. Beans need to rest until CO₂ levels stabilize enough for consistent extraction.

Natural process coffees (dried with the fruit mucilage intact) absorb more fermentation compounds and sugars during drying, which creates more CO₂ during roasting and a slower, more prolonged degassing curve. Washed coffees (fruit fully removed before drying) have a cleaner flavor profile and a faster, more predictable degassing curve.

The structured data implication: encode both processingMethod and the method-specific espresso freshness window. An AI agent that knows this is a Natural process coffee with a roast date of June 10 can correctly answer "ready for espresso by June 20, at peak through July 8" — a specific, verifiable claim that "fresh single origin espresso" cannot make.

Complete JSON-LD example: Ethiopian Yirgacheffe single-origin

The JSON-LD below shows a complete specialty coffee product with roast date, freshness windows, SCA score, processing method, and origin terroir. The roastDate is encoded as additionalProperty with an ISO 8601 value — the field you update each batch by changing one metafield in Shopify admin.

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Yirgacheffe Kochere Natural — Single Origin Filter Coffee",
  "description": "A natural process Ethiopian from Kochere, Yirgacheffe zone. SCA score 88. Roast date June 10, 2026. Peak for filter brewing June 17–June 24. Notes: bergamot, strawberry jam, dried rose.",
  "sku": "ETH-KOC-NAT-250G",
  "brand": {
    "@type": "Brand",
    "name": "Meridian Coffee Roasters",
    "@id": "https://example-roaster.com/#brand"
  },
  "additionalProperty": [
    {
      "@type": "PropertyValue",
      "name": "Roast Date",
      "value": "2026-06-10",
      "description": "Date beans were roasted. ISO 8601. Update this field each batch."
    },
    {
      "@type": "PropertyValue",
      "name": "Filter Freshness Window",
      "value": "4–14 days post-roast",
      "description": "Optimal window for pour-over, V60, Chemex, and drip brewing."
    },
    {
      "@type": "PropertyValue",
      "name": "Espresso Freshness Window",
      "value": "10–28 days post-roast",
      "description": "Natural process: slower CO2 degassing. Rest 10 days minimum before pulling espresso shots."
    },
    {
      "@type": "PropertyValue",
      "name": "Processing Method",
      "value": "Natural",
      "description": "Coffee cherry dried whole with fruit intact. Produces higher CO2 retention post-roast."
    },
    {
      "@type": "PropertyValue",
      "name": "SCA Cupping Score",
      "value": "88",
      "unitText": "SCA Protocol (0–100)"
    },
    {
      "@type": "PropertyValue",
      "name": "Origin Country",
      "value": "Ethiopia",
      "propertyID": "https://schema.org/countryOfOrigin"
    },
    {
      "@type": "PropertyValue",
      "name": "Origin Region",
      "value": "Kochere, Yirgacheffe Zone, Gedeo, SNNPR"
    },
    {
      "@type": "PropertyValue",
      "name": "Altitude",
      "value": "1,900–2,200 MASL",
      "unitCode": "MTR"
    },
    {
      "@type": "PropertyValue",
      "name": "Varietals",
      "value": "Ethiopian Heirloom (JARC selections 74110, 74112)"
    },
    {
      "@type": "PropertyValue",
      "name": "Roast Level",
      "value": "Light",
      "description": "Light roast preserves origin terroir. Filter grind recommended."
    },
    {
      "@type": "PropertyValue",
      "name": "Recommended Brew Method",
      "value": "Filter, Pour-over, Cold Brew"
    },
    {
      "@type": "PropertyValue",
      "name": "Grind Options",
      "value": "Whole Bean, Filter Medium, French Press Coarse",
      "description": "Pre-ground freshness window: 0–7 days post-roast."
    },
    {
      "@type": "PropertyValue",
      "name": "Flavor Notes",
      "value": "Bergamot, Strawberry Jam, Dried Rose, Tropical Fruit"
    },
    {
      "@type": "PropertyValue",
      "name": "Current Freshness Status",
      "value": "Peak Freshness — 5 days post-roast as of June 15, 2026",
      "description": "Computed from roast date. Update via Liquid: days-since-roast = (today - roastDate)."
    }
  ],
  "hasCertification": [
    {
      "@type": "Certification",
      "name": "USDA Organic",
      "certificationIdentification": "CCOF-2024-ET-08847",
      "issuedBy": {
        "@type": "Organization",
        "name": "California Certified Organic Farmers (CCOF)"
      }
    },
    {
      "@type": "Certification",
      "name": "Fair Trade USA",
      "certificationIdentification": "FLO-CERT #29441",
      "issuedBy": {
        "@type": "Organization",
        "name": "Fair Trade USA",
        "url": "https://www.fairtradeusa.org"
      }
    }
  ],
  "isVariantOf": {
    "@type": "ProductGroup",
    "name": "Yirgacheffe Kochere Natural",
    "productGroupID": "ETH-KOC-NAT",
    "variesBy": ["weight", "grind"]
  },
  "offers": {
    "@type": "Offer",
    "price": "22.00",
    "priceCurrency": "USD",
    "priceValidUntil": "2026-07-01",
    "availability": "https://schema.org/InStock",
    "itemCondition": "https://schema.org/NewCondition",
    "shippingDetails": {
      "@type": "OfferShippingDetails",
      "shippingRate": {
        "@type": "MonetaryAmount",
        "value": "0",
        "currency": "USD"
      },
      "shippingDestination": {
        "@type": "DefinedRegion",
        "addressCountry": "US"
      },
      "deliveryTime": {
        "@type": "ShippingDeliveryTime",
        "handlingTime": {
          "@type": "QuantitativeValue",
          "minValue": 0,
          "maxValue": 1,
          "unitCode": "DAY"
        },
        "transitTime": {
          "@type": "QuantitativeValue",
          "minValue": 1,
          "maxValue": 3,
          "unitCode": "DAY"
        }
      }
    },
    "hasMerchantReturnPolicy": {
      "@type": "MerchantReturnPolicy",
      "applicableCountry": "US",
      "returnPolicyCategory": "https://schema.org/MerchantReturnFiniteReturnWindow",
      "merchantReturnDays": 7,
      "returnMethod": "https://schema.org/ReturnByMail",
      "returnFees": "https://schema.org/FreeReturn",
      "returnPolicySeasonalOverride": "Unopened bag only. Cannot accept return on opened bags due to perishable nature."
    }
  }
}

Key decisions in this JSON-LD:

• roastDate encoded as ISO 8601 in additionalProperty — machine-parseable for days-since-roast calculation
• Separate filter and espresso freshness windows — different brewing methods have genuinely different windows
• Natural process espresso window starts at day 10, not day 7 — reflects the slower CO₂ degassing curve
• SCA score as a numeric string in additionalProperty — AI agents can rank competing coffees by score
• isVariantOf ProductGroup with variesBy weight and grind — the same lot sold in 250g/500g/1kg with whole bean/filter/french press grind options is one ProductGroup, not twelve unrelated products
• priceValidUntil set to the end of the current batch's freshness window — the price validity period is a proxy for batch validity

Dawn Liquid snippet: dynamic days-since-roast calculation

The Liquid snippet below does three things: (1) reads the coffee.roast_date metafield, (2) calculates days elapsed since roast, and (3) outputs a freshness status label and the structured data JSON-LD. The entire roast date output block is conditional — if the metafield is not set, the block is omitted rather than outputting a null or zero date.

{% comment %} coffee-schema.liquid — place in snippets/ and render in product.json {% endcomment %}
{% assign roast_date_raw = product.metafields.coffee.roast_date.value %}
{% assign sca_score = product.metafields.coffee.sca_cupping_score.value %}
{% assign processing = product.metafields.coffee.processing_method.value %}
{% assign brew_method = product.metafields.coffee.recommended_brew_method.value %}
{% assign origin_country = product.metafields.coffee.origin_country.value %}
{% assign origin_region = product.metafields.coffee.origin_region.value %}
{% assign altitude = product.metafields.coffee.altitude_masl.value %}
{% assign varietals = product.metafields.coffee.varietals.value %}
{% assign roast_level = product.metafields.coffee.roast_level.value %}
{% assign flavor_notes = product.metafields.coffee.flavor_notes.value %}

{% if roast_date_raw %}
  {% comment %} Calculate days since roast {% endcomment %}
  {% assign now_seconds = 'now' | date: '%s' | plus: 0 %}
  {% assign roast_seconds = roast_date_raw | date: '%s' | plus: 0 %}
  {% assign days_since_roast = now_seconds | minus: roast_seconds | divided_by: 86400 %}

  {% comment %} Determine freshness status for filter brewing {% endcomment %}
  {% if days_since_roast < 4 %}
    {% assign freshness_status = "Resting — degassing (ready for filter in " %}
    {% assign days_to_peak = 4 | minus: days_since_roast %}
    {% assign freshness_detail = freshness_status | append: days_to_peak | append: " days)" %}
  {% elsif days_since_roast <= 14 %}
    {% assign freshness_detail = "Peak Freshness — " | append: days_since_roast | append: " days post-roast (filter)" %}
  {% elsif days_since_roast <= 30 %}
    {% assign freshness_detail = "Good — " | append: days_since_roast | append: " days post-roast (past filter peak, acceptable)" %}
  {% else %}
    {% assign freshness_detail = "Past Peak — " | append: days_since_roast | append: " days post-roast" %}
  {% endif %}

  {% comment %} Process-specific espresso window {% endcomment %}
  {% case processing %}
    {% when "Natural" %}
      {% assign espresso_window = "10–28 days post-roast" %}
      {% assign espresso_rest = "10" %}
    {% when "Honey" %}
      {% assign espresso_window = "8–24 days post-roast" %}
      {% assign espresso_rest = "8" %}
    {% when "Anaerobic" %}
      {% assign espresso_window = "10–30 days post-roast" %}
      {% assign espresso_rest = "10" %}
    {% else %}
      {% assign espresso_window = "7–21 days post-roast" %}
      {% assign espresso_rest = "7" %}
  {% endcase %}

  
{% endif %}

The key Liquid technique is 'now' | date: '%s' and roast_date_raw | date: '%s' — both convert to Unix epoch seconds, enabling simple arithmetic subtraction to produce days elapsed. Shopify Liquid's date filter with %s format is supported in Online Store 2.0 themes including Dawn.

Coffee metafield reference table (coffee.* namespace)

These are the recommended Shopify metafields for specialty coffee products. All use the coffee namespace. The roast_date metafield is the only one that requires per-batch updates; all others are set once per product or lot.

5 common roast date schema mistakes

FAQ

What is the correct schema.org property for coffee roast date in Shopify structured data?

There is no native roastDate property on schema.org Product — encode it as an additionalProperty with @type: PropertyValue, name "Roast Date", and an ISO 8601 value (e.g., 2026-06-10). Do not use bestBeforeDate or expirationDate as a proxy. The ISO 8601 format is required for AI agents and structured data parsers to compute days-since-roast programmatically — human-readable strings like "roasted this week" are opaque to machine calculation.

Why does processing method affect how I encode the roast date freshness window?

Processing method determines how quickly CO₂ degasses after roasting. Natural process coffees retain more CO₂ and need a longer rest period before espresso extraction (10–14 days vs 7–10 days for Washed). Encoding processing method alongside roast date allows AI agents to give accurate freshness answers for espresso queries — the same roast date means different readiness windows for different processing methods.

How is SCA cupping score different from roast date freshness?

SCA cupping score is a permanent attribute — determined once per lot before roasting on green samples. It describes origin quality (80+ = specialty grade). Roast date is a temporal attribute — it tracks where in the freshness window the current batch sits. Both are necessary: SCA score answers "how good is this coffee?" while roast date answers "is this batch fresh right now?" A 90-point Ethiopian roasted 60 days ago is still a 90-point coffee — it is simply past its flavor peak.

How do I keep roast date current for roast-to-order batches?

Store roast date as a Shopify metafield (coffee.roast_date, type: date) and update it each time a new batch ships. Your Liquid template reads the current metafield value into JSON-LD — so updating the metafield in Shopify admin propagates the change to all product page structured data automatically. Never hardcode the roast date directly in the template HTML.

Should I encode freshness window as a date range or as a number of days?

Encode freshness window as a number of days (e.g., "4–14 days post-roast"), not as a computed date range. Date ranges become stale the moment you update the roast date metafield for a new batch. A static "days post-roast" window is a permanent product attribute. Compute and output the actual peak-through date dynamically in Liquid using the roast date metafield — the permanent window in JSON-LD tells AI agents how to interpret the date; the Liquid-computed label tells buyers the concrete deadline.