Skip to content
Sign in

Guide9 min readPublished

Shipping and return policies AI agents can read

Where Google wants shipping and return policies, how to write them as markup and as pages an AI agent can read, with builders for both and a check for your policy text.

How do you make shipping and return policies readable to an AI agent? Publish each as a plain HTML page that states the costs with a currency, the delivery times and the return window in days, link both from every page, and add the same terms as schema.org markup: a MerchantReturnPolicy and a shipping policy for the whole store, with product-level markup only where a product differs. A policy that lives in a PDF, or says "contact us", gives an agent nothing to tell the shopper.

This guide covers where Google wants each policy, a builder for the return policy and the shipping details, and a check that reads your policy text the way our scan does. Storewalk is ours: we build the scan, and its shipping and returns checks are ours. Google and schema.org are quoted from their own pages, read on 3 November 2026. For the Product markup that the policies hang off, see product structured data for AI agents.

Why do shipping and returns matter to an AI agent?

They are the two answers a shopper wants before paying, and an assistant can only give them if it can find them. "What does delivery cost to Lyon?" and "Can I send it back if it doesn't fit?" are ordinary questions. The answers can sit in a footer link, behind a "calculated at checkout", or in a PDF. A person shrugs and clicks through. An agent working for that person has to stop, or guess, and we would rather it did neither.

Google gives the same reason in its own words. When it added store-wide return policies in June 2024, it wrote: "A return policy is a major factor considered by shoppers when buying products online". Its merchant listings recommend shipping details and a return policy on each offer, beside the price they require, or, better, once for the whole store.

Where should the policies go: the store or each product?

Google's answer for both is the store, with exceptions on the product. Return policies first: "A standard return policy for your business that applies to most or all products you sell can be specified using the MerchantReturnPolicy structured data type nested under the Organization structured data type using the hasMerchantReturnPolicy property." It adds: "We recommend placing return information on a single page on your site that describes the return policy of your business. You don't need to include it on every page of your site." A product that differs gets its own policy on its Offer.

Shipping follows the same pattern, with a different type. The store's standard policy is a ShippingService under the Organization, using hasShippingService, whose one required property is shippingConditions: the cost and delivery time for a set of conditions such as a destination or an order value. A product that ships differently gets an OfferShippingDetails on its Offer, under shippingDetails.

If you tell Google the same thing in several places, it has a ranking. "Google uses the following order of precedence (from strongest to weakest)":

  1. The Content API for Shopping.
  2. Settings in Merchant Center or Search Console.
  3. Product-level merchant listing markup.
  4. Organization-level markup.

So settings in Merchant Center or Search Console beat your markup. For Search Console, Google spells it out: if you provide both, "Google will only use the information provided in Search Console." The ranking is Google's, for Google's own results. Other agents can only read what is on your site: the markup and the policy pages.

How do you write a return policy in markup?

Google gives two ways to meet its requirement. Option A is the policy itself: applicableCountry, the countries it covers as two-letter codes ("You can specify up to 50 countries"), and returnPolicyCategory, one of a set number of days, no time limit, or no returns. With a set number of days, merchantReturnDays is required too. schema.org defines it as "the number of days (from the delivery date) that a product can be returned." Option B is a link: merchantReturnLink, "the URL of a web page that describes the return policy to your customers."

The rest is recommended: who pays for the postage (returnFees), how the item comes back (returnMethod), and the fee if there is one. Build yours:

A return policy markup builder, for the store or one product
Where the policy goes
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Northwind Linen",
  "url": "https://example.com",
  "hasMerchantReturnPolicy": {
    "@type": "MerchantReturnPolicy",
    "applicableCountry": [
      "DE",
      "FR",
      "NL"
    ],
    "returnPolicyCategory": "https://schema.org/MerchantReturnFiniteReturnWindow",
    "merchantReturnDays": 30,
    "returnMethod": "https://schema.org/ReturnByMail",
    "returnFees": "https://schema.org/FreeReturn",
    "merchantReturnLink": "https://example.com/policies/returns"
  }
}
</script>

A complete block: paste it into your page’s HTML as it stands, script tag and all.

  • Yes: Required: applicableCountry with returnPolicyCategory (A), or merchantReturnLink (B) (Google)
  • Yes: For option A, countries as two-letter ISO 3166-1 alpha-2 codes, up to 50 (Google)
  • Yes: merchantReturnDays, required with a set number of days (Google)
  • Yes: A non-zero returnShippingFeesAmount when the customer pays a fee (Google)
  • Not yet: Our EVAL-002 does not read Organization markup yet, so it reads your returns page (our check)

Source: Google Search Central: Merchant return policy structured data

Our own check has a gap here. The returns check reads a return policy on the product or its offer, or a MerchantReturnPolicy node on a product page. It does not read the Organization-level policy yet, the very place Google recommends, so a store that follows Google's advice is judged on its returns page instead. That's fine if the page states the window in days, which is one more reason to make the page good.

How do you write shipping costs and delivery times in markup?

For a product, Google's merchant-listing page lists three required properties of OfferShippingDetails: shippingRate, with a value and a currency ("The currency must be the same as the currency of the offer"), shippingDestination with a two-letter country, and deliveryTime, split into handling time and transit time. Free shipping is a rate of zero: "To specify free shipping, set the value to 0." Each block holds one rate, so three different rates are three blocks.

