Optimization Guide

Ecommerce MerchantReturnPolicy Schema: Shopify Returns Structured Data for AI Agents

Q: What is MerchantReturnPolicy in schema.org?

MerchantReturnPolicy is a dedicated schema.org type for specifying structured return policy information on a product or organization. It captures: the return window (merchantReturnDays), whether returns are free or have a fee (itemReturnShippingFeesAmount or returnShippingFeesAmount), the return method (ReturnByMail, ReturnInStore, ReturnAtKiosk), the policy applicable countries (applicableCountry), and the overall return policy category (MerchantReturnFiniteReturnWindow, MerchantReturnUnlimitedWindow, MerchantReturnNotPermitted). Unlike a plain-text return policy page, MerchantReturnPolicy makes return information machine-readable for AI shopping agents.

Q: How do I add MerchantReturnPolicy to Shopify product JSON-LD?

Add a 'hasMerchantReturnPolicy' property to your Product JSON-LD block. The value is a MerchantReturnPolicy object. Example: { '@type': 'MerchantReturnPolicy', 'applicableCountry': 'US', 'returnPolicyCategory': 'https://schema.org/MerchantReturnFiniteReturnWindow', 'merchantReturnDays': 30, 'returnMethod': 'https://schema.org/ReturnByMail', 'returnFees': 'https://schema.org/FreeReturn' }. For a store-wide policy, add hasMerchantReturnPolicy to the Organization block in your homepage JSON-LD instead of repeating it on every product.

Q: What is the difference between returnFees and itemReturnShippingFeesAmount?

returnFees is a schema.org enumeration: FreeReturn (no return shipping cost), ReturnShippingFees (customer pays return shipping), and OriginalShippingFees (customer pays the original shipping fee, not return shipping). itemReturnShippingFeesAmount is a MonetaryAmount object specifying a precise dollar amount charged for return shipping — use this when returns cost a specific flat fee (e.g., '$7.99 return label'). restockingFee is a separate MonetaryAmount or QuantitativeValue for restocking charges. Use the enumeration for simple cases; use MonetaryAmount when you have a specific fee to communicate.

Q: Do AI shopping agents use MerchantReturnPolicy structured data?

Yes. Return policy is a major conversion factor in AI-assisted shopping — queries like 'does X store have free returns?', 'what is the return window for Y product?', and comparison queries like 'which of these has the best return policy?' are common in AI shopping interfaces. ChatGPT Shopping, Google AI Mode, and Perplexity Shopping all surface return policy as a product attribute when MerchantReturnPolicy structured data is present. Without it, agents either skip the return info or extract it from prose — which is lower confidence and error-prone.

Q: Should MerchantReturnPolicy go on the product page or the Organization?

Both, depending on your policy structure. If your return policy is store-wide and identical for all products, add it once to the Organization JSON-LD on your homepage via 'hasMerchantReturnPolicy'. This is the most efficient approach and lets AI agents understand your policy at the brand level. If different product categories have different policies (e.g., 30 days for most items but final sale on personalized products), add per-product MerchantReturnPolicy via 'hasMerchantReturnPolicy' in the Product block — this overrides the Organization-level policy for that product. You can have both.

Return policy is a top-3 purchase decision factor for first-time buyers. AI shopping agents answer "does this store have free returns?" from structured data — not from reading your returns page. MerchantReturnPolicy is the schema.org type built exactly for this, and almost no Shopify stores use it.

TL;DR Add a hasMerchantReturnPolicy block to your Product JSON-LD (per-product policies) or to your Organization JSON-LD on the homepage (store-wide policy). Use returnPolicyCategory enum values, merchantReturnDays for the window, returnFees for cost, and returnMethod for the return channel. Five fields is enough to make your return policy machine-readable to all AI shopping agents.

Why MerchantReturnPolicy Structured Data Matters

Return policy anxiety is the #1 barrier to first purchase at unknown online stores. When AI shopping agents help a buyer compare products across stores, return policy is a decision-critical attribute — equal in weight to price and shipping time for many purchase categories.

