Skip to content
Published Authored byBilly Reiner

Schema · How-to

Shopify hasMerchantReturnPolicy

hasMerchantReturnPolicy is the Offer property that declares the return policy attached to a sale1. Its value is a MerchantReturnPolicy object with applicableCountry, returnPolicyCategory (one of MerchantReturnFiniteReturnWindow, MerchantReturnNotPermitted, MerchantReturnUnlimitedWindow, MerchantReturnUnspecified), merchantReturnDays, returnMethod, returnFees. Third-party SEO publications throughout 2026 claim Google AI Overviews now treats this property as effectively required for Product visibility — [UNVERIFIED — third-party only]. Shopify's primary docs do not codify this requirement at our verification window (2026-05-22). We recommend the field anyway, because Google Merchant Center has required it for Shopping eligibility for over a year2, and Shopify itself recommends keeping policies "complete and up-to-date" for AI agent reference4.

The 2026 install pattern: emit a MerchantReturnPolicy sub-object inside Offer on every Shopify PDP, with the values pulled from the merchant's actual refund policy. 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.

The AI Overviews claim — [UNVERIFIED]

Industry SEO publications throughout Jan–May 2026 repeatedly state that Google AI Overviews now treats hasMerchantReturnPolicy (and shippingDetails) as effectively required on Product schema — without them, products become invisible to AI shopping recommendations. This claim is widespread but has not been confirmed in Shopify's primary documentation or in Google Search Central's own AI Overviews policy statements at our verification window. We mark it [UNVERIFIED — third-party only].

Why ship hasMerchantReturnPolicy anyway

Three reasons to ship hasMerchantReturnPolicy regardless of whether the AI Overviews claim turns out exact. First, Google Merchant Center has required (effectively) this field for over a year for Shopping eligibility — stores running Merchant Center feeds already need it. 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, AI shopping engines (ChatGPT, Perplexity, Gemini, Copilot) all read structured-data policy fields when surfacing recommendations; the field demonstrably helps even if the specific AI Overviews threshold is unverified.

Cost to ship is low. The merchant already has a real return policy on /policies/refund-policy. The schema work is a Liquid block that translates the existing policy values into MerchantReturnPolicy properties — one block, reused inside Offer on every product page.

MerchantReturnPolicy fields

The fields Google's Product documentation names as required for the property and 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/ReturnShippingFees if the customer pays return shipping.
  • refundType — optional. https://schema.org/FullRefund or https://schema.org/StoreCredit.

JSON-LD example — MerchantReturnPolicy inside Offer

The block below shows hasMerchantReturnPolicy inside the Offer sub-object of a Shopify Product block. Hard-coded values where the merchant's policy is universal (30-day finite window, free returns by mail); use a metafield for stores where the policy varies by country or product.

JSON-LD hasMerchantReturnPolicy inside Offer, inside Product, inside main-product.liquid 
 "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), the block changes to returnPolicyCategory: "https://schema.org/MerchantReturnNotPermitted" and the merchantReturnDays / returnMethod / returnFees fields are dropped. Branch on a product metafield (e.g. custom.final_sale = true) to handle both cases in one Liquid template.

Validation

Rich Results Test against a PDP with hasMerchantReturnPolicy should report Product detected, Offer parsed, MerchantReturnPolicy parsed, zero errors. The Rich Results Test does not actually require all five fields to validate — applicableCountry and returnPolicyCategory are the strict minimum. Schema.org Markup Validator confirms structural validity.

For Merchant Center eligibility, the JSON-LD MerchantReturnPolicy must agree with the feed's return-policy attributes. Mismatch (different merchantReturnDays in the feed vs the schema) flags in Merchant Center diagnostics. Some Shopify Merchant Center sync apps generate a separate Merchant Center return policy ID; align that ID with the schema if your store uses one.

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 — the validator flags this. Fourth: using a string for merchantReturnDays ('30') instead of an integer (30) — Schema.org accepts both but Google's parser sometimes complains about the string form.

A fifth gotcha for stores with category-specific policies (clothing returnable within 30 days, electronics within 14, custom orders not returnable): build a metafield-driven branching block that emits a different MerchantReturnPolicy per product type. The Liquid grows complex; the ROI is policy-customer agreement, which matters for trust regardless of schema.

Keep reading