Home › Blog › Shopify shipping structured data for AI shopping agents

Shopify shipping structured data for AI shopping agents: OfferShippingDetails, ShippingDeliveryTime, and free-shipping threshold schema

2026-06-11 — ~16 min read — OfferShippingDetailsShipping schemaShopify LiquidAI shopping

When a shopper asks ChatGPT Shopping "does this store offer free shipping on orders over $50?" or Perplexity "can I get this delivered by Thursday?", the AI agent's answer comes from structured data — not from reading your shipping policy page. The OfferShippingDetails and ShippingDeliveryTime schema types are the machine-readable layer AI agents use to answer those questions. Over 92% of Shopify stores have none of it.

Why AI shopping agents need shipping structured data

Shipping is the third-most-common purchase intent modifier in AI shopping queries, after price ("under $50") and availability ("in stock"). Queries like "free shipping running shoes", "get a yoga mat delivered this week", and "cheapest laptop with next-day delivery" are answered by AI agents from a combination of Product JSON-LD and — critically — OfferShippingDetails schema.

Without shipping structured data, AI shopping agents have three options:

1. Skip the product from shipping-filtered result sets entirely — the safest choice for an agent that cannot verify the claim.
2. Parse the shipping policy page — unstructured text that varies wildly between stores and is often behind JavaScript or in PDF format. This produces unreliable, hard-to-normalise results.
3. Make no claim — show the product in results but omit the "Free shipping" or "Arrives by Thursday" badge that influences click-through.

None of these outcomes serves you. Stores that do have OfferShippingDetails and ShippingDeliveryTime get the shipping badge in AI result cards and are included in shipping-filtered queries. That is a compounding advantage: shipping-filtered queries convert at 2× the rate of unfiltered browse queries because the shopper has already qualified the logistics constraint before clicking.

OfferShippingDetails: anatomy of the schema

OfferShippingDetails is a schema.org type that lives inside an Offer object as the shippingDetails property. It describes a single shipping option — one rate, one region, one delivery window. For stores with multiple shipping options (standard + express, or free + paid), you use multiple OfferShippingDetails objects inside the same Offer.

Here is the minimal valid OfferShippingDetails for a US-only free shipping offer — the skeleton everything builds on:

{
  "@type": "OfferShippingDetails",
  "shippingRate": {
    "@type": "MonetaryAmount",
    "value": 0,
    "currency": "USD"
  },
  "shippingDestination": {
    "@type": "DefinedRegion",
    "addressCountry": "US"
  }
}

ShippingDeliveryTime: separating handling from transit

