Return and Shipping Markup for Merchant Listings

The two markup fields that unlock shipping and returns in listings

Your listings can show delivery estimates and return windows right beside the price, but only if Google can read them as structured data. Two Offer-level fields control this, both missing from every default Shopify theme. Here is what they do, the shortcut that avoids code entirely, and copy-paste examples for the exceptions.

By Hazzy · Software engineer, former SEO specialist

The two fields

Both live inside the Offer, not the Product. Placed on the Product they are ignored. shippingDetails (OfferShippingDetails) declares shipping cost, destination and delivery time. hasMerchantReturnPolicy (MerchantReturnPolicy) declares the return window, fees and conditions. Google lists both as recommended rather than required, which undersells them: without one of them set somewhere, your result simply cannot show delivery or return information, and it looks thinner than every competitor that does.

One storewide policy belongs in Merchant Center; only genuine per-product exceptions belong in page markup. Both paths feed the same listing display.

The account-level shortcut

If your shipping rates and return window are the same across the catalogue, do not touch the theme: set shipping and returns once in Merchant Center (or Search Console shipping settings) and Google applies them to every listing on the account. No schema, no code, no per-product maintenance. This covers the requirement for the overwhelming majority of stores, and the remaining Search Console warnings about the page fields become safely ignorable.

Do the easy thing first

Merchant Center settings cover the whole account in minutes. Only reach for JSON-LD when specific products genuinely differ: final-sale items, oversized surcharges, extended warranties.

Per-product exceptions, with examples

When one product breaks the storewide rule, override it inside that product Offer:

"hasMerchantReturnPolicy": {
  "@type": "MerchantReturnPolicy",
  "applicableCountry": "US",
  "returnPolicyCategory": "https://schema.org/MerchantReturnFiniteReturnWindow",
  "merchantReturnDays": 14,
  "returnMethod": "https://schema.org/ReturnByMail"
},
"shippingDetails": {
  "@type": "OfferShippingDetails",
  "shippingRate": { "@type": "MonetaryAmount", "value": "12.00", "currency": "USD" },
  "shippingDestination": { "@type": "DefinedRegion", "addressCountry": "US" },
  "deliveryTime": {
    "@type": "ShippingDeliveryTime",
    "handlingTime": { "@type": "QuantitativeValue", "minValue": 1, "maxValue": 2, "unitCode": "DAY" },
    "transitTime": { "@type": "QuantitativeValue", "minValue": 3, "maxValue": 5, "unitCode": "DAY" }
  }
}

Keep markup truthful

These values must match the policy you actually honour. Markup that overstates a return window or understates a shipping cost is treated like fabricated ratings: a data-quality violation that can suppress the listing, not a clever optimisation. Point every field at real settings and keep them in sync when settings change.

Deeper: product schema pillar · Related guides: hasMerchantReturnPolicy missing · shippingDetails missing

Find out if this is happening to you

Shipwork reads your product page markup and reports whether each Offer carries hasMerchantReturnPolicy and shippingDetails: alongside every other missing field. Free, no account, no signup. Paste your store address.

Check my markup

Questions

Can I ignore the shippingDetails warning if Merchant Center has my shipping?

Yes: with account-level shipping set, the page-level warning is non-critical. Add page markup only for products that genuinely differ.

Where do these fields go: Product or Offer?

Offer. Placed on the Product they are ignored, which is one of the most common implementation mistakes.

What values can returnMethod take?

Schema.org defines ReturnByMail, ReturnAtKiosk, ReturnInStore and others. Use the one matching your actual policy, never an aspirational one.

Do I need deliveryTime as well as shippingRate?

Rate alone unlocks the cost display; adding handling and transit times unlocks the delivery-date display. Both beat neither.

Keep reading

Product Schema JSON-LD for Shopify: Full Guide Product Schema Example: JSON-LD for Products and Variants Product Variants Schema: ProductGroup Guide Google Merchant Center Requirements for Shopify