Skip to content
Published Authored byBilly Reiner

Schema · How-to

Shopify hasMerchantReturnPolicy

hasMerchantReturnPolicy is the property that declares a return policy, on an Organization or on an Offer1. Its value is a MerchantReturnPolicy object with applicableCountry, returnPolicyCategory (one of MerchantReturnFiniteReturnWindow, MerchantReturnNotPermitted, MerchantReturnUnlimitedWindow, MerchantReturnUnspecified), merchantReturnDays, returnMethod, returnFees. Google recommends one store-wide policy under Organization, and a policy under Offer only for products that are exceptions5. On a merchant listing it's a recommended property, not a required one2. Some SEO publications claim Google AI Overviews requires it; no Google documentation says so. Add it anyway: it's how Google can show your return terms, and Shopify recommends keeping policies "complete and up-to-date" for AI agents4.

The 2026 install pattern: declare the store's return policy once, inside the Organization (OnlineStore) block, with values taken from the merchant's actual refund policy. Add an Offer-level MerchantReturnPolicy only on products with different terms, such as final-sale items. Shopify exposes the policy at shop.refund_policy and at the route /policies/refund-policy; the schema is the structured-data twin of the human-readable policy page.

What MerchantReturnPolicy is

Per Schema.org v30.0, MerchantReturnPolicy 'provides information about product return policies associated with an Organization, Product, or Offer.' Inheritance: Thing > Intangible > MerchantReturnPolicy. The type supersedes the older ProductReturnPolicy. Key properties: applicableCountry (Country or Text — ISO 3166-1 alpha-2 like 'US', 'GB', 'DE'), returnPolicyCategory (MerchantReturnEnumeration), merchantReturnDays (Integer or Date — for finite-window policies), returnMethod (ReturnMethodEnumeration), returnFees (ReturnFeesEnumeration), refundType (RefundTypeEnumeration).

Mental model: MerchantReturnPolicy declares "if a customer buys this product, here's the deal on returning it." The structured form lets Google Merchant Center, AI shopping engines, and any other downstream consumer parse the policy uniformly across millions of stores. The Shopify storefront's /policies/refund-policy page is the human-readable copy; the JSON-LD is the machine-readable version of the same facts.

What Google documents, and the AI Overviews claim

Google's merchant return policy documentation is specific. Put a standard return policy that covers most or all of your products under Organization, using hasMerchantReturnPolicy, on a single page; you don't need it on every page. Use an Offer-level MerchantReturnPolicy only to override that policy for specific products, and note that Offer-level policies support fewer properties. When both exist, the product-level policy wins. Some SEO publications go further and say Google AI Overviews requires the property on every product. No Google documentation says that, so this page doesn't repeat it.

Why ship hasMerchantReturnPolicy anyway

Three reasons to ship hasMerchantReturnPolicy. First, it's the documented way to give Google your return terms for merchant listings: Google's return policy documentation and merchant listing documentation both cover it, and the alternatives Google names are settings in Merchant Center or Search Console, or the Content API for Shopping. Second, Shopify's own AI-optimisation doc names keeping policies 'complete and up-to-date' as one of its recommendations for AI agent reference. Third, it's cheap: the policy already exists in plain words on the store.

Cost to ship is low. The merchant already has a real return policy on /policies/refund-policy. The schema work is one MerchantReturnPolicy object that translates the existing policy values into properties, placed once in the Organization block, plus an Offer-level override on the few products that differ.

MerchantReturnPolicy fields

