# Inventory Export Cleaner

> Clean and normalize messy Shopify CSV exports for products, orders, or inventory by fixing encoding issues, whitespace problems, sparse-row formatting, and common data-quality problems before analysis or re-import. Use when an agent needs Shopify CSV cleanup, forward-fill normalization, encoding repair, spreadsheet damage cleanup, or preparation of messy CSV exports for downstream inventory work.

- Skill: `useretrace/inventory-export-cleaner` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add useretrace/inventory-export-cleaner`
- Raw SKILL.md: https://api.skillmd.com/api/skills/useretrace/inventory-export-cleaner/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: useretrace (https://skillmd.com/u/useretrace)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/useretrace/inventory-export-cleaner

---


# Shopify Inventory Export Cleaner

Clean messy Shopify CSV exports — fix encoding issues, forward-fill sparse product/order fields, strip whitespace, and flag data quality problems. Outputs a drop-in replacement CSV and a markdown audit trail.

## When to use this skill

Activate when the user:
- Has a Shopify CSV export that needs cleaning before analysis
- Mentions encoding problems, blank fields, or messy data in a Shopify export
- Asks about forward-filling, deduplication, or normalizing Shopify exports
- Mentions Excel corrupting their Shopify CSV

## Prerequisites

Before running, ensure Python 3.9+ is available and install dependencies:

```bash
pip install -r "$SKILL_DIR/scripts/requirements.txt"
```

Resolve `SKILL_DIR` to the installed skill root first. If `pip install` fails due to permissions, try `pip install --user -r "$SKILL_DIR/scripts/requirements.txt"` or use a virtual environment.

## Input

Any of these three Shopify export formats (auto-detected by column signatures):

| Type | Export path | Key columns |
|------|------------|-------------|
| **Products CSV** | Admin → Products → Export | `Handle`, `Title`, `Variant SKU`, `Variant Price` |
| **Orders CSV** | Admin → Orders → Export | `Name`, `Email`, `Lineitem sku`, `Lineitem quantity`, `Created at` |
| **Inventory CSV** | Admin → Products → Inventory | `Handle`, `Title`, `SKU`, `On hand` |

## Running the cleaner

Resolve the installed skill root first. The exact path depends on where the skill was installed in the current environment.

```bash
SKILL_DIR="<resolved-installed-skill-dir>"

python "$SKILL_DIR/scripts/inventory_export_cleaner.py" \
  --input products_export.csv \
  --output-dir ./cleaned
```

### All flags

| Flag | Default | Description |
|------|---------|-------------|
| `--input` | *(required)* | Path to the Shopify CSV export to clean |
| `--output-dir` | `./cleaned` | Output directory |
| `--type` | `auto` | File type: `products`, `orders`, `inventory`, `auto` |
| `--no-forward-fill` | off | Skip forward-fill of product/order fields |
| `--strict` | off | Exit non-zero on `errors` by default; accepts `warnings` or `all` |
| `--utc-dates` | off | Normalize dates to UTC (default: preserve original timezone) |
| `--dry-run` | off | Preview changes without writing output files |

### Examples

Clean a products export:
```bash
python "$SKILL_DIR/scripts/inventory_export_cleaner.py" \
  --input products_export.csv \
  --output-dir ./cleaned
```

Clean an orders export without forward-fill:
```bash
python "$SKILL_DIR/scripts/inventory_export_cleaner.py" \
  --input orders_export.csv \
  --no-forward-fill
```

Strict mode (fail CI if issues detected):
```bash
python "$SKILL_DIR/scripts/inventory_export_cleaner.py" \
  --input products_export.csv \
  --strict
```

Preview changes without writing files:
```bash
python "$SKILL_DIR/scripts/inventory_export_cleaner.py" \
  --input products_export.csv \
  --dry-run
```

Convert order timestamps to UTC explicitly:
```bash
python "$SKILL_DIR/scripts/inventory_export_cleaner.py" \
  --input orders_export.csv \
  --utc-dates
```

## Output

Two files on normal runs:

1. **`{original_name}_cleaned.csv`** — Drop-in replacement with same column structure. Encoding fixed, whitespace stripped, empty rows removed, product/order fields forward-filled, and location names normalized. Orders keep their original timezone unless `--utc-dates` is used.

2. **`{original_name}_audit.md`** — Markdown audit listing every change applied and every issue flagged. Human-readable, version-controllable.

With `--dry-run`, the cleaner prints the summary and full audit preview but does not write either file.

## What gets auto-fixed vs. flagged

**Auto-fixed** (safe, deterministic transformations):
- UTF-8 BOM removal and LF line ending normalization
- Smart quote normalization (curly → straight)
- Header and value whitespace stripping
- Empty row removal
- Forward-fill of product/order-level fields (unless `--no-forward-fill`)
- Date normalization to ISO 8601 UTC when `--utc-dates` is used (orders)
- Location name normalization (inventory)
- Transparent non-UTF-8 decoding (`cp1252` / `latin-1`) with UTF-8 output

**Flagged only** (requires merchant judgment):
- Blank SKUs, duplicate SKUs
- Missing cost price, zero price variants
- Inventory tracking inconsistencies
- Blank lineitem SKUs (often intentional)
- Negative inventory (oversold)
- Non-numeric values in numeric columns
- Non-contiguous Handle groups (likely Excel sorting)
- Unparseable order dates

## Presenting results

After the script runs:
1. **Ask about intent first** — "Are you cleaning this for analysis (ABC, Dead Stock, etc.) or for re-import into Shopify?"
2. For **analysis**, confirm the default forward-fill is correct and the cleaned file is ready for the user’s next step.
3. For **Shopify re-import**, recommend `--no-forward-fill` to preserve Shopify's sparse variant format. Note that dates stay in the original timezone by default; use `--utc-dates` only when explicit UTC normalization is needed.
4. Lead with the **change count** — how many things were fixed automatically.
5. Highlight any **flagged issues** that need merchant attention, especially blank SKUs and duplicate SKUs.
6. If flags include non-contiguous Handle groups, warn: "Your file appears to have been sorted in Excel — the cleaning is correct, but check for other unintended modifications."
7. Point to the audit report for the full change log.
8. Reference `reference.md` for background on why Shopify exports are messy.

## Multi-file workflows

This cleaner processes one file at a time. If the user has multiple Shopify exports, clean each file separately and keep the resulting files clearly named.

If the user plans to do more analysis afterward, offer to clean the additional exports they already have available, but do not assume any other skill is required.

## Edge cases

- **Already-clean file**: Reports zero changes, still writes output files
- **Single-variant products**: Forward-fill has no effect (only one row per handle)
- **All variants missing SKU**: Flags all of them — the merchant needs to add SKUs in Shopify admin
- **Non-Shopify CSV**: Auto-detection fails; use `--type` to force, or the script exits with a clear error
- **Excel-saved CSV with BOM**: Handled automatically — this is the most common encoding issue
- **`--no-forward-fill` for analysis workflows**: Variant rows will keep blank product titles. Many downstream analyses will still be numerically correct, but outputs may be less readable. For analysis use, prefer the default (forward-fill enabled).