---
title: "Machine-readable return policy · Specoria"
description: "Machine-readable return policy: The return window is an agent filter; a store it can’t verify isn’t recommended to a shopper who wants returns."
source_url: "https://specoria.com/method/checks/returns-machine/"
lang: "en"
---

[← All checks](https://specoria.com/method/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.

- Passed Your return policy is defined in structured data and complete (window type, days and country; at product or organization level).
- Partial Your return policy is in structured data but incomplete: …. Without these fields agents and Google can’t fully verify the condition.
- Failed Your 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

- [schema.org/MerchantReturnPolicy ↗](https://schema.org/MerchantReturnPolicy)
- [Google: merchant listing structured data ↗](https://developers.google.com/search/docs/appearance/structured-data/merchant-listing)

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 →](https://specoria.com/method/#criteria)

[← PreviousCan variants (size, color) be addressed?](https://specoria.com/method/checks/variants/)[Next →Returns page and window](https://specoria.com/method/checks/returns-human/)

[Run the free test](https://specoria.com/method/checks/returns-machine/#test) [See the sample report →](https://specoria.com/reports/sample-report/)

## Related

- [Returns page and window](https://specoria.com/method/checks/returns-human/)
- [Machine-readable shipping information](https://specoria.com/method/checks/shipping-machine/)
- [Agent Readiness Index 2027](https://specoria.com/index/) How the benchmarked stores scored, with open data
- [Agentic commerce statistics](https://specoria.com/agentic-commerce-statistics/) Sourced, dated figures you can cite

FREE TEST

## Test your store now

Enter your store’s address: 27 checks on your public pages, the way a shopping agent reads them.

The free test runs in your browser and needs JavaScript. [Request the free deep audit by email instead →](https://specoria.com/#contact)

Your result opens on its own page. Want the full picture? The free deep audit and panel come next, by email.