MerchantReturnPolicy schema: store-wide returns and shipping in Organization markup

JSON-LD example

Copy this into a <script type="application/ld+json"> tag and replace the values with your own.

{
  "@context": "https://schema.org",
  "@type": "OnlineStore",
  "name": "Fernhill Ceramics",
  "url": "https://example.com/",
  "hasMerchantReturnPolicy": {
    "@type": "MerchantReturnPolicy",
    "applicableCountry": [
      "US",
      "CA"
    ],
    "returnPolicyCategory": "https://schema.org/MerchantReturnFiniteReturnWindow",
    "merchantReturnDays": 30,
    "returnMethod": "https://schema.org/ReturnByMail",
    "returnFees": "https://schema.org/FreeReturn",
    "refundType": "https://schema.org/FullRefund",
    "itemCondition": "https://schema.org/NewCondition"
  },
  "hasShippingService": {
    "@type": "ShippingService",
    "name": "Standard shipping",
    "shippingConditions": [
      {
        "@type": "ShippingConditions",
        "shippingDestination": {
          "@type": "DefinedRegion",
          "addressCountry": "US"
        },
        "orderValue": {
          "@type": "MonetaryAmount",
          "minValue": 0,
          "maxValue": 74.99,
          "currency": "USD"
        },
        "shippingRate": {
          "@type": "MonetaryAmount",
          "value": 7.5,
          "currency": "USD"
        },
        "transitTime": {
          "@type": "ServicePeriod",
          "duration": {
            "@type": "QuantitativeValue",
            "minValue": 3,
            "maxValue": 5,
            "unitCode": "DAY"
          }
        }
      },
      {
        "@type": "ShippingConditions",
        "shippingDestination": {
          "@type": "DefinedRegion",
          "addressCountry": "US"
        },
        "orderValue": {
          "@type": "MonetaryAmount",
          "minValue": 75,
          "currency": "USD"
        },
        "shippingRate": {
          "@type": "MonetaryAmount",
          "value": 0,
          "currency": "USD"
        }
      }
    ]
  }
}

Properties

Where the policy lives, and what overrides it

Google recommends putting the store-wide policy on one page, typically your returns or shipping page, rather than on every page. Individual products that follow different rules get an Offer-level policy in their Product markup, which supports only a subset of these properties; see Product schema for that side.

When several sources disagree, Google applies this order, strongest first:

1. Return and shipping settings sent through the Content API for Shopping
2. Settings in Merchant Center or Search Console
3. Product-level merchant listing markup
4. Organization-level markup

So if you have entered return settings in Search Console, Google uses those and ignores the markup. Keep all of them saying the same thing, or pick one source and maintain it.

Describing the return window

You have two ways to meet the requirement. Option A spells out the policy with applicableCountry, returnPolicyCategory and, for a finite window, merchantReturnDays. Option B is only merchantReturnLink, a URL to the written policy. Option A gives Google details it can show; Option B is quicker when the policy is complicated or handled by a returns service.

Holidays are where policies change. returnPolicySeasonalOverride lets you state, say, that purchases between November 15 and December 24 can be returned until January 31, while the normal 30-day rule covers the rest of the year. The fee properties also split by reason: customerRemorseReturnFees for change-of-mind returns and itemDefectReturnFees for faulty items, so free returns for defects and paid returns for everything else can both be described.

Store-wide shipping rates

Each ShippingConditions item pairs a situation (destination, order value, weight or item count) with a shippingRate and transitTime. When more than one condition fits a product, Google uses the lowest cost, and if costs tie, the fastest option. The example gives US orders under $75 a $7.50 rate and free shipping above that.

A few limits are worth knowing. Region codes in addressRegion work only for the US, Australia and Japan. Use doesNotShip: true to say a destination isn't served, rather than leaving it out. If you use validForMemberTier for loyalty-member rates, Google requires at least one regular, non-member service as well.

Adding it to a WooCommerce store

WooCommerce prints Product markup with an Offer on product pages. Before adding store-wide policies, view a product's source and look for any Offer-level hasMerchantReturnPolicy or shippingDetails that contradicts what you plan to publish.

Hydrogen SEO prints your Organization from the Schema screen. To extend it rather than add a second organization, find that node in the hydrogen_seo_schemas filter and attach the policy on your returns page:

add_filter( 'hydrogen_seo_schemas', function ( $schemas ) {
    if ( ! is_page( 'returns' ) ) {
        return $schemas;
    }
    foreach ( $schemas as &$node ) {
        if ( isset( $node['@type'] ) && in_array( $node['@type'], [ 'Organization', 'OnlineStore' ], true ) ) {
            $node['hasMerchantReturnPolicy'] = my_store_return_policy(); // The array from the example.
        }
    }
    return $schemas;
} );

If the Organization sits inside an @graph in your output, loop over that array instead. Then check the returns page in the JSON-LD checker.