Appearance
Shopify konfigurieren
Diese Seite beschreibt die Shopify-Einstellungen einer Verbindung. Den allgemeinen Ablauf finden Sie unter Verbindungen.
Die Shopify-Konfiguration verbindet ReadySync mit Ihrem Shopify-Shop über die Admin GraphQL API. Produkte, Varianten, Bestand, Bilder, Kollektionen und Bestellungen laufen über dasselbe Token.
Voraussetzungen
- Shopify-Shop (Admin-Zugriff)
- Eine Custom App im Shopify-Admin mit Admin-API-Zugriffstoken
- Die unten genannten API-Berechtigungen (Scopes)
Anmeldung: Token oder Client-ID und Secret
ReadySync kennt zwei Wege. Neue Shops können unter „Apps entwickeln“ keine Custom App mehr anlegen; dort ist der zweite Weg der richtige.
- Admin-API-Zugriffstoken (Custom App): Das Token (
shpat_…) einer bestehenden Custom App, siehe unten. - Client-ID und Client-Secret (Dev Dashboard): Legen Sie die App im Shopify Dev Dashboard an, vergeben Sie dort die Scopes aus der Tabelle unten und installieren Sie die App im Shop. Client-ID und Secret stehen in den Einstellungen der App. ReadySync holt damit selbst ein Zugriffstoken, das 24 Stunden gilt, und erneuert es automatisch.
Gleiche Organisation
Die Anmeldung mit Client-ID und Secret funktioniert nur, wenn die App in derselben Dev-Dashboard-Organisation angelegt ist wie der Shop und dort installiert ist. Sonst meldet Shopify shop_not_permitted.
Custom App und Zugriffstoken anlegen
- Öffnen Sie im Shopify-Admin Einstellungen → Apps und Vertriebskanäle → Apps entwickeln.
- Legen Sie eine App an, z. B. „ReadySync“.
- Unter API-Berechtigungen konfigurieren mindestens diese Scopes setzen:
| Scope | Wofür |
|---|---|
read_products, write_products | Produkte, Varianten, Kollektionen |
read_inventory, write_inventory | Bestand am Lagerort |
read_locations | Lagerorte auflisten |
read_orders, write_orders | Bestellungen lesen, Tags setzen, stornieren |
read_customers | Kundennummer der Bestellung für den Bestellexport |
read_merchant_managed_fulfillment_orders, write_merchant_managed_fulfillment_orders | Fulfillment inkl. Tracking |
read_files, write_files | Bild-Upload |
- App installieren und unter API-Zugangsdaten das Admin-API-Zugriffstoken einmalig kopieren (
shpat_…).
Token nur einmal sichtbar
Shopify zeigt das Token nur einmal. Speichern Sie es direkt in ReadySync. Bei Verlust: Token rotieren und in der Verbindung ersetzen.
Konfiguration in ReadySync
Öffnen Sie die Verbindung und wechseln Sie zum Tab Shop.
| Feld | Beschreibung |
|---|---|
| Shop-Domain | z. B. mein-shop.myshopify.com. Eine volle URL wird auf die Domain gekürzt. |
| Anmeldung | Admin-API-Zugriffstoken oder Client-ID und Client-Secret, siehe oben. |
| Admin-API-Zugriffstoken | Das Token der Custom App. |
| Client-ID / Client-Secret | Aus den Einstellungen der App im Dev Dashboard. |
| API-Version | Quartalsversion, Standard 2026-04. Nur ändern, wenn Shopify das verlangt. |
| Lagerort-ID | GID oder Zahl des Lagers für Bestände, z. B. gid://shopify/Location/123456. Leer = erster aktiver Lagerort mit Online-Bestellungen. Sie können auch einen zweiten Lagerort angeben. Führt Shopify einen Artikel dort noch nicht, schaltet ReadySync ihn an diesem Lagerort frei, bevor es den Bestand setzt. |
| Bestandspolitik | Nicht ohne Bestand verkaufen (DENY) oder weiter verkaufen (CONTINUE). |
| Tags aus „Keywords“ | Ersetzen (Standard), Ergänzen oder nur Tags mit Präfix verwalten, siehe unten. |
| Tag-Präfix | Nur im Modus „Nur Tags mit Präfix verwalten“, z. B. rs:. Muss mit :, _, - oder / enden. |
| Nur bestehende Produkte aktualisieren | ReadySync legt keine neuen Produkte oder Varianten an. Artikel, deren SKU in Shopify fehlt, stehen als übersprungen im Job-Protokoll. |
Wie ReadySync bestehende Produkte findet und aktualisiert
ReadySync sucht jeden Artikel über die SKU der Variante. Auch Einzelartikel haben in Shopify eine Variante; dort steht die SKU.
- Gefunden: ReadySync aktualisiert das Produkt und die Variante. Geschrieben werden nur Felder, die im Mapping zugeordnet sind und in der Zeile einen Wert haben. Titel, Beschreibung, SEO-Angaben, Tags, Optionen und weitere Varianten bleiben unverändert, wenn sie nicht gemappt sind.
- Produkt mit mehreren Varianten: Eine Zeile ohne Variantengruppe ändert dort nur ihre eigene Variante (Preis, Streichpreis, EAN, Gewicht, Bestand). Titel, Texte und Status des Produkts bleiben, damit eine Zeile nicht alle Farben umbenennt oder deaktiviert.
- Aktiv-Status: Ist „Aktiv“ nicht gemappt oder die Spalte leer, bleibt der Status des Produkts in Shopify, wie er ist. Neue Produkte werden aktiv angelegt.
- Streichpreis: Ohne gemappten Streichpreis bleibt der Vergleichspreis in Shopify stehen. Ein gelieferter Streichpreis, der nicht über dem Verkaufspreis liegt, löscht ihn.
- Keywords → Tags: Wie ein gemapptes Keywords-Feld die Tags schreibt, stellen Sie in der Verbindung ein:
- Ersetzen (Standard): Die Keywords sind die Tag-Liste. In Shopify gepflegte Tags gehen dabei verloren.
- Ergänzen: ReadySync fügt fehlende Tags hinzu und entfernt keine.
- Nur Tags mit Präfix verwalten: ReadySync setzt das Präfix (z. B.
rs:) vor jedes Keyword und entfernt nur Tags mit diesem Präfix, die nicht mehr geliefert werden. Aktions-, Bundle- oder Steuer-Tags ohne Präfix bleiben stehen. Das Präfix muss mit:,_,-oder/enden; ohne gültiges Präfix ergänzt ReadySync nur und entfernt keine Tags. - Eine leere Keywords-Zelle lässt die Tags in allen Modi unverändert.
- Produkttyp: Ein gemapptes Feld „Produkttyp“ (z. B. aus der Warengruppe) wird zum Shopify-Produkttyp.
- Rückstände erlauben: Ein gemapptes Feld setzt die Bestandspolitik pro Variante.
1,ja,j,yes,truebedeuten weiter verkaufen,0,nein,n,no,falsebedeuten nicht ohne Bestand verkaufen. Andere Werte lassen die Variante unverändert; übersetzen Sie sie bei Bedarf mit einer Wert-Mapping-Transformation. Ohne Mapping gilt die Bestandspolitik der Verbindung für neue Varianten, bestehende bleiben, wie sie sind. - EAN: ReadySync schreibt das Feld
barcodeder Variante. Shopify ändert damit nur den ersten Barcode; weitere Barcodes der Variante bleiben erhalten. - Nicht gefunden: ReadySync legt das Produkt neu an, außer „Nur bestehende Produkte aktualisieren“ ist eingeschaltet. Optionen aus dem Mapping (z. B. „Farbe“) werden zu Produktoptionen.
Varianten
Shopify kennt kein eigenes Hauptprodukt mit Artikelnummer. Eine Variantengruppe (Mapping „Varianten-Gruppe“) ist in Shopify ein Produkt mit mehreren Varianten.
- ReadySync findet das Produkt der Gruppe über die SKU einer beliebigen Variante der Gruppe.
- Fehlt nur eine Variante, hängt ReadySync sie an das bestehende Produkt an. Ein neuer Wert einer vorhandenen Option (z. B. eine neue Farbe) wird dabei angelegt. Neue Optionen fügt ReadySync einem bestehenden Produkt nie hinzu, weil Shopify sonst allen vorhandenen Varianten einen Wert zuweist; solche Zeilen stehen im Job-Protokoll.
- Fällt eine Variante aus dem Vollexport, löscht ReadySync (bei „Löschen“) nur diese Variante. Das Produkt wird erst gelöscht oder auf Entwurf gesetzt, wenn keine seiner Varianten mehr im Export steht.
- Existiert keine Variante der Gruppe, legt ReadySync ein Produkt mit allen Varianten an. Das Muster der Hauptprodukt-Nummer (z. B.
VAR-{group}) wird bei Shopify nicht als Artikel angelegt.
Varianten an bestehende Produkte anhängen
Für eine zweite Verbindung, die zusätzliche Varianten an Produkte hängt, die schon im Shop stehen, z. B. B-Ware, Vorführ- oder Auspackgeräte neben der Neuware. Schalten Sie im Tab Produktimport unter Varianten An bestehende Produkte anhängen ein.
- Die Varianten-Gruppe ist die SKU einer Variante, die schon in Shopify existiert, meist die Artikelnummer der Neuware. ReadySync hängt jede Zeile als weitere Variante an dieses Produkt. Eine Gruppe darf aus einer einzigen Zeile bestehen.
- Die Varianten-Option muss am Produkt schon existieren, z. B. „Farbe“. Den Wert bauen Sie im Mapping, etwa mit einer Regex-Transformation
^→Auspackgerätvor der Farbe. - ReadySync legt in diesem Modus keine Produkte an und ändert keine Produktdaten: Titel, Beschreibung, Tags, Bilder und Produktmetafelder bleiben, wie die Hauptverbindung sie pflegt. Geschrieben werden nur Variantenfelder wie Preis, Streichpreis, Bestand, Bestandspolitik und Variantenmetafelder.
- Gibt es kein Produkt mit der SKU aus der Varianten-Gruppe, überspringt ReadySync die Zeile und vermerkt sie im Job-Protokoll.
Beispiel: Die Neuware hat die SKU 211970, das Auspackgerät AU_211970. Die Auspack-Verbindung mappt die SKU per Regex ^ → AU_, die Varianten-Gruppe auf die Artikelnummer und die Option „Farbe“ auf „Auspackgerät “ plus Farbe. Steht AU_211970 noch nicht im Shop, entsteht sie als neue Variante am Produkt von 211970.
Metafelder
Im Mapping-Editor legen Sie unter Metafelder beliebige Shopify-Metafelder als Ziel an, für das Produkt oder die Variante:
| Angabe | Beispiel |
|---|---|
| Besitzer | Produkt oder Variante |
| Namespace | custom |
| Key | product_data, delivery_time, blackfriday_price |
| Typ | Leer lassen, wenn das Metafeld in Shopify eine Definition hat. Sonst z. B. „Mehrzeiliger Text“ für lange HTML-Texte, „Dezimalzahl“ für Preise. |
- Leere Zellen werden nicht geschrieben; das Metafeld behält dann seinen Wert in Shopify.
- Lehnt Shopify ein Metafeld ab (z. B. falscher Typ), steht eine Warnung mit dem Namen des Metafelds im Protokoll. ReadySync schreibt die übrigen Metafelder des Artikels trotzdem, ebenso Preis, Bestand und Texte. Häufigste Ursache ist ein Typ im Mapping, der nicht zur Definition in Shopify passt; wählen Sie dann „Aus der Definition in Shopify“.
- Ein Wert, der nicht zum Typ passt (z. B. Text bei „Dezimalzahl“), wird übersprungen.
- Produkt-Metafelder einer Variantengruppe kommen aus der ersten Zeile der Gruppe. Eine Zeile ohne Variantengruppe auf einem Produkt mit mehreren Varianten schreibt nur ihre Varianten-Metafelder.
- Transformationen und Ausweichspalte stehen auch für Metafelder zur Verfügung.
Bildimport
Bilder laufen über denselben Admin-Token (Staged Upload + Produktdateien). Ein zweites Passwort wie bei WooCommerce ist nicht nötig. Ohne Bildspalte im Mapping bleibt der Produktdaten-Import davon unberührt.
Bestellexport
Shopify hat keine WooCommerce-artigen Statuswerte. ReadySync filtert und markiert so:
| Feld | Beschreibung |
|---|---|
| Zahlungsstatus | Mehrfachauswahl, Standard paid. Für Vorkasse z. B. „Bezahlt“ und „Ausstehend“ wählen, dann gehen auch unbezahlte Überweisungsbestellungen sofort ans ERP. „Alle Zahlungsstatus“ schließt auch erstattete Bestellungen ein. |
| Fulfillment-Status | Standard unfulfilled, damit bereits versendete Aufträge nicht erneut exportiert werden. |
| Tag nach Export | Standard readysync-exported. Verhindert Doppel-Export. |
Stornierte Bestellungen werden unabhängig von diesen Filtern nie exportiert.
ReadySync übernimmt die Versandkosten der Bestellung und überträgt sie ans ERP, bei HQS als Position auf dem Versandkosten-Artikel.
Status-Updates aus dem ERP
Die Statusdatei muss einen Shopify-verständlichen Wert liefern:
| Wert in der Datei | Wirkung |
|---|---|
fulfilled, shipped, completed | Fulfillment anlegen |
| Trackingnummer gesetzt | Fulfillment inkl. Sendungsnummer |
cancelled, canceled | Bestellung stornieren |
Andere Werte werden übersprungen und im Job-Protokoll vermerkt.
Liefert das ERP Statuscodes (z. B. die HQS-Status-Datei), legt die Zuordnung Statuscode → Aktion im Tab „ERP“ fest, was passiert: ausführen, Sendungsnummer an die bestehende Ausführung hängen, stornieren oder ein Tag setzen. Siehe HQS.
Shopify verschickt dabei keine Versandbestätigung, solange Kunde benachrichtigen aus ist. Das Tag setzen braucht das Recht write_orders, das der Status-Import ohnehin hat.
Mapping
Der Mapping-Katalog zeigt nur Felder, die dieser Adapter schreibt: SKU (auf der Variante), Name, Beschreibung, Vendor, Produkttyp, EAN/Barcode, Verkaufs- und Streichpreis, Bestand, Rückstände erlauben, Aktiv, Bilder, Varianten, Kollektionen, Gewicht, SEO-Titel/Beschreibung, Tags und Metafelder.
Bewusst nicht: Staffelpreise, Grundpreis, Shopware-Verkaufskanäle.