A shipping details markup builder, for one destination and rate
"offers": {
  "@type": "Offer",
  "shippingDetails": {
    "@type": "OfferShippingDetails",
    "shippingRate": {
      "@type": "MonetaryAmount",
      "value": "4.90",
      "currency": "EUR"
    },
    "shippingDestination": {
      "@type": "DefinedRegion",
      "addressCountry": "DE"
    },
    "deliveryTime": {
      "@type": "ShippingDeliveryTime",
      "handlingTime": {
        "@type": "QuantitativeValue",
        "minValue": 0,
        "maxValue": 1,
        "unitCode": "DAY"
      },
      "transitTime": {
        "@type": "QuantitativeValue",
        "minValue": 2,
        "maxValue": 4,
        "unitCode": "DAY"
      }
    }
  }
}

A fragment: paste it inside your Product, merged with the offer’s price and stock.

  • Yes: shippingDestination.addressCountry as a two-letter code (Google)
  • Yes: shippingRate.value as a number, above 0 when you charge (Google)
  • Yes: shippingRate.currency, the same as the offer’s currency (Google)
  • Yes: deliveryTime with handling and transit days (Google)
  • Yes: Our EVAL-001 passes a product whose offer carries OfferShippingDetails, paid or free (our check)

One destination and one rate per block; Google asks for a separate OfferShippingDetails for each further rate. Built in your browser; nothing is sent.

Source: Google Search Central: Merchant listing structured data (shipping details)

Our shipping check passes a product whose offer carries OfferShippingDetails, with one exception. If the markup says shipping is free and your shipping page states a cost and never says free, it warns, because the store is telling agents something its own page contradicts. The store-level ShippingService is not read yet; as with returns, the shipping page stands in for it.

What should the policy pages themselves say?

The page is where the policy lives, and every reader can use it. Our checks look for four things on it:

  • It is HTML text. An agent can't read terms out of a PDF, an image of a rate table, or a page that is one embedded PDF. Our checks fail a policy like that, unless the product markup (or, for shipping, the product page) already states the terms. A table image whose alt text carries the rates is fine.
  • The shipping page states a cost with a currency, or commits to free delivery. "Shipping calculated at checkout", with nothing else, fails. A delivery time with no cost is a warning.
  • The returns page states a window in days, weeks or months. "Contact us to arrange a return" is a published policy that an agent can't act on, and our check warns on it.
  • The page and the markup agree. If the markup says 45 days and the page only ever says 30, our returns check warns. A page that states two windows, such as 14 days by law and 30 days by choice, passes as long as the markup's window is one of them.

Paste your own policy text and set what your markup says:

What our checks find in your policy text

Return windows found: 14 days, 30 days

Amounts with a currency: €4.90, €80; a free-shipping phrase: “Free delivery”

PASS EVAL-001, if this were your shipping page: HTML shipping policy states costs with an explicit currency

PASS EVAL-002, if this were your returns page: The HTML return policy states a 30-day window

Our checks read the shipping and returns pages separately; this box reads one text both ways. Weeks and months count as 7 and 30 days. Read in your browser; nothing is sent.

Then link both pages from the footer of every page, with the words "Shipping" and "Returns" in the links. Our crawler finds policy pages by their links and a few usual paths, and an agent has little else to go on.

What do Shopify, WooCommerce, BigCommerce and Magento do?

On Shopify, policies are written under Settings > Policies and served at /policies/refund-policy and /policies/shipping-policy. Shopify warns: "Don't assume that an automatically published policy includes every detail your business needs." The structured_data filter page doesn't mention shipping details or return policy markup, so check what your theme prints. See the Shopify guide.

On WooCommerce, version 11.3 is "scheduled for the week of November 9, 2026", and its pre-release post says it "adds structured data linking to the selected policy page": a MerchantReturnPolicy with a merchantReturnLink. Core prints no shipping details in its product markup. See the WooCommerce guide.

On BigCommerce, the policy is a page you make yourself under Storefront › Web Pages, and the Cornerstone theme prints no policy markup. On Magento, the shipping policy text set under Stores > Configuration is shown during checkout, which makes it a little late for an agent comparing shops; returns (RMA) exist only in Adobe Commerce. The BigCommerce and Magento guides have the paths.

Once your pages and markup agree, run a scan. The agent readiness checklist has the rest of the list, and prices, stock and variants covers the other half of what an agent compares.

Frequently asked questions

Do I need return policy markup on every product page?

No. Google recommends one return policy for the store, under your Organization markup, on a single page, and a product-level policy only for products that differ. Note that our own returns check reads product-level markup and your returns page, and does not read the Organization-level policy yet.

What does Google require in a MerchantReturnPolicy?

Either applicableCountry with returnPolicyCategory (plus merchantReturnDays for a set window), or a merchantReturnLink to your returns page. Return fees, the return method and the rest are recommended.

How do I mark up free shipping?

Set the shippingRate value to 0, with your currency, in the OfferShippingDetails. Google: "To specify free shipping, set the value to 0." Make sure your shipping page says free as well, or our shipping check warns that the two disagree.

Can my shipping policy be a PDF?

It can, but an agent can't read it. Our shipping and returns checks fail a policy that is a PDF or an image, unless the product markup (or, for shipping, the product page) already states the terms. Publish the same terms as an HTML page.

Which wins if Merchant Center and my markup disagree?

For Google, Merchant Center. Its order of precedence puts settings in Merchant Center or Search Console above product-level markup, and product-level markup above Organization-level markup. Other agents only see what is on your site.

The sources below were last checked on the date shown.