Return policy and shipping structured data for AI agents

Why AI agents need return and shipping data

Return terms and delivery time are two of the questions shoppers ask before buying, and they’re the questions an AI shopping agent has to answer when comparing two similar products. Most stores publish them only as prose on a policy page. The agent then has to find that page, read it, and interpret phrases like “most items within 30 days, exclusions apply”.

Structured data removes the guesswork. Google documents two pieces:

• MerchantReturnPolicy: return window, return method, fees, and the countries the policy covers.
• Shipping details: OfferShippingDetails on a product’s offer, or a ShippingService nested under your Organization for a store-wide shipping policy.

In our calibration of 31 live stores, only 3 passed this check, so adding it is one of the quickest ways to stand out to agents.

What the scanner checks

The scanner reads the JSON-LD on up to three sampled product pages plus the homepage, and looks for:

• Return policy: any node with a hasMerchantReturnPolicy property, or any MerchantReturnPolicy node.
• Shipping: any node with shippingDetails or hasShippingService, or any OfferShippingDetails or ShippingService node.

Both product-level (on the Offer) and organization-level (on the homepage Organization) placement count.

Result	Condition
Pass	Both a return policy and shipping details are present.
Partial	Only one of the two is present.
Fail	Neither is present.
Inconclusive	No product page could be fetched.

The scanner checks presence, not the values. Use Google’s Rich Results Test to validate the fields themselves.

How to add return and shipping structured data

1. Put your standard return policy on the Organization in the homepage JSON-LD. Google’s return policy guide requires either applicableCountry + returnPolicyCategory (plus merchantReturnDays for a finite window) or a merchantReturnLink:

<script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "Organization",
    "name": "Your Store",
    "url": "https://your-store.com",
    "hasMerchantReturnPolicy": {
      "@type": "MerchantReturnPolicy",
      "applicableCountry": "US",
      "returnPolicyCategory": "https://schema.org/MerchantReturnFiniteReturnWindow",
      "merchantReturnDays": 30,
      "returnMethod": "https://schema.org/ReturnByMail",
      "returnFees": "https://schema.org/FreeReturn",
      "merchantReturnLink": "https://your-store.com/policies/returns"
    }
  }
</script>

2. Add shipping details to each Offer (or use an organization-level ShippingService per Google’s shipping policy guide):

"offers": {
  "@type": "Offer",
  "price": "89.00",
  "priceCurrency": "USD",
  "availability": "https://schema.org/InStock",
  "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": 2, "maxValue": 5, "unitCode": "DAY" }
    }
  }
}

3. Override per product only when needed. Product-level markup takes precedence over the organization-level policy, so use it for final-sale items or oversized shipping.

4. Keep it in sync with your human-readable returns and shipping pages, which agents also look for (see policy links).

How to fix it on Medusa

• Not shipped by default. Medusa is headless, so this markup is the storefront’s job, and the DTC starter storefront doesn’t output it.
• Return policy: Google accepts it at Organization level, so add hasMerchantReturnPolicy once in the storefront’s root layout, with the same terms as your returns page.
• Shipping: add shippingDetails to the offers in the product page’s Product JSON-LD, using the rates and regions of the shipping options you configured in Medusa.
• See Is Medusa agent-ready? for the Product JSON-LD snippet to extend.

Common mistakes

• Return policy only on a /returns page in prose, with no markup at all.
• merchantReturnDays without applicableCountry and returnPolicyCategory.
• Shipping rate as a string with a symbol ("$0") instead of a MonetaryAmount.
• Markup that promises free returns while the policy page charges a restocking fee.

Sources

• Google: merchant return policy structured data
• Google: merchant shipping policy structured data
• Google: merchant listing structured data
• schema.org MerchantReturnPolicy
• schema.org OfferShippingDetails