# Return policy and shipping structured data for AI agents

> AI shopping agents answer "can I return this?" and "when will it arrive?" before recommending a purchase. An agent-ready store publishes both in structured data, a MerchantReturnPolicy and shipping details (OfferShippingDetails or an organization-level ShippingService), on its products or its Organization.

- Source: https://is-agentic-storefront.com/checks/return-shipping-data
- Updated: 2026-10-15
- Category: Product data (25% of score)
- Impact: Medium
- Spec: [Google return policy markup](https://developers.google.com/search/docs/appearance/structured-data/return-policy)
- Scanner check: Return policy and shipping details are in structured data

## 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**](https://developers.google.com/search/docs/appearance/structured-data/return-policy): return window, return method, fees, and the countries the policy covers.
- **Shipping details**: [`OfferShippingDetails`](https://schema.org/OfferShippingDetails) on a product's offer, or a [`ShippingService`](https://developers.google.com/search/docs/appearance/structured-data/shipping-policy) nested under your `Organization` for a store-wide shipping policy.

In our [calibration of 31 live stores](https://is-agentic-storefront.com/guides/scoring-methodology), 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](https://developers.google.com/search/docs/appearance/structured-data/return-policy) requires either `applicableCountry` + `returnPolicyCategory` (plus `merchantReturnDays` for a finite window) or a `merchantReturnLink`:

```html
<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](https://developers.google.com/search/docs/appearance/structured-data/shipping-policy)):

```json
"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](https://is-agentic-storefront.com/checks/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](https://github.com/medusajs/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?](https://is-agentic-storefront.com/guides/medusa-agent-readiness) 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](https://developers.google.com/search/docs/appearance/structured-data/return-policy)
- [Google: merchant shipping policy structured data](https://developers.google.com/search/docs/appearance/structured-data/shipping-policy)
- [Google: merchant listing structured data](https://developers.google.com/search/docs/appearance/structured-data/merchant-listing)
- [schema.org MerchantReturnPolicy](https://schema.org/MerchantReturnPolicy)
- [schema.org OfferShippingDetails](https://schema.org/OfferShippingDetails)

## Frequently asked questions

### Where should MerchantReturnPolicy go, on the product or the Organization?

Google recommends an organization-level policy via hasMerchantReturnPolicy for your standard terms, and product-level markup only for exceptions. Product-level markup overrides the organization-level policy.

### Is a link to my returns page enough?

For Google, a MerchantReturnPolicy with merchantReturnLink is a valid minimum. Agents get more from explicit fields such as applicableCountry, returnPolicyCategory and merchantReturnDays, which they can quote without opening another page.

### How common is return and shipping structured data?

Rare. In our calibration scan of 31 live stores, only 3 passed this check, making it the most commonly failed check.

## Run your store on a platform built for agentic commerce

Medusa is open-source, headless commerce with a full Store API agents can call and storefronts you control end to end.

### Deploy on Medusa Cloud

Open-source commerce with a full Store API, hosted and scaled for you. Your storefront, your data model.

- [Deploy on Medusa Cloud](https://cloud.medusajs.com?utm_source=agent-friendly-scorer&utm_medium=referral&utm_campaign=markdown-cta&utm_content=%2Fchecks%2Freturn-shipping-data)
- [Medusa Cloud docs](https://docs.medusajs.com/cloud?utm_source=agent-friendly-scorer&utm_medium=referral&utm_campaign=markdown-cta&utm_content=%2Fchecks%2Freturn-shipping-data)

### Storefront skills for coding agents

Teach Claude Code, Cursor or Codex to build storefronts with the patterns these checks look for.

```bash
npx skills add medusajs/medusa-agent-skills
```

[View the skill on GitHub](https://github.com/medusajs/medusa-agent-skills/tree/main/plugins/ecommerce-storefront/skills/storefront-best-practices)

---

Scan your store for free at https://is-agentic-storefront.com/