Shopify-Import-CSV vor dem Hochladen prüfen – ohne Risiko für Ihren Shop

Ein falsch formatierter oder manuell bearbeiteter CSV-Export kann Shopify-Importvorgänge schwerwiegend stören. Statt erst nachträglich zu reagieren, wenn die falsche Variante dem falschen Produkt zugeordnet wurde oder halbe Produktzeilen verschwunden sind, hilft ein neues Tool dabei, potenzielle Probleme vor dem Hochladen zu erkennen und zu beheben. Das Programm läuft lokal auf Ihrem Rechner, benötigt keine API-Zugriffe zu Ihrem Shop und gibt klare Rückmeldungen – ohne dass sensible Daten das Gerät verlassen.

Warum Shopify-Importe scheitern – und die Fehlermeldungen wenig helfen

Shopifys Produkt-Import über CSV funktioniert in zwei Schritten: Zuerst wird die Datei validiert, dann werden die Inhalte verarbeitet. Doch selbst wenn die Datei den Upload-Dialog ohne Fehlermeldung passiert, kann der eigentliche Import fehlschlagen. Die häufigsten Ursachen sind:

• Unsichtbare Zeichen am Dateianfang: Tabellenkalkulationen wie Excel oder Google Sheets fügen manchmal einen UTF-8-BOM (Byte Order Mark) ein. Dieser führt dazu, dass Shopify die erste Spaltenüberschrift (z. B. Title) nicht korrekt erkennt.

• Abweichende oder veraltete Spaltennamen: Kleine Unterschiede wie title statt Title oder Handle statt URL handle können dazu führen, dass Shopify die Spalte ignoriert oder zurückweist.

• Fehlende Eltern-Handles bei Varianten: Eine Variante ohne zugehörige Produkt-Handle kann nicht zugeordnet werden, was zu Fehlern oder falschen Zuordnungen führt.

• Doppelte Handles in der Produktliste: Zwei Produktzeilen mit identischem Handle führen dazu, dass Shopify eines der Produkte überschreibt oder beide zusammenführt – ohne dies anzuzeigen.

• Kleinere, aber folgenreiche Datenfehler: Negative Preise, compare-at-Preise, die niedriger sind als der Verkaufspreis, oder alt-Texte für Bilder ohne verknüpfte Bild-URLs können den Import zwar abschließen, aber zu sichtbaren Fehlern im Shop führen.

Diese Probleme entstehen vor allem, wenn Menschen die CSV-Datei manuell in Tabellenkalkulationen bearbeiten. Automatisierte Tools wie Shopifys eigene Exportfunktion oder Drittanbieter-Apps erstellen zwar korrekte Formate – doch sobald ein Mensch eingreift, steigt das Risiko für Fehler.

Ein praktisches Beispiel: So funktioniert die Überprüfung

Stellen Sie sich vor, Sie haben eine Produktliste exportiert, in Excel bearbeitet und möchten diese nun hochladen. Statt die Datei direkt in Shopify zu importieren, nutzen Sie das CSV-Preflight-Tool, um sie vorab zu prüfen. Der Befehl

csv-preflight check produktliste.csv --out-dir ./ergebnis --lang de

erzeugt anschließend drei Ausgabedateien:

• `fixed_products.csv`: Eine bereinigte Version Ihrer ursprünglichen Datei, in der nur mechanische Fehler behoben wurden. Diese Datei können Sie direkt in Shopify importieren.

• `errors.csv`: Eine maschinell lesbare Liste aller gefundenen Probleme mit Angaben zu Zeile, Regel, Schweregrad und vorgeschlagener Lösung.

• `report.md`: Ein menschlich lesbarer Bericht, der Ihnen in weniger als einer Minute einen Überblick über alle kritischen und warnenden Hinweise gibt.

Der Prozess läuft lokal auf Ihrem Rechner ab – es werden keine Daten an externe Server gesendet, und es ist kein Login oder API-Zugriff auf Ihren Shop erforderlich.

Beispiel eines echten Berichts

Angenommen, Ihre produktliste.csv enthält mehrere der oben genannten Probleme. Der generierte report.md könnte dann wie folgt aussehen:

# Shopify CSV Preflight Report

## Zusammenfassung
- Gescannte Zeilen: 4
- Produktgruppen: 3
- Kritische Fehler: 6
- Warnungen: 8
- Automatisch behoben: 2

## Kritische Fehler (vor dem Import beheben)
- [F01a] Datei: UTF-8-BOM am Dateianfang erkannt.
- [F03a] Datei: Spaltenname `title` weicht nur durch Kleinschreibung von einem Standardnamen ab.
- [R02] Zeile 2: Varianten-/Bildzeile fehlt das Eltern-Handle.
- [R03] Zeile 1: Zwei Produktstartzeilen teilen sich das Handle `aurora-hoodie` (Zeilen 1 und 3).
- [R11] Zeile 4: `alt`-Text vorhanden, aber Bild-URL fehlt.