Google AI Mode explicitly surfaces return policy in product comparison panels. ChatGPT Shopping answers "which of these has the best return policy?" from structured data. Perplexity Shopping includes "free returns" as a filterable attribute. If your policy lives only in prose on a /policies/refund-policy page, AI agents either skip it entirely or produce a low-confidence inference that may be wrong.

The fix — MerchantReturnPolicy — is a schema.org type added to Google's product structured data spec in 2022 and now widely recognized by AI product crawlers. It takes five fields to implement correctly. Almost no Shopify stores have done it.

MerchantReturnPolicy: Core Fields

Field	Type	Purpose
`returnPolicyCategory`	Enum URI	Overall policy type — finite window, unlimited, or no returns
`merchantReturnDays`	Integer	Number of days from purchase (or delivery) for returns
`returnFees`	Enum URI	Whether return shipping is free, at customer expense, or original fee
`returnMethod`	Enum URI	How the item is returned (mail, in-store, kiosk)
`applicableCountry`	ISO 3166-1 alpha-2	Country/countries this policy applies to
`itemReturnShippingFeesAmount`	MonetaryAmount	Specific dollar amount charged for return shipping label
`restockingFee`	MonetaryAmount or QuantitativeValue	Restocking charge applied on return
`merchantReturnLink`	URL	URL to the full return policy page
`returnPolicySeasonalOverride`	MerchantReturnPolicySeasonalOverride	Holiday or promotional extended return window (with startDate/endDate)
`inStoreReturnsOffered`	Boolean	Whether in-store returns are available (for omnichannel merchants)

returnPolicyCategory enum values

Enum	Use when
`schema.org/MerchantReturnFiniteReturnWindow`	Returns accepted within a fixed number of days (30, 60, 90, etc.)
`schema.org/MerchantReturnUnlimitedWindow`	Returns accepted at any time (rare — Costco-style policies)
`schema.org/MerchantReturnNotPermitted`	No returns — final sale, personalized, or perishable items

returnFees enum values

Enum	Meaning
`schema.org/FreeReturn`	Return shipping is free for the customer
`schema.org/ReturnShippingFees`	Customer pays return shipping — use with `itemReturnShippingFeesAmount` for the specific cost
`schema.org/OriginalShippingFees`	Customer pays the original order's shipping cost (not a separate return label fee)

Implementation: Store-Wide Policy on Organization

If your return policy is the same for all products, add it once to the Organization block in your homepage's JSON-LD. AI agents apply this store-level policy to all products from your domain unless overridden at the product level.

{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Acme Store",
  "url": "https://acme-store.com",
  "hasMerchantReturnPolicy": {
    "@type": "MerchantReturnPolicy",
    "applicableCountry": ["US", "CA"],
    "returnPolicyCategory": "https://schema.org/MerchantReturnFiniteReturnWindow",
    "merchantReturnDays": 30,
    "returnMethod": "https://schema.org/ReturnByMail",
    "returnFees": "https://schema.org/FreeReturn",
    "merchantReturnLink": "https://acme-store.com/policies/refund-policy",
    "inStoreReturnsOffered": false
  }
}

Implementation: Per-Product Policies in Shopify

For product categories with different return rules (e.g., electronics have 30-day returns, personalized items are final sale), add hasMerchantReturnPolicy inside the Product JSON-LD block. This overrides the Organization-level policy for that specific product.

{% comment %} product.liquid — extend existing Product JSON-LD block {% endcomment %}
{
  "@type": "Product",
  "name": {{ product.title | json }},
  "hasMerchantReturnPolicy": {
    "@type": "MerchantReturnPolicy",
    "applicableCountry": "US",
    {% assign is_final_sale = product.tags | where: "final-sale" | size %}
    {% if is_final_sale > 0 %}
    "returnPolicyCategory": "https://schema.org/MerchantReturnNotPermitted"
    {% else %}
    "returnPolicyCategory": "https://schema.org/MerchantReturnFiniteReturnWindow",
    "merchantReturnDays": 30,
    "returnMethod": "https://schema.org/ReturnByMail",
    "returnFees": "https://schema.org/FreeReturn",
    "merchantReturnLink": "https://{{ shop.domain }}/policies/refund-policy"
    {% endif %}
  }
}

