# Shipping & Returns Policy Extractor – Costs, Times, Returns (`fast_data_asap/shop-shipping-returns-extractor`) Actor

Extract shipping costs, free-shipping threshold, delivery times, carriers, express option, return window, free returns and withdrawal period (Widerrufsfrist) from any online shop. English + German, Shopify-aware, JSON-LD included. One flat row per shop.

- **URL**: https://apify.com/fast_data_asap/shop-shipping-returns-extractor.md
- **Developed by:** [Fast Data](https://apify.com/fast_data_asap) (community)
- **Categories:** E-commerce, AI
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$3.00 / 1,000 shop analyseds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Shipping & Returns Policy Extractor – Costs, Times, Returns

Turn any online shop's **shipping and returns policy into structured data**. Give it shop domains and get one flat row per shop: **free-shipping threshold, shipping costs per country/zone, delivery times, carriers, express option, return window, free returns, return costs and the legal withdrawal period (Widerrufsfrist)**. Every value comes with a confidence level and a short evidence snippet from the policy page.

Works with **English and German** shops, knows **Shopify** policy pages, and also reads `shippingDetails` and `hasMerchantReturnPolicy` **JSON-LD**.

### What it does

For each shop domain or URL:

1. Reads `robots.txt` and fetches the home page over plain HTTP. It uses no browser, no login and no bot-protection bypass, which keeps it fast and cheap.
2. Finds the **shipping**, **returns** and **withdrawal** pages from footer and navigation links. It matches link text and URLs such as *shipping, delivery, Versandkosten, Versand & Lieferung, Lieferbedingungen, Zahlung & Versand, returns, refund, Retoure, Rücksendung, Rückgabe, Widerrufsbelehrung*. If that is not enough it follows help-centre links (*Hilfe, Service, Kundenservice, FAQ*), tries Shopify's `/policies/` pages, the sitemap and common paths such as `/versandkosten`, `/lieferung`, `/hilfe/versand`, `/service/ruecksendung` or `/widerrufsbelehrung`, and uses the AGB page for the withdrawal period. Login, account, cart and click-&-collect pages are never used as policy pages.
3. Pulls the policy details out of the page text with English and German patterns:
   - **Shipping:** free-shipping threshold and currency, shipping cost min/max, a per-country/zone cost list (table layouts too), delivery days min/max, named carriers (DHL, DPD, UPS, FedEx, GLS, Hermes, USPS, Royal Mail, Evri, Deutsche Post and more), express option
   - **Returns:** return window in days, free returns yes/no, return cost (with a per-country table when the shop lists one)
   - **Withdrawal:** the legal withdrawal period, e.g. *"Die Widerrufsfrist beträgt vierzehn Tage"* → 14
4. Reads JSON-LD `OfferShippingDetails` and `MerchantReturnPolicy` from the home page and one product page.
5. Applies plausibility rules: standard shipping costs 0–50 (order-value bands, minimum order values and bulky/freight rates are not taken as the shipping cost; outliers only as a `low` confidence fallback), free-shipping threshold > 0, delivery days 0–30 from the most specific standard-parcel sentence, return window 7–365 days.
6. Returns one flat row per shop with a `confidence` value (`found` / `inferred` / `missing`) and an `evidence` snippet of up to 200 characters for every field.

### Who it's for

- **Merchants** comparing their shipping and returns offer with competitors (free-shipping threshold, return window, free returns)
- **E-commerce agencies and consultants** auditing many shops at once
- **AI shopping agents and LLM apps** that need machine-readable delivery and return terms
- **Market researchers** tracking shipping and returns terms across a whole niche

### Why use this instead of the alternatives

- **Policy data, not just links.** Most store scrapers stop at "here is the refund policy URL". This actor extracts the numbers.
- **German shops supported.** It knows Versandkosten, Lieferzeit, Werktage, Rückgaberecht, Retourenkosten and Widerrufsfrist, including spelled-out numbers like "vierzehn Tage".
- **Not Shopify-only.** It finds policy pages on any platform through links and the sitemap.
- **Traceable.** Every value has an evidence snippet and a confidence level, so you can check it or filter out guesses.
- **Cheap and fast.** Plain HTTP, about 5–15 page requests per shop, and the three default shops finish in under 10 seconds.

### Input example

```json
{
  "shops": ["www.allbirds.com", "www.bergfreunde.de", "www.manufactum.de"],
  "language": "auto",
  "checkProductPage": true,
  "respectRobotsTxt": true
}
```

- `shops`: domains or URLs (required)
- `language`: `auto` (default), `en` or `de`. English and German patterns always run; the hint sets the `Accept-Language` header and the reported language.
- `checkProductPage`: also read the JSON-LD of one product page (default `true`)
- `respectRobotsTxt`: skip pages that robots.txt disallows (default `true`)
- `maxConcurrency`, `proxyConfiguration`: optional

### Output example

This row comes from a real run (the zone lists are shortened):

```json
{
  "domain": "bergfreunde.de",
  "status": "ok",
  "shippingPageUrl": "https://www.bergfreunde.de/lieferung-und-zahlung/",
  "returnsPageUrl": "https://www.bergfreunde.de/rueckgabe/",
  "withdrawalPageUrl": "https://www.bergfreunde.de/widerruf/",
  "freeShippingThreshold": 99,
  "currency": "EUR",
  "shippingCostMin": 3.95,
  "shippingCostMax": 9.95,
  "deliveryDaysMin": 2,
  "deliveryDaysMax": 4,
  "carriers": ["DHL"],
  "expressAvailable": null,
  "returnWindowDays": 100,
  "freeReturns": true,
  "returnCost": 0,
  "returnCostCurrency": "EUR",
  "withdrawalPeriodDays": 14,
  "shippingCostsByZone": [
    {"zone": "Germany, France", "method": "standard", "amount": 3.95, "currency": "EUR", "evidence": "Germany, France: 3,95 €"},
    {"zone": "Austria", "method": "standard", "amount": 4.45, "currency": "EUR", "evidence": "Austria: 4,45 €"}
  ],
  "returnCostsByZone": [
    {"zone": "Germany, Austria", "amount": 0, "currency": "EUR", "evidence": "Germany, Austria: 0,00 €"},
    {"zone": "France", "amount": 2.95, "currency": "EUR", "evidence": "France: 2,95 €"}
  ],
  "jsonLdShipping": null,
  "jsonLdReturnPolicy": [
    {"returnPolicyCategory": "MerchantReturnFiniteReturnWindow", "merchantReturnDays": 100, "returnFees": "FreeReturn", "returnMethod": "ReturnByMail", "applicableCountry": ["DE"]}
  ],
  "confidence": {
    "freeShippingThreshold": "found", "shippingCostMin": "found", "deliveryDaysMax": "found",
    "returnWindowDays": "found", "freeReturns": "found", "withdrawalPeriodDays": "found", "expressAvailable": "missing"
  },
  "evidence": {
    "freeShippingThreshold": "In Deutschland liefern wir bereits ab 99 EUR Bestellwert versandkostenfrei!",
    "deliveryDaysMin": "So dauert es durchschnittlich für Lieferungen nach Deutschland 2-4 Werktage, bis das Paket bei Dir ankommt.",
    "returnWindowDays": "Dein gesetzliches Widerrufsrecht bleibt von den nachfolgenden Regelungen zum 100 Tage-Rückgaberecht unberührt.",
    "withdrawalPeriodDays": "Mit diesem Formular kannst Du Deinen Vertrag innerhalb der gesetzlich geltenden Frist von 14 Tagen widerrufen."
  },
  "language": "de",
  "pagesFetched": 6
}
```

Other rows from the same run:

- **manufactum.de**: free shipping from 250 €, otherwise 6.95 €, delivery in 2–3 working days, DHL, Deutsche Post or freight forwarder, free returns within 14 days
- **allbirds.com**: free ground shipping over $100, 30-day return policy, `freeReturns: false` (evidence: *"Customers are responsible for return shipping charges."*)

Other fields: `platform` (`shopify` when detected), `jsonLdSourceUrls`, `inputUrl`, `skippedByRobots`, `checkedAt`, `error`.

`status` values:

| status | meaning | charged |
|---|---|---|
| `ok` | at least one shipping, returns or withdrawal page was found and parsed | yes |
| `no_policy_pages` | the site is readable, but no policy page was found | no |
| `policy_pages_not_reachable` | the site blocks non-browser requests (bot-protection challenge, HTTP 403, tarpit/timeout) or is a JavaScript-only app shell; `error` says which | no |
| `blocked_by_robots` | robots.txt disallows the home page | no |
| `error` | other failures (DNS, invalid URL, HTTP 404/5xx) | no |

Each `shippingCostsByZone` entry has `method` (`standard`, `express` or `bulky`) and `plausible` (false for amounts above 50).

### Pricing

Pay per event: **$0.003 per shop** ($3 per 1,000 shops). You are charged only when at least one shipping, returns or withdrawal page was found and parsed. Unreachable shops, shops without policy pages and shops blocked by robots.txt are free.

### Use via API, n8n or MCP

**API (synchronous, returns the rows):**

```bash
curl -X POST "https://api.apify.com/v2/acts/fast_data_asap~shop-shipping-returns-extractor/run-sync-get-dataset-items?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"shops":["www.bergfreunde.de","www.allbirds.com"]}'
```

**n8n / Make / Zapier:** use the Apify node or app, choose *Run Actor* with `fast_data_asap/shop-shipping-returns-extractor`, pass `shops`, then read the dataset items.

**MCP (Claude, Cursor, other AI agents):** add the server `https://mcp.apify.com?tools=fast_data_asap/shop-shipping-returns-extractor`. Your agent can then look up any shop's shipping and returns terms on its own.

### Limits and notes

- The actor reads only public policy pages and collects no personal data.
- Values are extracted with heuristics. Check `confidence` and `evidence`. `inferred` means a weaker signal, such as a free-shipping banner on the home page, JSON-LD only, or the EU statutory 14 days when a withdrawal page exists but states no number.
- Shops that serve different policies per region (for example gymshark.com) list many zones. The min/max values are then taken in the main currency of the shipping page, and the full list is in `shippingCostsByZone`.
- Shops that need JavaScript to show their policy text, or that block plain HTTP requests (for example amazon.de, zalando.de, flaconi.de, hornbach.de or dm.de), come back with `status: "policy_pages_not_reachable"` and are free. Using a residential proxy in `proxyConfiguration` can help in some cases.

# Actor input Schema

## `shops` (type: `array`):

Online shops to analyse, e.g. allbirds.com or https://www.bergfreunde.de. The actor finds the shipping, returns and withdrawal pages itself (footer/navigation links, Shopify /policies/ pages, sitemap).

## `language` (type: `string`):

Language of the shop pages. 'auto' detects it from the page. English and German patterns are always applied.

## `checkProductPage` (type: `boolean`):

Also fetch one product page linked from the home page to read shippingDetails and hasMerchantReturnPolicy structured data.

## `respectRobotsTxt` (type: `boolean`):

Skip pages that the shop's robots.txt disallows.

## `maxConcurrency` (type: `integer`):

How many shops are processed in parallel.

## `proxyConfiguration` (type: `object`):

Optional. Shops are fetched directly by default. Enable Apify Proxy if a shop rate-limits data-center traffic.

## Actor input object example

```json
{
  "shops": [
    "www.allbirds.com",
    "www.bergfreunde.de",
    "www.manufactum.de"
  ],
  "language": "auto",
  "checkProductPage": true,
  "respectRobotsTxt": true,
  "maxConcurrency": 5,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "shops": [
        "www.allbirds.com",
        "www.bergfreunde.de",
        "www.manufactum.de"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("fast_data_asap/shop-shipping-returns-extractor").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "shops": [
        "www.allbirds.com",
        "www.bergfreunde.de",
        "www.manufactum.de",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("fast_data_asap/shop-shipping-returns-extractor").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "shops": [
    "www.allbirds.com",
    "www.bergfreunde.de",
    "www.manufactum.de"
  ]
}' |
apify call fast_data_asap/shop-shipping-returns-extractor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,fast_data_asap/shop-shipping-returns-extractor"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/Y5gq4TsyJehVTBdYe/builds/13TmVyII0uyqRqh5W/openapi.json