## Warnungen (empfohlen zur Überprüfung)
- [R07] Zeile 4: `inventory_policy` enthält ungültigen Wert `maybe` (muss `deny` oder `continue` sein).
- [R08] Zeile 4: Bestandsverfolgung auf `shopify` gesetzt, aber Bestandsmenge fehlt oder ist keine Zahl.
- [R10] Zeile 1: `compare-at`-Preis (39,00 €) niedriger als Verkaufspreis (48,00 €).
- [R10] Zeile 4: Verkaufspreis negativ (-18,00 €).

## Automatisch behoben
- [F01a] UTF-8-BOM entfernt.
- [F03a] Spaltenname normalisiert (`title` → `Title`).

## Nicht geprüft
Folgende Aspekte werden **nicht** überprüft, da sie eine Verbindung zu Ihrem Shop erfordern würden:
- Erreichbarkeit von Bild-URLs
- Überschreiben bestehender Handles
- Validierung von Metafeld-Verknüpfungen
- Konsistenz von Optionen mit bestehenden Produkten

Das Tool gibt zudem einen Exit-Code ungleich Null zurück, wenn kritische Fehler gefunden wurden. Dies ermöglicht es, den Befehl in Skripte zu integrieren und Importe automatisch zu stoppen, falls Probleme erkannt werden.

Was automatisch korrigiert wird – und was nicht

Das Tool behebt ausschließlich mechanische und eindeutige Fehler, die keine Interpretation erfordern:

• Entfernung des UTF-8-BOM
• Normalisierung von Spaltennamen (z. B. title → Title)

Alles andere – wie fehlende Eltern-Handles, doppelte Handles oder negative Preise – wird nur gemeldet, aber nicht automatisch geändert. So behalten Sie die volle Kontrolle über Ihre Produktdaten.

Für wen lohnt sich das Tool?

Das CSV-Preflight-Tool richtet sich an alle, die regelmäßig Produktdaten in Shopify importieren und dabei auf Nummer sicher gehen möchten:

• Einzelhändler, die vor einem Launch oder einer Aktion ihre Produktliste aktualisieren müssen.

• Agenturen oder Freelancer, die im Auftrag von Kunden Produktkataloge migrieren und eine saubere Übergabe wünschen.

• Jeder, der schon einmal erlebt hat, wie ein scheinbar erfolgreicher Import zu fehlerhaften oder fehlenden Produkten führte – und nie wieder raten möchte.

Wichtig: Das Tool ist ausschließlich für Produkt-CSVs konzipiert. Es erkennt Dateien mit personenbezogenen Daten (z. B. Bestell- oder Kundendaten) und lehnt diese ab, um die Sicherheit Ihrer Kundendaten zu gewährleisten.

Vergleich mit bestehenden Lösungen

Vollständige Migrations-Tools wie Matrixify oder Ablestar bieten umfangreiche Funktionen für komplexe Importe. Doch viele Nutzer kritisieren diese Lösungen regelmäßig für drei Hauptprobleme:

• Hohe Kosten für kleine, einmalige Importe.
• Langsame Verarbeitung, besonders bei großen Katalogen.
• Steile Lernkurve durch komplexe Benutzeroberflächen und viele Optionen.

Das CSV-Preflight-Tool setzt genau hier an: Es ist einfach, schnell und fokussiert auf einen einzigen Zweck – die Vorabprüfung Ihrer CSV-Datei, bevor diese Ihr Shop betritt. Ohne Anmeldung, ohne API-Zugriff und ohne dass Ihre Daten das Gerät verlassen.

So starten Sie mit dem Tool

Das Tool ist kostenlos und open source auf GitHub verfügbar. Sie können es direkt ausprobieren:

1. Installation:

   uv tool install csv-preflight

1. Überprüfung Ihrer CSV-Datei:

   csv-preflight check Ihre-produkte.csv --out-dir ./auswertung

1. Auswertung der Ergebnisse:

• Prüfen Sie errors.csv und report.md.
• Nutzen Sie fixed_products.csv für den Import in Shopify.

Falls Sie bereits einmal von einem stillen, fehlerhaften Import betroffen waren, teilen Sie Ihre Erfahrungen gerne als Kommentar oder Issue auf GitHub. Der Entwickler prüft aktuell, ob das Tool zu einer kostenpflichtigen Einmal- oder Shopify-App ausgebaut werden soll – und sucht dafür konkrete Nutzerfeedback.

Shopify-Importe müssen kein Glücksspiel sein. Mit dem richtigen Werkzeug im Voraus können Sie sicherstellen, dass Ihre Produktdaten korrekt und vollständig in den Shop gelangen – ohne böse Überraschungen.