Google's return policy documentation requires either applicableCountry plus returnPolicyCategory (and merchantReturnDays for a finite window), or a merchantReturnLink to the policy page on its own. The field set Schema.org documents: applicableCountry (one or array of ISO 3166-1 alpha-2 country codes — the geographies where the policy applies), returnPolicyCategory (a MerchantReturnEnumeration URL), merchantReturnDays (when returnPolicyCategory is MerchantReturnFiniteReturnWindow), returnMethod (ReturnMethodEnumeration URL — ReturnByMail, ReturnInStore, ReturnAtKiosk), returnFees (ReturnFeesEnumeration URL — FreeReturn, RestockingFees, ReturnFeesCustomerResponsibility, ReturnFeesEnumerated), refundType (RefundTypeEnumeration URL).

  • applicableCountry — required. ISO 3166-1 alpha-2. For a Shopify store shipping to US only, 'US'. For multi-country, an array.
  • returnPolicyCategory — required. Most Shopify stores: https://schema.org/MerchantReturnFiniteReturnWindow.
  • merchantReturnDays — required when category is MerchantReturnFiniteReturnWindow. The integer number of days the customer has to return.
  • returnMethod — recommended. https://schema.org/ReturnByMail for most ecommerce.
  • returnFees — recommended. https://schema.org/FreeReturn if returns are free; https://schema.org/ReturnFeesCustomerResponsibility if the customer arranges and pays for return shipping; https://schema.org/ReturnShippingFees if you charge a return shipping fee, stated in returnShippingFeesAmount5.
  • refundType — optional. https://schema.org/FullRefund or https://schema.org/StoreCredit.

JSON-LD example — MerchantReturnPolicy on Organization

The block below is the hasMerchantReturnPolicy property for the store-wide policy. It goes inside your one Organization (OnlineStore) block, alongside name, url and logo. Hard-coded values suit a universal policy (30-day finite window, free returns by mail). The same object shape works inside an Offer when one product needs different terms, though Offer-level policies accept fewer properties.

JSON-LD hasMerchantReturnPolicy inside the Organization block (or inside an Offer, for a product-specific exception) 
"hasMerchantReturnPolicy": {
  "@type": "MerchantReturnPolicy",
  "applicableCountry": "US",
  "returnPolicyCategory": "https://schema.org/MerchantReturnFiniteReturnWindow",
  "merchantReturnDays": 30,
  "returnMethod": "https://schema.org/ReturnByMail",
  "returnFees": "https://schema.org/FreeReturn",
  "refundType": "https://schema.org/FullRefund"
}

For final-sale or non-returnable products (cosmetics, perishables, custom orders), add an override on that product's Offer: returnPolicyCategory: "https://schema.org/MerchantReturnNotPermitted", with the merchantReturnDays / returnMethod / returnFees fields dropped. Branch on a product metafield (e.g. custom.final_sale = true) in the product template so only those products carry it. Google uses the product-level policy where both exist2.

Validation

The Rich Results Test supports return policy markup as its own type. Test the page that carries the Organization block: expect the return policy detected with zero errors. The strict minimum is applicableCountry and returnPolicyCategory, plus merchantReturnDays for a finite window, or a merchantReturnLink alone. For an Offer-level override, test the product page; the policy shows up inside the merchant listing. Schema.org Markup Validator confirms structural validity.

Return policy is on Google's list of Rich Results Test types6, so you can check the Organization-level block directly. If you also use Merchant Center, know which source wins. Google applies return policies in this order, strongest first: the Content API for Shopping, settings in Merchant Center or Search Console, product-level markup, organization-level markup5. A policy set in Merchant Center overrides the markup, so keep the two in agreement to avoid showing shoppers two different return windows.

Shopify gotchas on hasMerchantReturnPolicy

Four gotchas. First: emitting an empty MerchantReturnPolicy object on a store that hasn't configured its refund policy — validators accept the empty object, but the markup is meaningless. Wrap emission in a Liquid conditional on the metafield or hard-code the policy only after the merchant ships their real one. Second: hard-coding applicableCountry: 'US' on a multi-country store, misrepresenting policy to customers outside the US. Third: emitting MerchantReturnFiniteReturnWindow without merchantReturnDays — Google requires the day count for a finite window. Fourth: using a string for merchantReturnDays ('30') instead of an integer (30) — Google's documentation types it as an Integer, so print a number.

A fifth gotcha for stores with category-specific policies (clothing returnable within 30 days, electronics within 14, custom orders not returnable): declare the most common policy on Organization, then build a metafield-driven branch in the product template that adds an Offer-level MerchantReturnPolicy only for the product types that differ. The Liquid grows complex; the ROI is policy-customer agreement, which matters for trust regardless of schema.

Keep reading