Specoria
Menu
TR Free test
← All checks
returns_machine

Machine-readable return policy

Why it matters The return window is an agent filter; a store it can’t verify isn’t recommended to a shopper who wants returns.

Category
Policies and trust
Weight
5 of 100 points
Critical blocker
No. If it fails, it only costs its own weight.
Applies to
Online stores
Effort
1-2 hours · developer (once, at organization level)
Score model
v2.4

How we measure it

We look for a machine-readable return policy (MerchantReturnPolicy) at product, offer or Organization level, resolving @id references. We check three fields: the window type (returnPolicyCategory), a whole number of days for a finite window (merchantReturnDays; “30 days” or 14.5 don’t count) and the country (applicableCountry). All complete passes; a policy with missing fields is a partial pass (one missing 0.75, two 0.6, all three 0.5 points); no policy fails.

What the result page says

These are the sentences in the test result; “…” is replaced by what we found on your site.

  • PassedYour return policy is defined in structured data and complete (window type, days and country; at product or organization level).
  • PartialYour return policy is in structured data but incomplete: …. Without these fields agents and Google can’t fully verify the condition.
  • FailedYour return policy isn’t in structured data, so an agent can’t verify a condition like “…-day returns”.

How to fix it

Target: The return policy is defined once at organization level (OnlineStore → hasMerchantReturnPolicy) or on the product offer, with the same values as your returns page.

Example code

{
  "@context": "https://schema.org",
  "@type": "OnlineStore",
  "@id": "https://example.com/#org",
  "name": "Store Name",
  "url": "https://example.com",
  "hasMerchantReturnPolicy": {
    "@type": "MerchantReturnPolicy",
    "applicableCountry": "US",
    "returnPolicyCountry": "US",
    "returnPolicyCategory": "https://schema.org/MerchantReturnFiniteReturnWindow",
    "merchantReturnDays": 30,
    "returnMethod": "https://schema.org/ReturnByMail",
    "returnFees": "https://schema.org/FreeReturn"
  }
}

Example values (example.com, product name, price) are placeholders; replace them with your own.

How to verify it yourself

The Rich Results Test should show the return policy under “Merchant listings”. Note: if it’s set in Google Merchant Center, that setting applies on Google.

Fix it with an AI coding agent

Paste this into Claude Code, Cursor or another coding agent working on your store’s code. Review the change before you deploy it.

You are working on my online store. Specoria’s agent readiness test checks the item below. Fix it so AI shopping agents can read the store and act on it.

## 1. Machine-readable return policy (returns_machine)
Target: The return policy is defined once at organization level (OnlineStore → hasMerchantReturnPolicy) or on the product offer, with the same values as your returns page.
Example fix (adapt it to this codebase and platform; example values are placeholders):
```
{
  "@context": "https://schema.org",
  "@type": "OnlineStore",
  "@id": "https://example.com/#org",
  "name": "Store Name",
  "url": "https://example.com",
  "hasMerchantReturnPolicy": {
    "@type": "MerchantReturnPolicy",
    "applicableCountry": "US",
    "returnPolicyCountry": "US",
    "returnPolicyCategory": "https://schema.org/MerchantReturnFiniteReturnWindow",
    "merchantReturnDays": 30,
    "returnMethod": "https://schema.org/ReturnByMail",
    "returnFees": "https://schema.org/FreeReturn"
  }
}
```
Reference: https://specoria.com/method/checks/returns-machine/

## Rules
- First look through the codebase and tell me which files or templates you will change, before editing anything.
- Change only what these checks need, and keep the visible page and the structured data saying the same thing.
- Never invent prices, stock, shipping or return terms, reviews or product identifiers (GTIN): take them from the store’s real data or ask me.
- Don’t block or slow down real visitors and don’t add tracking.
- After deploying, run the free test again at https://specoria.com/ to verify the fix.

Specifications and guidance

The check is based on these open sources; links go to the publisher’s own pages.

Where it sits in the 196-criteria framework

The result of this check counts as evidence for these items of the readiness framework:

  • 2.5 MerchantReturnPolicy is structured
  • 6.4 The return policy is machine-readable and matches practice

The framework and its source →

Run the free test See the sample report →