The deliveryTime property is where most implementations fall short. Merchants often write a single "3–5 business days" estimate in their shipping policy — but AI shopping agents (and Google's merchant experience) distinguish between two phases of that window:

• Handling time (handlingTime): how long between order placement and the package leaving your warehouse. For same-day fulfilment cut-off stores, this is 0–1 business days. For stores that batch-process orders, it may be 1–3 days.
• Transit time (transitTime): how long the carrier takes to deliver once the package is collected. For standard USPS Ground Advantage in the US, this is typically 2–8 business days depending on origin/destination distance.

Separating these matters because the AI agent's "can I get this by Friday?" calculation requires knowing both numbers separately. An agent that sees a combined 3–5 days window cannot tell whether the store ships today (handling: 0) with a 3–5 day carrier, or whether they take 3 days to ship (handling: 3) and use overnight carrier delivery (transit: 1). The first scenario can answer "yes" to a Friday delivery query on a Monday; the second cannot.

The full ShippingDeliveryTime structure with both components:

{
  "@type": "ShippingDeliveryTime",
  "handlingTime": {
    "@type": "QuantitativeValue",
    "minValue": 0,
    "maxValue": 1,
    "unitCode": "DAY"
  },
  "transitTime": {
    "@type": "QuantitativeValue",
    "minValue": 3,
    "maxValue": 7,
    "unitCode": "DAY"
  },
  "cutoffTime": "16:00:00-05:00"
}

The optional cutoffTime property (ISO 8601 time with timezone offset) tells AI agents and Google's merchant experience the order deadline for same-day processing. A cutoffTime of 16:00:00-05:00 means orders placed before 4 PM US Eastern time begin processing the same business day. This is used to answer "get it by tomorrow" queries correctly — an order placed at 2 PM ET on Monday, with a 0–1 day handling time, can legitimately promise Tuesday + transit.

Free-shipping threshold: eligibleTransactionVolume

Most Shopify stores offer free shipping above a cart threshold — typically $35, $50, or $75 in the US market. This is one of the highest-leverage shipping schema implementations because "free shipping over $X" is a heavily searched purchase qualifier in AI shopping interfaces.

The eligibleTransactionVolume property on OfferShippingDetails lets you declare a minimum order value that activates a specific shipping rate. Combined with a zero-cost shippingRate, this expresses your free shipping threshold to AI agents in fully machine-readable form.

The correct approach is two OfferShippingDetails blocks in the same Offer: one for the paid rate (no minimum), and one for the free rate (with the threshold):

"shippingDetails": [
  {
    "@type": "OfferShippingDetails",
    "shippingRate": {
      "@type": "MonetaryAmount",
      "value": 5.99,
      "currency": "USD"
    },
    "shippingDestination": {
      "@type": "DefinedRegion",
      "addressCountry": "US"
    },
    "deliveryTime": {
      "@type": "ShippingDeliveryTime",
      "handlingTime": {
        "@type": "QuantitativeValue",
        "minValue": 0,
        "maxValue": 1,
        "unitCode": "DAY"
      },
      "transitTime": {
        "@type": "QuantitativeValue",
        "minValue": 3,
        "maxValue": 7,
        "unitCode": "DAY"
      }
    }
  },
  {
    "@type": "OfferShippingDetails",
    "shippingRate": {
      "@type": "MonetaryAmount",
      "value": 0,
      "currency": "USD"
    },
    "shippingDestination": {
      "@type": "DefinedRegion",
      "addressCountry": "US"
    },
    "eligibleTransactionVolume": {
      "@type": "PriceSpecification",
      "minPrice": 50,
      "priceCurrency": "USD"
    },
    "deliveryTime": {
      "@type": "ShippingDeliveryTime",
      "handlingTime": {
        "@type": "QuantitativeValue",
        "minValue": 0,
        "maxValue": 1,
        "unitCode": "DAY"
      },
      "transitTime": {
        "@type": "QuantitativeValue",
        "minValue": 3,
        "maxValue": 7,
        "unitCode": "DAY"
      }
    }
  }
]

With this in place, an AI shopping agent can answer: "This store charges $5.99 shipping on orders under $50, and offers free standard shipping (3–7 business days) on orders of $50 or more." That answer is surfaced as a badge in AI result cards for queries like "free shipping yoga mat" without any user clicking through to your site.

Regional shipping: DefinedRegion for multi-market stores

For stores using Shopify Markets or shipping to multiple countries, DefinedRegion gives you precise control over which shipping options apply to which geographies. AI shopping agents use shippingDestination to filter out products that do not ship to a user's detected or stated location.

The DefinedRegion type supports three granularity levels:

For a Shopify Markets store shipping to the US, UK, and EU with different rates and delivery windows, the correct structure is one OfferShippingDetails per market, each with its own shippingRate, shippingDestination, and deliveryTime. The shippingDetails array accepts any number of objects, so there is no structural limit to how many regions you can declare.

A common pattern for a two-market store (US standard + International):

"shippingDetails": [
  {
    "@type": "OfferShippingDetails",
    "shippingRate": { "@type": "MonetaryAmount", "value": 0, "currency": "USD" },
    "shippingDestination": { "@type": "DefinedRegion", "addressCountry": "US" },
    "eligibleTransactionVolume": { "@type": "PriceSpecification", "minPrice": 50, "priceCurrency": "USD" },
    "deliveryTime": {
      "@type": "ShippingDeliveryTime",
      "handlingTime": { "@type": "QuantitativeValue", "minValue": 0, "maxValue": 1, "unitCode": "DAY" },
      "transitTime": { "@type": "QuantitativeValue", "minValue": 3, "maxValue": 7, "unitCode": "DAY" }
    }
  },
  {
    "@type": "OfferShippingDetails",
    "shippingRate": { "@type": "MonetaryAmount", "value": 14.99, "currency": "USD" },
    "shippingDestination": { "@type": "DefinedRegion", "addressCountry": "GB" },
    "deliveryTime": {
      "@type": "ShippingDeliveryTime",
      "handlingTime": { "@type": "QuantitativeValue", "minValue": 1, "maxValue": 2, "unitCode": "DAY" },
      "transitTime": { "@type": "QuantitativeValue", "minValue": 7, "maxValue": 14, "unitCode": "DAY" }
    }
  }
]

Liquid implementation for Dawn themes

Shopify themes generate Product JSON-LD in one of two places: snippets/structured-data.liquid (Dawn and descendants) or inline in sections/main-product.liquid. Find the block containing "@type": "Product" — this is where you will add the shippingDetails array.

Look for the offers block, which typically looks like:

{
  "@type": "Offer",
  "url": "{{ product.url | prepend: shop.url }}",
  "priceCurrency": "{{ shop.currency }}",
  "price": "{{ product.selected_or_first_available_variant.price | divided_by: 100.0 | round: 2 }}",
  "availability": "https://schema.org/{% if product.available %}InStock{% else %}OutOfStock{% endif %}"
}

Add shippingDetails inside the Offer object, after the availability line. Here is the complete addition using Shopify Liquid for a typical US store with a $50 free shipping threshold. Replace the threshold and transit times with your actual values:

{
  "@type": "Offer",
  "url": "{{ product.url | prepend: shop.url }}",
  "priceCurrency": "{{ shop.currency }}",
  "price": "{{ product.selected_or_first_available_variant.price | divided_by: 100.0 | round: 2 }}",
  "availability": "https://schema.org/{% if product.available %}InStock{% else %}OutOfStock{% endif %}",
  "shippingDetails": [
    {
      "@type": "OfferShippingDetails",
      "shippingRate": {
        "@type": "MonetaryAmount",
        "value": 5.99,
        "currency": "USD"
      },
      "shippingDestination": {
        "@type": "DefinedRegion",
        "addressCountry": "US"
      },
      "deliveryTime": {
        "@type": "ShippingDeliveryTime",
        "handlingTime": {
          "@type": "QuantitativeValue",
          "minValue": 0,
          "maxValue": 1,
          "unitCode": "DAY"
        },
        "transitTime": {
          "@type": "QuantitativeValue",
          "minValue": 3,
          "maxValue": 7,
          "unitCode": "DAY"
        },
        "cutoffTime": "16:00:00-05:00"
      }
    },
    {
      "@type": "OfferShippingDetails",
      "shippingRate": {
        "@type": "MonetaryAmount",
        "value": 0,
        "currency": "USD"
      },
      "shippingDestination": {
        "@type": "DefinedRegion",
        "addressCountry": "US"
      },
      "eligibleTransactionVolume": {
        "@type": "PriceSpecification",
        "minPrice": 50,
        "priceCurrency": "USD"
      },
      "deliveryTime": {
        "@type": "ShippingDeliveryTime",
        "handlingTime": {
          "@type": "QuantitativeValue",
          "minValue": 0,
          "maxValue": 1,
          "unitCode": "DAY"
        },
        "transitTime": {
          "@type": "QuantitativeValue",
          "minValue": 3,
          "maxValue": 7,
          "unitCode": "DAY"
        }
      }
    }
    {% unless product.requires_shipping %}
    ,{
      "@type": "OfferShippingDetails",
      "doesNotShip": true,
      "shippingDestination": {
        "@type": "DefinedRegion",
        "addressCountry": "US"
      }
    }
    {% endunless %}
  ]
}

Notes on the Liquid snippet

• product.requires_shipping — Shopify's Liquid variable that returns false for digital products (downloads, gift cards, subscription-only products). The {% unless product.requires_shipping %} block adds a doesNotShip: true signal for digital items, which correctly excludes them from "need delivery" filtered queries.
• Hardcoded vs. dynamic threshold — the minPrice: 50 is intentionally hardcoded here. Shopify does not expose free shipping thresholds as a Liquid variable. If you change your shipping threshold in the Shopify admin, you must also update this value in the snippet. Some merchants store the threshold in a theme setting (settings.free_shipping_threshold) via config/settings_schema.json — that approach allows in-admin updates without touching Liquid code and is recommended for stores that change promotions frequently.
• cutoffTime timezone — use the UTC offset for your warehouse location, not a named timezone. -05:00 is US Eastern Standard Time; -08:00 is US Pacific Standard Time. If your store observes Daylight Saving Time, you will need to update this offset twice a year, or use a static offset that represents your worst-case handling window.
• Multiple Offers vs. one Offer — if your Product JSON-LD currently has one Offer object, this snippet works as-is. If you generate one Offer per variant (more accurate for variant-level pricing but more verbose), add the shippingDetails array to every variant Offer or reference a shared OfferShippingDetails node via @id.

Five mistakes that break shipping schema

Testing and validation

After adding OfferShippingDetails to your theme, use these tools to verify the implementation:

1. Google Rich Results Test

Visit Google's Rich Results Test (search.google.com/test/rich-results) and enter a product URL. Expand the Product result and look for the offers block — within it, shippingDetails should be listed with its child properties. If you see an error like "Missing field 'shippingDestination'" or "Missing field 'transitTime'", the validator will tell you exactly which required property is absent.

2. schema.org validator

The schema.org validator (validator.schema.org) gives you a lower-level check that is not Google-specific. It validates OfferShippingDetails against the schema.org specification and catches type mismatches (like passing a string where MonetaryAmount is expected) that the Rich Results Test sometimes silently accepts.

3. Google Merchant Center product diagnostics

If your store is linked to Google Merchant Center, the product diagnostics tab shows whether your structured data shipping claims conflict with your Merchant Center shipping settings. Mismatches cause the shipping badge to be suppressed in Google AI Mode even if your JSON-LD is technically valid.

4. CatalogScan

CatalogScan's AI readiness scan checks whether your product pages include shippingDetails as part of its 18-signal audit. The scan flags missing OfferShippingDetails, identifies whether deliveryTime includes both handlingTime and transitTime, and cross-checks the shipping rate against your og:price:amount context. For detailed guidance on the complete structured data testing workflow, see our guide on Shopify structured data audit tools.

After deploying the snippet, allow 3–21 days for AI crawlers to re-index your product pages with the new shipping signals. You can accelerate this by pinging IndexNow for affected product URLs — see our guide on IndexNow for Shopify for the exact workflow. Google's Merchant Center will update faster (usually within 48–72 hours) if you trigger a re-crawl via the product diagnostics interface.

FAQ