Return policy with specific fee amount

{
  "@type": "MerchantReturnPolicy",
  "applicableCountry": "US",
  "returnPolicyCategory": "https://schema.org/MerchantReturnFiniteReturnWindow",
  "merchantReturnDays": 60,
  "returnMethod": "https://schema.org/ReturnByMail",
  "returnFees": "https://schema.org/ReturnShippingFees",
  "itemReturnShippingFeesAmount": {
    "@type": "MonetaryAmount",
    "value": "7.99",
    "currency": "USD"
  },
  "merchantReturnLink": "https://store.com/policies/refund-policy"
}

Holiday extended return window override

{
  "@type": "MerchantReturnPolicy",
  "returnPolicyCategory": "https://schema.org/MerchantReturnFiniteReturnWindow",
  "merchantReturnDays": 30,
  "returnFees": "https://schema.org/FreeReturn",
  "returnPolicySeasonalOverride": {
    "@type": "MerchantReturnPolicySeasonalOverride",
    "startDate": "2026-11-15",
    "endDate": "2027-01-31",
    "returnPolicyCategory": "https://schema.org/MerchantReturnFiniteReturnWindow",
    "merchantReturnDays": 90
  }
}

Return Policy as a Competitive Advantage in AI Results

When AI agents present product comparisons, free returns is a trust signal that moves buyers. Google's own consumer research shows "free returns" reduces purchase hesitation by up to 67% for first-time store visitors. Surfacing this in structured data means AI agents can highlight your return policy advantage in their recommendation text — without you needing to be the cheapest or best-reviewed option.

Return policy structured data checklist

MerchantReturnPolicy on Organization (homepage JSON-LD)
returnPolicyCategory set to the correct enum
merchantReturnDays as integer (not string)
returnFees enum — especially FreeReturn if you offer it
returnMethod (ReturnByMail most common for DTC)
applicableCountry for your shipping markets
merchantReturnLink pointing to your /policies/refund-policy
Per-product override for final sale or special-category items
Seasonal override for holiday extended window (if applicable)

CatalogScan Checks for Return Policy Structured Data

CatalogScan's AI Readiness scan checks for the presence of MerchantReturnPolicy on your domain — either at the Organization level (homepage JSON-LD) or the Product level (product page JSON-LD). A missing return policy is flagged as a high-priority gap because it directly affects purchase conversion in AI shopping interfaces. The scan also checks that returnPolicyCategory uses valid schema.org enum URIs and that merchantReturnDays is a number, not a string.

FAQ

What is MerchantReturnPolicy in schema.org?

MerchantReturnPolicy is a schema.org type for structured return policy data. It captures the return window (merchantReturnDays), fees (returnFees or itemReturnShippingFeesAmount), return method (mail, in-store, kiosk), applicable countries, and policy category (finite window, unlimited, or not permitted).

How do I add MerchantReturnPolicy to Shopify product JSON-LD?

Add "hasMerchantReturnPolicy" to your Product JSON-LD block with a MerchantReturnPolicy object. For store-wide policies, add it to the Organization block in your homepage JSON-LD instead — AI agents apply the organization-level policy to all products unless overridden at product level.

What is the difference between returnFees and itemReturnShippingFeesAmount?

returnFees is an enum (FreeReturn, ReturnShippingFees, OriginalShippingFees) for the general type of return cost. itemReturnShippingFeesAmount is a MonetaryAmount with a specific dollar value — use it when you charge a flat return shipping fee (e.g., $7.99 prepaid label).

Do AI shopping agents use MerchantReturnPolicy structured data?

Yes. ChatGPT Shopping, Google AI Mode, and Perplexity Shopping all surface return policy as a product attribute. Queries like "does this store have free returns?" and comparison queries pull from MerchantReturnPolicy structured data. Without it, agents skip the return info or extract low-confidence guesses from prose.

Should MerchantReturnPolicy go on the product page or the Organization?

For a store-wide policy (same rules for all products), add it once to the Organization JSON-LD on your homepage. For different policies by category (30-day standard, final sale on personalized), add per-product hasMerchantReturnPolicy overrides in each Product block.