# Merchant Feed Doctor — Validate & Auto-Fix Shopping Feeds (`vanborn_labs/merchant-feed-doctor`) Actor

Validate and auto-fix Google Merchant Center product feeds from Shopify, WooCommerce or a native CSV/TSV. Finds price, GTIN, title, availability and identifier issues, applies only safe deterministic fixes, and returns a ready-to-upload TSV plus an HTML report. No Google API, no invented GTINs.

- **URL**: https://apify.com/vanborn_labs/merchant-feed-doctor.md
- **Developed by:** [Van Born Labs](https://apify.com/vanborn_labs) (community)
- **Categories:** E-commerce, SEO tools, Automation
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $10.00 / 1,000 product checkeds

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

## Merchant Feed Doctor — Validate & Auto-Fix Google Shopping Feeds

**Offline validator and auto-fixer for Google Merchant Center product feeds.** Paste a Shopify export, a WooCommerce export, or a native Google CSV/TSV. Get a corrected feed, a scored report, and a fix log — no Google API, no invented data.

Stop losing impressions and getting disapproved products. Merchant Feed Doctor inspects Shopify, WooCommerce, or native Google Shopping feeds, reports every issue with a clear code and severity, and applies only safe, deterministic fixes — all without any network calls.

### The problem

Google Merchant Center rejects or demotes products for dozens of silent reasons:

- Missing required attributes (id, title, description, link, image_link, price, availability, brand/identifier, condition)
- Titles that are too long, ALL CAPS, or stuffed with “free shipping”, “sale”, “!!!”
- Prices not in `19.99 USD` format, zero/negative prices, sale_price ≥ price
- Invalid GTINs (wrong length or check digit)
- Non-https image links, spaces in URLs
- Clothing items missing color / size / gender / age_group or item_group_id (color or size alone does not make a product apparel)
- Duplicate IDs, ragged CSV rows, Windows-1252 encoding surprises

Fixing these by hand is slow and error-prone. This tool does it in seconds, offline, with a full audit trail.

### What it checks

| Rule | Severity | Auto-fix |
|------|----------|----------|
| Required fields missing | error | — |
| Title > 150 chars, ALL CAPS, promotional text, heavy duplicates | error/warning | truncate at word boundary, sentence-case, strip promo phrases |
| Description > 5000 chars or contains HTML | error/warning | strip HTML |
| Price format, currency mismatch, zero/negative, sale_price ≥ price | error/warning | reformat to `12.50 USD` (understands `1.299,99 €`, `1,299.00`, `£12`); drop a sale_price that is not lower |
| Availability not in {in_stock, out_of_stock, preorder, backorder} | error | normalize common variants (“in stock”, “yes”, “InStock”…) |
| GTIN length 8/12/13/14 + GS1 check digit, spreadsheet damage (`8.6E+11`, `'0123…`) | error | strip apostrophe/spaces, restore leading zeros only if the check digit proves it; never invents a GTIN |
| shipping_weight without unit | warning | Shopify grams → `680 g`, Woo kg → `0.2 kg` |
| Ragged CSV rows | warning | — |
| link / image_link not absolute https or contains spaces | error/warning | http→https, URL-encode spaces |
| Duplicate ids | error | append `-2`, `-3`… |
| Variants missing item_group_id | warning | fill from Shopify Handle |
| Clothing/footwear missing color/size/gender/age_group | warning | — (not flagged on bedding, cosmetics, or other non-apparel just because they have Color/Size) |
| google_product_category not numeric ID or path | warning | — |
| condition values | warning | normalize |

Every fix is logged with before/after values.

### Use cases

- **Clean a Shopify or WooCommerce export** before the first Merchant Center upload, or after a wave of disapprovals.
- **Fix EU and US prices** that spreadsheets have reformatted (`1.299,99 €`, `1,299.00`, `$19.9`) into the `19.99 USD` shape Google requires.
- **Agency QA**: run a client's feed, send them the HTML report and the fixed TSV, and charge per catalog instead of a monthly feed platform.
- **Pipelines**: hook the dataset, `fixed_feed.tsv` and `report.json` into Make, Zapier, n8n or the Apify API.

### Input

CSV or TSV. Auto-detects:

- Delimiter (comma, tab, semicolon)
- Encoding (UTF-8, UTF-8 BOM, Windows-1252)
- Source format (Shopify export, WooCommerce export, or native Google columns)

Real export layouts are handled:

- **Shopify product CSV**: variant rows inherit title/description/vendor/options from the first row of their Handle; image-only rows become `additional_image_link`; `Variant Compare At Price` is treated as the regular price and `Variant Price` as the sale price; availability is derived from inventory qty/policy; draft/archived/unpublished products and gift cards are skipped (listed in the report); `Google Shopping / *` columns are mapped.
- **WooCommerce exporter**: `variable` parent rows are skipped and their variations inherit description/brand/images and get `item_group_id`; `Attribute N` columns become color/size; the `Images` list is split; `In stock?` + `Backorders allowed?` map to availability; `GTIN, UPC, EAN, or ISBN` and `Brands` are mapped.
- Shopify and WooCommerce exports contain no product URLs: set `store_url` and links are built as `/products/<handle>` (Shopify) or `/?p=<id>` (WooCommerce).

Mapped attributes: `id`, `title`, `description`, `link`, `image_link`, `price`, `sale_price`, `availability`, `brand`, `gtin`, `mpn`, `condition`, `google_product_category`, `product_type`, `item_group_id`, `color`, `size`, `gender`, `age_group`, `shipping_weight`.

#### Options

- `target_country` (default `US`)
- `currency` (default `USD`)
- `auto_fix` (default `true`)
- `title_max` (default `150`)
- `strict` (default `false`)
- `store_url` (default empty) — shop base URL used to build product links for Shopify/WooCommerce exports

### Output

- `fixed_feed.tsv` — cleaned feed in Google Merchant format
- `report.json` — summary counts, issues found in the original feed, `remaining_issues` left after fixes, fixes list, skipped rows, health score before and after fixes (0–100)
- `report.html` — single-file dark report (charcoal background, white text, brand lime accent `#B8FF2C` with dark text on lime fills), sortable issues table, no external assets

#### Example report.json (excerpt)

```json
{
  "summary": {
    "product_count": 62,
    "error_count": 211,
    "warning_count": 333,
    "fix_count": 148,
    "health_score": 50,
    "health_score_after_fixes": 90,
    "remaining_error_count": 0,
    "source": "shopify",
    "encoding": "utf-8"
  },
  "issues": [
    {
      "code": "missing_link",
      "severity": "error",
      "message": "Required field 'link' is missing or empty",
      "row": 2,
      "field": "link"
    }
  ],
  "fixes": [
    {
      "row": 2,
      "field": "price",
      "before": "29.99",
      "after": "29.99 USD",
      "reason": "reformat price to 'X.XX CURRENCY'"
    }
  ]
}
```

### Usage

#### CLI (Python 3.11+)

```bash
python -m feed_doctor feed.csv --out out/
python -m feed_doctor feed.tsv --out out/ --currency EUR --strict
python -m feed_doctor feed.csv --no-fix --json
```

#### As a library

```python
from feed_doctor import process_feed
fixed, report, html = process_feed(open("feed.csv", "rb").read())
```

#### Apify Actor

Input schema accepts `feed_url` **or** `feed_text` plus the options above.

The actor:

- Pushes one dataset item per product (`issues_found`, `remaining_issues`, `fixes`, `status` ok/warning/error) plus a summary item
- Saves `fixed_feed.tsv`, `report.html`, and `report.json` to the key-value store
- Charges one `product-checked` event per product item (`Actor.push_data(..., charged_event_name=...)`) and stops cleanly at the user's max-charge limit

### FAQ

**Does it call any external APIs?**\
No. Everything runs offline. GTIN check digits are computed locally. No Google API calls.

**Will it invent GTINs or product data?**\
No. Invalid GTINs are flagged only. Fixes are limited to whitespace, HTML stripping, normalization, URL cleanup, title cleanup, price formatting, and ID deduplication.

**What encodings are supported?**\
UTF-8, UTF-8 with BOM, and Windows-1252 (common in Shopify/Woo exports). Falls back to latin-1.

**How is the health score calculated?**\
0–100 ≈ the share of products Merchant Center would accept. A product with any error counts 0, a product with only warnings counts 1 − 0.1 per warning (minimum 0.5), a clean product counts 1. The report shows the score of your original feed and of the fixed feed.

**Can I use it on a private feed?**\
Yes. Paste the raw CSV/TSV into `feed_text` or run the CLI locally. No data leaves your machine.

**Shopify / WooCommerce column mapping?**\
Yes. Common headers (`Handle`, `Variant SKU`, `Variant Price`, `Body (HTML)`, `Regular price`, `Stock status`, etc.) are mapped automatically to Google attributes. Color/Size options become `color`/`size`.

**Does it treat every product with a Color or Size option as apparel?**\
No. Gender and age_group warnings apply to clothing, footwear and wearable accessories (from the title, product type or Google category). Bedding, home goods and cosmetics are not flagged just because they have color or size variants, including makeup shade names like “Girl” or “Cardigan”.

**Does a clean score mean Google will approve the feed?**\
No. This is a deterministic preflight of the file itself. Merchant Center also looks at your landing pages, account status, policies and additional attributes this tool cannot see.

### Pricing

Pay-per-event pricing is live on the Apify Store:

- **$0.25 actor start** (`apify-actor-start`) per run at the default 512 MB of memory. Apify bills one start event per GB of memory, minimum one, so a default run is a single $0.25 start.
- **$0.01 per `product-checked`** — $10 per 1,000 products checked

A 1,000-product catalog costs about **$10.25** per run; 5,000 products cost $50.25. Skipped rows (Shopify drafts, gift cards, WooCommerce parent rows) are not charged. If a run hits the user's max-charge limit, the actor stops pushing products and says so in the summary.

The actor charges via `Actor.push_data(..., charged_event_name="product-checked")`.

### Disclaimer

Not affiliated with or endorsed by Google, Shopify, or WooCommerce. Google Merchant Center rules change; this tool checks the most common feed specification rules and does not guarantee approval.

### License

MIT

### Van Born Labs

Built for merchants and agencies who need reliable, auditable Google Shopping feeds.

More from Van Born Labs: https://arkadiuszvanborn.com/labs/merchant-feed-doctor

# Changelog

This Actor's version history is a separate document: https://apify.com/vanborn_labs/merchant-feed-doctor/changelog.md

# Actor input Schema

## `feed_url` (type: `string`):

Public URL of a CSV or TSV product feed (Shopify, WooCommerce, or Google). Used if feed_text is empty.

## `feed_text` (type: `string`):

Raw CSV/TSV content. Takes precedence over feed_url. Ideal for offline / private feeds.

## `store_url` (type: `string`):

Your shop's base URL, e.g. https://shop.example.com. Shopify and WooCommerce product exports contain no product URLs; with this set, links are built as /products/<handle> (Shopify) or /?p=<id> (WooCommerce).

## `target_country` (type: `string`):

Target country code (default: US)

## `currency` (type: `string`):

Expected currency code (default: USD)

## `auto_fix` (type: `boolean`):

Apply safe deterministic fixes

## `title_max` (type: `integer`):

Maximum title length (default 150)

## `strict` (type: `boolean`):

Treat more issues as errors

## Actor input object example

```json
{
  "feed_text": "id,title,description,link,image_link,price,availability,brand,gtin,condition\nSKU-1,ORGANIC COTTON TEE - FREE SHIPPING!!!,<p>Soft tee</p>,http://shop.example.com/tee,https://shop.example.com/tee.jpg,19.9,In Stock,Acme,036000291452,New\n",
  "target_country": "US",
  "currency": "USD",
  "auto_fix": true,
  "title_max": 150,
  "strict": false
}
```

# Actor output Schema

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

One dataset item per product checked (issues found, remaining issues, fixes, status) plus a run summary item. The Products (overview) view is selected by default.

## `fixedFeed` (type: `string`):

Ready-to-upload Google Merchant Center TSV, stored as fixed_feed.tsv.

## `reportJson` (type: `string`):

Full audit report with summary counts, issues, remaining issues, fixes and skipped rows, stored as report.json.

## `reportHtml` (type: `string`):

Single-file HTML report (charcoal + lime accent), stored as report.html.

# 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 = {
    "feed_text": `id,title,description,link,image_link,price,availability,brand,gtin,condition
SKU-1,ORGANIC COTTON TEE - FREE SHIPPING!!!,<p>Soft tee</p>,http://shop.example.com/tee,https://shop.example.com/tee.jpg,19.9,In Stock,Acme,036000291452,New`
};

// Run the Actor and wait for it to finish
const run = await client.actor("vanborn_labs/merchant-feed-doctor").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 = { "feed_text": """id,title,description,link,image_link,price,availability,brand,gtin,condition
SKU-1,ORGANIC COTTON TEE - FREE SHIPPING!!!,<p>Soft tee</p>,http://shop.example.com/tee,https://shop.example.com/tee.jpg,19.9,In Stock,Acme,036000291452,New
""" }

# Run the Actor and wait for it to finish
run = client.actor("vanborn_labs/merchant-feed-doctor").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 '{
  "feed_text": "id,title,description,link,image_link,price,availability,brand,gtin,condition\\nSKU-1,ORGANIC COTTON TEE - FREE SHIPPING!!!,<p>Soft tee</p>,http://shop.example.com/tee,https://shop.example.com/tee.jpg,19.9,In Stock,Acme,036000291452,New\\n"
}' |
apify call vanborn_labs/merchant-feed-doctor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,vanborn_labs/merchant-feed-doctor"
        }
    }
}
```

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/B83LJfQhzNsNiChiw/builds/5i8YHHOeZKhxxoSjq/openapi.json
