Shopify mit Warenwirtschaft verbinden: Welche Felder zusammengehören und wo der Abgleich scheitert
Eine Anbindung von Shopify an die Warenwirtschaft gelingt, wenn drei Dinge vorab feststehen: welches Shopify-Objekt welchem Wawi-Feld entspricht, welches System je Datenbereich führt und über welchen Schlüssel beide Seiten einen Datensatz wiederfinden. Die SKU der Variante eignet sich für die Erstzuordnung nur, wenn sie auf beiden Seiten vorhanden und eindeutig ist. Für den laufenden Abgleich speichern Sie die Shopify-IDs. Typische Fehlerquellen sind überschriebene Bestände, doppelt verarbeitete Bestellungen, verpasste Webhooks und unklare Schreibzuständigkeiten. Die Tabellen und die Checkliste unten bündeln diese Punkte.
Stand 18.11.2026. Grundlage: Shopify-Entwicklerdokumentation (Admin-GraphQL-API-Referenz, Bestandsverwaltung, Webhooks, Rate Limits), am 18.11.2026 abgerufen. Die genannten GraphQL-Felder und Mutationen beziehen sich auf API-Version 2026-10, sofern keine andere Version genannt ist.
- Erst klären: Brauchen Sie überhaupt eine eigene Anbindung?
- Das Shopify-Datenmodell: eine Kette aus fünf Objekten
- Zuordnungstabelle: Shopify-Feld, Wawi-Feld, Richtung, Schlüssel, Stolperstein
- Entscheidungshilfe: Wer ist Master für Bestand, Preis, Artikelstamm und Bestellung?
- Bestand schreiben: absolut, relativ und mit Wiederholungsschutz
- Bestellungen übernehmen: Webhook, Abfrage und Abgleichlauf
- Rate Limits: Wie schnell dürfen Sie abgleichen?
- Wo Abgleiche scheitern: Symptom, Ursache, Gegenmittel
- Checkliste: Rate-Limit-, Webhook- und Wiederholungsregeln
Erst klären: Brauchen Sie überhaupt eine eigene Anbindung?
Bietet Ihre Warenwirtschaft einen fertigen Shopify-Anschluss und decken Ihre Fälle sich mit dessen Umfang, ist ein Eigenbau meist nicht nötig. Ob das zutrifft, lässt sich anhand der Zuordnungstabelle weiter unten prüfen: Geht der Anschluss mit mehreren Lagerorten, Varianten, Teilerstattungen und Ihrer Preislogik um, wie Sie es brauchen? Fehlt einer dieser Punkte, lohnt sich eine individuelle Schnittstelle.
Abnahmeprüfung für einen Standardanschluss: Wählen Sie den Anschluss aus, konfigurieren Sie die Datenrichtungen und ordnen Sie Varianten und Lagerorte zu. Bevor Sie produktiv schalten, lösen Sie im Testshop über den Checkout einen Auftrag über drei Stück einer bestandsgeführten, am Teststandort aktiven Variante aus. Sorgen Sie für genügend Bestand und eine Zuordnung aller drei Einheiten zum selben Standort. Prüfen Sie anschließend folgende Werte (angenommene Zahlen):
- Artikelzuordnung: Die Position erscheint in der Wawi beim erwarteten Artikel, und
LineItem.idsowie Variant-ID sind gespeichert. Landet die Position in der Fehlerliste oder bei einem falschen Artikel, ist die Zuordnung nicht abgenommen. - Lagerort: Prüfen Sie nach abgeschlossenem Routing je Versandauftrag (
FulfillmentOrder) den zugewiesenen Standort (assignedLocation.location.id) und die zugewiesene Stückzahl. Die drei Testeinheiten müssen am erwarteten Wawi-Lager landen. - Bestandsänderung: Am Standort sinkt
availableum 3 undcommittedsteigt um 3, währendon_handunverändert bleibt. Sobald die Auslieferung in Shopify erfasst ist, sinkencommittedundon_handum je 3 (siehe Rechenbeispiel weiter unten). - Auftragsimport: In der Wawi liegt genau ein Kundenauftrag zur Shopify-Bestellung. Bestellnummer, Menge, Einzelpreise, Rabatte, Versandkosten und Gesamtsumme entsprechen den Werten in Shopify.
- Teilerstattung: Erstatten Sie eine der drei Einheiten. In Shopify bleibt
quantitybei 3,currentQuantityist 2. Prüfen Sie in der Warenwirtschaft, ob die erstattete Einheit eindeutig dem ursprünglichen Auftrag zugeordnet ist und der Erstattungsbetrag stimmt. Je nach Belegablauf kann die ursprüngliche Position mit drei Einheiten bestehen bleiben und die Korrektur auf einem eigenen Beleg stehen.
Wenn Sie den Testauftrag per orderCreate statt über den Checkout erzeugen, setzen Sie das gewünschte Bestandsverhalten ausdrücklich. Der Standardwert BYPASS ist für diesen Test ungeeignet, weil er den Bestand nicht beansprucht.
Das Shopify-Datenmodell: eine Kette aus fünf Objekten
Shopify trennt, was viele Warenwirtschaften in einem Artikelsatz führen. Die Kette lautet: Ein Shopify-Produkt (Product) hat eine oder mehrere Varianten (ProductVariant). Jede Variante hat genau einen InventoryItem (Bestandsartikel). Dessen Menge liegt je Standort in einem InventoryLevel, und der Standort selbst ist eine Location.
- Kunden bestellen Varianten, nicht Produkte. Der Wawi-Artikel entspricht deshalb in der Regel der Variante, nicht dem Produkt.
- Die SKU steht an der Variante und am Bestandsartikel. Die Dokumentation weist darauf hin, dass sie Groß- und Kleinschreibung unterscheidet.
- Bestand ist ein Paar aus Bestandsartikel und Standort. Ohne Standort-Zuordnung lässt sich keine Menge schreiben.
- Ein Shop darf standardmäßig bis zu 2.048 Varianten je Produkt haben. Wawi-Artikelfamilien mit sehr vielen Ausprägungen können diese Grenze erreichen.
Wie sich Varianten- und Set-Artikel ungünstig auswirken, beschreibt Bestandsabgleich bei Sets und Varianten.
Zuordnungstabelle: Shopify-Feld, Wawi-Feld, Richtung, Schlüssel, Stolperstein
Die Tabelle fasst zusammen, was in der Doku verteilt steht. Die Spalte „Wawi-Feld“ nennt die übliche Entsprechung und kann bei Ihrem System anders heißen. „Führt“ ist eine Empfehlung, keine Vorgabe von Shopify.
| Shopify | Typisches Wawi-Feld | Führt | Schlüssel | Stolperstein |
|---|---|---|---|---|
Product (Titel, Beschreibung) | Artikelstamm, Bezeichnung, Langtext | Wawi oder Produktdatenpflege | Product-ID (GID) in der Wawi speichern | Typischer Fall: Eine Wawi-Artikelfamilie wird in Shopify ein Produkt mit mehreren Varianten. Legen Sie die Gruppierung für Shopify fest und speichern Sie die Zuordnung der Wawi-Artikel zu den Shopify-Varianten. |
ProductVariant.sku | Artikelnummer | Wawi | SKU für die Erstzuordnung, Variant-ID für den laufenden Abgleich | Die SKU taugt für die Erstzuordnung nur, wenn sie auf beiden Seiten vorhanden und eindeutig ist. Shopify kann mehrere Bestandsartikel mit derselben SKU führen (Feld duplicateSkuCount). Mehrdeutige Treffer geben Sie zur Klärung aus. Groß-/Kleinschreibung zählt. Führende Nullen oder Leerzeichen gehen bei Tabellen-Exporten leicht verloren. |
ProductVariant.barcodes | EAN/GTIN | Wawi | Barcode als Zweitschlüssel, ebenfalls auf Eindeutigkeit prüfen | Das ältere Feld barcode ist als veraltet markiert. Seit API-Version 2026-10 liefert ProductVariant.barcodes eine Connection für bis zu 20 Barcodes. Beim Schreiben ersetzt die Eingabeliste barcodes den gesamten bisherigen Satz. |
ProductVariant.price, compareAtPrice | Verkaufspreis, Streichpreis | Wawi, Aktionen ggf. Shop | Variant-ID | Der Preis gilt in der Standardwährung des Shops. Staffel- oder Kundengruppenpreise der Wawi passen nicht in dieses eine Feld. Netto/Brutto vorab festlegen. |
InventoryItem.tracked, unitCost | Lagerführung ja/nein, Einstandspreis | Wawi | InventoryItem-ID | Prüfen Sie, ob tracked den Wert true hat. Bei false verfolgt Shopify die Bestandsmengen des Artikels nicht. Vor dem Schreiben prüfen. |
InventoryLevel, Menge available | Verkaufbarer Bestand je Standort | Wawi, mit Prüfwert | InventoryItem-ID und Location-ID | Aus on_hand ergibt sich available nach Abzug von committed, reserved, damaged, safety_stock und quality_control. Beschädigte Ware, Sicherheitsbestand und Ware in der Qualitätskontrolle zählen zum physischen Bestand, stehen aber nicht zum Verkauf. Shop-Verkäufe verändern available laufend. Ein blindes Überschreiben kann diese Verkäufe wieder aus dem Bestand löschen. Ein aktiver Standort garantiert keinen aktiven Bestandsdatensatz je Artikel: Seit 2026-04 kann eine Mengenmutation einen inaktiven InventoryLevel mit gespeicherter Menge erzeugen. Der Schreibaufruf gelingt dann, der Artikel ist dort aber weder verkäuflich noch von dort auslieferbar. Prüfen Sie deshalb InventoryLevel.isActive je Bestandsartikel. |
InventoryLevel, Menge on_hand | Physischer Lagerbestand | Wawi | wie oben | on_hand ist die Summe aus available, committed, reserved, damaged, safety_stock und quality_control. |
InventoryLevel, Menge committed | Von Shopify gebundene Menge | Shopify | wie oben | Über die Admin-API nicht änderbar. Änderungen daran lösen keinen Webhook aus. Zu committed zählen neben offenen Bestellungen auch Entwurfsbestellungen mit reserviertem Bestand sowie als versandbereit markierte Umlagerungen oder Sendungen. Die Menge entspricht daher nicht allein den Kundenaufträgen. |
Location | Lager, Lagerort | Einmalige Zuordnung | Location-ID | Pflegen Sie eine feste Liste Wawi-Lager gleich Location-ID. Prüfen Sie isActive, fulfillsOnlineOrders und isFulfillmentService. |
Order | Kundenauftrag | Shop (entsteht dort) | Order-ID, daneben die Bestellnummer name | Standardmäßig sind nur Bestellungen der letzten 60 Tage abrufbar. Für ältere gibt es den Scope read_all_orders, den Sie zusätzlich zu read_orders oder write_orders deklarieren. Ob dafür eine Shopify-Freigabe nötig ist, hängt vom App-Typ ab (siehe FAQ). |
LineItem | Auftragsposition | Shop | LineItem.id für die Position, Variant-ID für die Artikelzuordnung | SKU und Variant-ID identifizieren einen Artikel, aber keine einzelne Auftragsposition. variant kann leer sein. Dann nutzen Sie eine bereits gespeicherte Zuordnung oder eine eindeutig zuordenbare SKU und geben ungelöste Fälle zur Klärung aus. quantity enthält erstattete und entfernte Einheiten, currentQuantity nicht. |
LineItem.originalUnitPriceSet, discountAllocations | Ursprünglicher Einzelpreis, Rabattanteile | Shop | – | Rabattanteile können auch erstattete oder entfernte Einheiten enthalten. Bewahren Sie sie beim Ursprungsbeleg auf und gleichen Sie Erstattungen getrennt ab. Für den aktuellen Positionswert nach allen Rabatten und vor Steuern verwenden Sie priceAfterAllDiscountsBeforeTaxesSet. |
FulfillmentOrder, Fulfillment | Lieferschein, Sendung, Tracking | Wawi meldet zurück | FulfillmentOrder.id für den Versandauftrag, Fulfillment.id für die einzelne Sendung mit Tracking | Eine Bestellung kann mehrere Fulfillment Orders haben, auch mehrere am selben Standort. Shopify datiert die Abkündigung des alten Ablaufs zur Versandabwicklung über Order und Fulfillment auf API-Version 2022-07. Bis 2023-07 sollten alle Apps den neuen Ablauf mit FulfillmentOrder nutzen. |
Entscheidungshilfe: Wer ist Master für Bestand, Preis, Artikelstamm und Bestellung?
Legen Sie je Datenbereich ein führendes System fest und je Vorgang, welche Änderungen erlaubt sind. Shopify-Verkäufe sollen regulär auf den Bestand wirken. Vermeiden Sie konkurrierende absolute Abgleiche aus mehreren Systemen, denn sie erzeugen Änderungen, die sich gegenseitig überholen. Die folgende Übersicht ist eine Empfehlung für den üblichen Fall.
| Datenbereich | Master | Begründung | Wann Sie abweichen |
|---|---|---|---|
| Artikelstamm (SKU, EAN, Gruppierung) | Wawi | Dort entsteht die Artikelnummer, auf die Einkauf, Lager und Buchhaltung zugreifen. | Ihre Texte und Bilder pflegen Sie im Shop oder in einer Produktdatenpflege. Dann bleibt dort nur der Stamm aus der Wawi. |
Bestand physisch (on_hand) | Wawi | Wareneingang, Inventur und Umlagerung finden dort statt. | Verkaufen Sie auf mehreren Kanälen, braucht es eine zentrale Stelle, die Kanalverkäufe zusammenführt. |
Gebundene Menge (committed) | Shopify | Shopify verwaltet diese Menge selbst, die API erlaubt keine Änderung. | Keine. Sie lesen den Wert. Die Kundenauftragsreservierung gleichen Sie anhand der Auftragsdaten ab und berücksichtigen andere Bindungsgründe, etwa Entwurfsbestellungen oder Umlagerungen, getrennt. |
| Preis | Wawi | Eine Preisquelle verhindert, dass Shop und Rechnung auseinanderlaufen. | Reine Shop-Aktionen: Dann führt der Shop für einen begrenzten Zeitraum, und die Wawi darf diese Artikel nicht überschreiben. |
| Bestellung | Shop, für im Shopify-Shop entstandene Bestellungen | Die Wawi übernimmt sie als Kundenauftrag. | Für in der Wawi erfasste Aufträge, etwa Telefon- oder Außendienstaufträge, legen Sie separat fest, ob sie dort bleiben oder nach Shopify übertragen werden. |
| Versandstatus, Tracking | Wawi | Dort wird gepackt und versendet. Der Shop erfährt es per Rückmeldung. | Versendet ein externer Lagerdienstleister, kann dessen Standort in Shopify als Fulfillment-Service geführt werden. |
Beim Setzen einer Menge können Sie den erwarteten aktuellen Wert der konkret geschriebenen Menge mitgeben (changeFromQuantity). Stimmt er nicht mehr, weil sich diese Menge inzwischen geändert hat, lehnt Shopify die Änderung mit CHANGE_FROM_QUANTITY_STALE ab. Der Prüfwert schützt also gegen eine zwischenzeitliche Änderung genau dieser Menge. Eine Bestellung kann available von 10 auf 9 senken und committed von 0 auf 1 erhöhen, während on_hand bei 10 bleibt. Eine Prüfung auf on_hand fällt dann nicht auf. Auch ein frisch gelesener Prüfwert schützt nicht vor einem veralteten Wawi-Zielwert: Vor einem absoluten available-Abgleich müssen die Shop-Verkäufe bereits im Wawi-Zielwert berücksichtigt sein. Bei CHANGE_FROM_QUANTITY_STALE lesen Sie den aktuellen Zustand und berechnen den Zielwert neu.
Bestand schreiben: absolut, relativ und mit Wiederholungsschutz
Für Mengen stehen zwei Mutationen bereit. inventorySetQuantities setzt einen absoluten Wert für available oder on_hand. inventoryAdjustQuantities ändert eine Menge um eine Differenz (delta), etwa von 100 auf 102 mit dem Wert 2. Eine dritte, inventoryMoveQuantities, verschiebt Mengen zwischen Status, zum Beispiel von reserved nach available.
- Absolut setzen eignet sich für Inventur und Nachtabgleich. Es heilt Abweichungen, kann aber Verkäufe überschreiben. Geben Sie darum den erwarteten Ausgangswert mit. Shopify führte
changeFromQuantityin 2026-01 ein. Mit 2026-04 wurde das Feld zur Pflicht, ein ausdrücklichesnullschaltet die Prüfung ab. Gleichzeitig entfielencompareQuantityundignoreCompareQuantity. - Relativ ändern eignet sich für einzelne Buchungen wie Wareneingang oder Korrektur. Seit 2026-04 gehört
changeFromQuantitybeiinventoryAdjustQuantitieszu jedem Eintrag inchanges. Übergeben Sie den erwarteten Ausgangswert oder ausdrücklichnull, wenn Sie die Prüfung bewusst abschalten. Füravailablelassen SieledgerDocumentUriweg. Bei anderen zulässigen Bestandsstatus, etwadamaged, geben Sie in jedem Eintrag dieselbe gültige Nicht-Shopify-URI für den einzelnen Buchungsbeleg an.referenceDocumentUriist der optionale Verweis auf den übergeordneten Vorgang. Eine nach einem unklaren Fehler ungeprüft erneut gesendete Delta-Buchung kann doppelt zählen. - Status verschieben: Bei
inventoryMoveQuantitiesgehörtchangeFromQuantityinfromund into, jeweils mit dem erwarteten Ausgangswert oder ausdrücklichnull. Für den Wechsel vonreservednachavailablegeben Sie infromzusätzlich eine gültige externeledgerDocumentUrian, die nicht das Formatgid://shopify/…haben darf. Lassen SieledgerDocumentUriintofüravailableweg. Shopify lehnt das Feld dort ab. - Idempotenzschlüssel: Die Direktive
@idempotent(key: $idempotencyKey)macht identische Wiederholungen sicher. Seit 2026-01 ist sie optional, ab 2026-04 Pflicht. Vergeben und speichern Sie einen eindeutigen Schlüssel pro API-Operation oder Teilpaket. Eine Buchungsnummer der Wawi allein reicht nicht, wenn der Beleg mehrere API-Aufrufe auslöst oder nach einer Neuberechnung andere Parameter gesendet werden. Verwenden Sie den Schlüssel bei identischen Wiederholungen erneut. Shopify erkennt ihn 24 Stunden lang. Danach gilt eine Wiederholung als neue Operation, und ein erneut gesendetes Delta kann doppelt gebucht werden. Prüfen Sie deshalb nach Ablauf der 24 Stunden den Buchungsstand, bevor Sie erneut senden. Für eine nachweislich abgelehnte und mit geänderten Parametern neu berechnete Operation verwenden Sie einen neuen Schlüssel, denn Shopify kann denselben Schlüssel mit geänderten Parametern mitIDEMPOTENCY_KEY_PARAMETER_MISMATCHzurückweisen. - Beleg: Mit
referenceDocumentUrihängen Sie einen Verweis auf den Wawi-Beleg an die Änderung. BeiinventoryMoveQuantitiesnimmt es die übergeordnete Belegreferenz auf, währendledgerDocumentUridie einzelne Buchung bezeichnet. Das erleichtert später die Fehlersuche.
Die Eingabefelder stehen in der Referenz für 2026-10: InventoryChangeInput und InventoryMoveQuantityTerminalInput.
Zum Zurücklesen gibt es die Webhooks inventory_levels/update, inventory_levels/connect und inventory_levels/disconnect. Änderungen an committed, reserved, damaged, safety_stock und quality_control lösen jedoch keinen Webhook aus. Wer diese Mengen braucht, liest sie regelmäßig je Bestandsartikel und Standort direkt und vergleicht sie mit dem gespeicherten Stand. InventoryLevel.updatedAt ist an Änderungen von available gekoppelt, andere Status können sich ändern, ohne dass dieser Zeitstempel mitzieht. Bei Bedarf werten Sie den Zeitstempel des einzelnen InventoryQuantity aus. Zu Überverkäufen über mehrere Kanäle lesen Sie Überverkauf bei Shop und Marktplatz.
Rechenbeispiel: eine Variante an zwei Standorten
Angenommene Zahlen, jeweils available / committed / on_hand. Shopify weist die Bestellung in diesem Beispiel Standort A zu.
| Schritt | Standort A | Standort B |
|---|---|---|
| Ausgangslage | 10 / 0 / 10 | 5 / 0 / 5 |
| Bestellung über 1 Stück | 9 / 1 / 10 | 5 / 0 / 5 |
| Auslieferung von Standort A in Shopify erfasst | 9 / 0 / 9 | 5 / 0 / 5 |
Die Wawi liest in der Ausgangslage available 10 an Standort A und will nach einem Wareneingang von 2 Stück auf 12 setzen, mit changeFromQuantity 10. Geht die Bestellung vorher ein, steht available bei 9. Shopify lehnt den Schreibvorgang mit CHANGE_FROM_QUANTITY_STALE ab, weil 9 nicht 10 ist. Die Wawi liest den aktuellen Zustand (9 / 1 / 10) und berechnet den Zielwert neu: 9 plus 2 ergibt 11. Eine Prüfung auf on_hand hätte nach der Bestellung nicht abgelehnt, weil on_hand bei 10 bleibt. Sie greift erst nach der in Shopify erfassten Auslieferung, wenn on_hand auf 9 sinkt.
Bestellungen übernehmen: Webhook, Abfrage und Abgleichlauf
Shopify meldet neue Bestellungen per Webhook, wenn Sie beispielsweise das Topic orders/create abonnieren. Die vollständige Topic-Liste samt Berechtigungen steht in der Webhook-Referenz. Beachten Sie diese Regeln aus der Shopify-Dokumentation:
- Signatur prüfen. Der Header
X-Shopify-Hmac-Sha256enthält eine Base64-Signatur des rohen Request-Bodys, berechnet mit dem Client Secret der App. Lesen Sie den Body, bevor Sie ihn parsen, und verwerfen Sie abweichende Zustellungen. - Schnell antworten. Das Verbindungs-Timeout liegt bei einer Sekunde, das Gesamt-Timeout bei fünf. Alles außerhalb von 2xx, auch eine Weiterleitung, zählt als Fehler. Prüfen Sie die Signatur, legen Sie Nachricht und Zustell-ID zuverlässig ab und senden Sie dann innerhalb des Zeitlimits
200 OK. Verarbeiten Sie den Auftrag anschließend asynchron, etwa über eine Warteschlange. Stürzt der Empfänger nach200 OKvor dem Speichern ab, gilt die Zustellung als erfolgreich, und die Nachricht fehlt in der Verarbeitung. - Wiederholungen einplanen. Bleibt die Antwort aus oder ist sie fehlerhaft, versucht Shopify es bis zu achtmal innerhalb von vier Stunden. Ein über die Admin-API eingerichtetes Abonnement löscht Shopify nach acht aufeinanderfolgenden Fehlschlägen. Warnmails gehen an die hinterlegte Entwickler-Notfalladresse der App. Danach liefert dieses Abonnement keine Bestellungen mehr.
- Duplikate erkennen. Verwenden Sie
X-Shopify-Webhook-Id, um wiederholte Zustellungen zu erkennen. Kommt dieselbe ID erneut, überspringen Sie die Verarbeitung und antworten trotzdem erfolgreich, sobald die ursprüngliche Nachricht zuverlässig erfasst ist. Mehrere Abonnements für dasselbe Topic liefern je eine Zustellung mit eigener Webhook-ID, aber gleicherX-Shopify-Event-Id. Solche Zustellungen können parallel verarbeitet werden, und die Webhook-ID erkennt sie nicht als Duplikat. Legen Sie den Kundenauftrag deshalb anhand der Shopify-Order-ID atomar an oder aktualisieren Sie ihn, etwa mit einem eindeutigen Schlüssel in der Datenbank. - Reihenfolge nicht voraussetzen. Shopify garantiert sie nicht, auch nicht über Topics hinweg. Nutzen Sie
X-Shopify-Triggered-Atoder ein vorhandenesupdated_atzur zeitlichen Einordnung. Zeitstempel stellen keine garantierte Reihenfolge her. Verhindern Sie, dass ein verspäteter älterer Stand neuere Daten überschreibt, und lesen Sie bei unklarer Reihenfolge den aktuellen Zustand per API. - Nicht auf Webhooks allein bauen. Shopify empfiehlt einen Abgleichlauf, der per API alles holt, was seit dem letzten Lauf geändert wurde. Für Bestellungen eignet sich dafür die Abfrage
ordersmit dem Filterupdated_at. Wie Sie Bestandsstatus abgleichen, steht im Abschnitt zum Bestand.
Beim Einlesen einer Bestellung zählen drei Details. Erstens: Verwenden Sie currentQuantity, wenn Sie nach Erstattungen oder Entfernungen die tatsächliche Menge brauchen. Zweitens: Erhalten Sie discountAllocations am Ursprungsbeleg und gleichen Sie Erstattungen gesondert ab. Ziehen Sie die ursprünglichen Rabattanteile nicht pauschal vom Wert der reduzierten Menge ab. Nutzen Sie für den heutigen Positionswert nach Rabatten und vor Steuern priceAfterAllDiscountsBeforeTaxesSet und für Buchungen die zum Vorgang passenden Summen-, Währungs-, Steuer- und Erstattungsdaten. discountedUnitPriceSet ist nur ein Näherungswert für den rabattierten Stückpreis. Drittens: Speichern Sie LineItem.id als Schlüssel der Auftragsposition. Ordnen Sie den Wawi-Artikel über die Variant-ID zu, sofern sie vorliegt. Bei fehlender Variante nutzen Sie eine bereits gespeicherte Zuordnung oder eine eindeutig zuordenbare SKU und geben ungelöste Fälle zur Klärung aus.
Rate Limits: Wie schnell dürfen Sie abgleichen?
Die GraphQL-Admin-API drosselt nach berechneten Abfragekosten, nicht nach Anzahl der Aufrufe. Die Dokumentation nennt für die Auffüllung des Kontingents 100 Punkte pro Sekunde im Standardplan, 200 bei Advanced, 1.000 bei Shopify Plus und 2.000 bei Shopify for enterprise. Eine einzelne Abfrage darf höchstens 1.000 Punkte kosten, geprüft wird vor der Ausführung auf Basis der angeforderten Kosten. Standardmäßig kosten Skalare und Enums 0, Objekte 1 und Mutationen 10. Die Kosten für Connections richten sich nach den Argumenten first und last.
- Lesen Sie
extensions.costundthrottleStatus, wenn sie vorhanden sind. Dort stehen die angeforderten und tatsächlichen Kosten sowie der aktuelle Füllstand. Steuern Sie Ihre Last daran und nicht an festen Pausen. Fehler, die vor der Ausführung auftreten, etwaMAX_COST_EXCEEDED, behandeln Sie gesondert: Dort gibt es keine tatsächlichen Ausführungskosten. - Ist das Kontingent erschöpft, meldet die API den Fehler
THROTTLED. Als Wartezeit empfiehlt Shopify eine Sekunde, bevor Sie es erneut versuchen. - Eingabelisten sind auf 250 Einträge begrenzt. Gruppieren Sie für
inventoryAdjustQuantitieszuerst nach Bestandsstatus. Außerhalb vonavailablegruppieren Sie zusätzlich nachledgerDocumentUri. Bilden Sie erst danach Pakete mit höchstens 250 Einträgen. Unterschiedliche Beleg-URIs im gleichen Aufruf könnenMAX_ONE_LEDGER_DOCUMENTauslösen. - Für große Datenmengen sieht Shopify Bulk Operations vor. Sie unterliegen nicht den Höchstkosten und Limits einzelner Abfragen.
- Für Neuanlagen gibt es eine Zusatzgrenze: Hat ein Shop 500.000 Varianten, sind höchstens 10.000 neue Varianten pro Tag möglich. Überschreitungen bringen eine Antwort 429. Shopify Plus ist davon ausgenommen.
Für den ersten Import eines größeren Katalogs ist ein sauberer Ablauf entscheidend. Was bei einem Tabellenimport schiefgehen kann, steht in Shopify-CSV-Import und gelöschte Varianten.
Wo Abgleiche scheitern: Symptom, Ursache, Gegenmittel
| Symptom | Wahrscheinliche Ursache | Gegenmittel |
|---|---|---|
| Bestand springt nach dem Abgleich zurück, Überverkauf | Absoluter Wert ohne Prüfwert überschreibt zwischenzeitliche Verkäufe, oder der Wawi-Zielwert berücksichtigt Shop-Verkäufe nicht | changeFromQuantity für die geschriebene Menge mitgeben, Shop-Verkäufe im Zielwert berücksichtigen, bei CHANGE_FROM_QUANTITY_STALE den aktuellen Zustand lesen und den Zielwert neu berechnen |
| Schreibaufruf erfolgreich, Artikel am Standort dennoch nicht verkäuflich | InventoryLevel ist inaktiv und speichert nur die Menge | InventoryLevel.isActive prüfen und den Bestandsartikel bei Bedarf mit inventoryActivate oder inventoryBulkToggleActivation aktivieren |
| Position ohne passenden Wawi-Artikel | SKU anders geschrieben, geändert oder Variante nicht mehr vorhanden | Variant-ID mitführen, Zuordnung prüfen, Abweichungen in eine Fehlerliste |
| Bestellung doppelt in der Wawi | Wiederholte Zustellung oder zwei Abonnements, die parallel verarbeitet werden | Webhook-ID zur Erkennung wiederholter Zustellungen verwenden und den Kundenauftrag anhand der Shopify-Order-ID atomar anlegen oder aktualisieren, etwa mit einem eindeutigen Datenbankschlüssel |
| Bestellung fehlt | Antwort nach mehr als fünf Sekunden, über die Admin-API eingerichtetes Abonnement nach acht aufeinanderfolgenden Fehlschlägen gelöscht | Empfängerablauf wie im Abschnitt zu Bestellungen, täglicher Abgleichlauf über updated_at der Bestellungen |
| Beim Erstimport fehlen ältere Bestellungen | Zugriff auf die letzten 60 Tage begrenzt | read_all_orders zusätzlich zum Bestell-Scope deklarieren (Freigabe je nach App-Typ, siehe FAQ) oder Altbestand aus der Wawi nehmen |
| Bestand im falschen Lager | Location-ID falsch oder fehlend zugeordnet | Feste Zuordnungsliste Wawi-Lager zu Location pflegen |
| Rechnungssumme weicht ab | Rabatte auf Auftragsebene oder per Code nicht in discountedUnitPriceSet enthalten, das nur ein Näherungswert ist | Zugewiesene Beträge aus discountAllocations übernehmen, bei Bedarf auch auf Versandzeilen, und für den Abgleich die passenden Summen-, Steuer-, Währungs- und Erstattungsdaten nutzen |
| Menge nach Erstattung falsch | quantity statt currentQuantity gelesen | Das passende Feld je Zweck festlegen |
Fehler THROTTLED | Zu viele Einzelaufrufe, zu große Abfragen | Pakete bis 250, Kosten aus extensions.cost lesen, wenn vorhanden, eine Sekunde warten |
Treten mehrere dieser Symptome gleichzeitig auf, lohnt es sich, zuerst die Entscheidungshilfe oben auszufüllen, denn unklare Schreibzuständigkeiten sind eine mögliche Ursache. Wenn Ihre Wawi keinen passenden Anschluss hat oder Ihre Preis- und Lagerlogik nicht in Standardfelder passt, ist eine individuelle Schnittstelle zwischen Shopify und Warenwirtschaft der saubere Weg.
Checkliste: Rate-Limit-, Webhook- und Wiederholungsregeln
Die genannten GraphQL-Felder und Mutationen beziehen sich auf API-Version 2026-10.
Einrichtung
- Lagerliste Wawi-Lager zu Shopify-
Locationanlegen und jeden Standort aufisActiveundfulfillsOnlineOrdersprüfen. Für jeden vorgesehenen Verkaufsstandort zusätzlichInventoryLevel.isActiveje Bestandsartikel prüfen und den Bestandsartikel bei Bedarf mitinventoryActivateoderinventoryBulkToggleActivationam Standort aktivieren. - Pro Variante Variant-ID und InventoryItem-ID in der Wawi speichern. Für die SKU-Zuordnung gelten die Regeln aus der Zuordnungstabelle (Zeile
ProductVariant.sku). - Prüfen Sie, ob
trackedden Werttruehat. Beifalseverfolgt Shopify die Bestandsmengen des Artikels nicht. - Pro Datenbereich ein führendes System und je Vorgang die erlaubten Änderungen festlegen (siehe Entscheidungshilfe). Shopify-Verkäufe regulär auf den Bestand wirken lassen und konkurrierende absolute Abgleiche aus mehreren Systemen vermeiden.
- Webhook-Empfänger nach den Regeln aus dem Abschnitt zu Bestellungen einrichten: Signatur prüfen, Nachricht und Zustell-ID zuverlässig ablegen, dann
200 OKsenden und asynchron verarbeiten. - Vor dem Produktivschalten die Abnahmeprüfung aus dem ersten Abschnitt mit Testauftrag und Teilerstattung durchführen.
Laufender Betrieb
- Bestandsschreiben mit
changeFromQuantityausführen, beiinventorySetQuantities,inventoryAdjustQuantitiesundinventoryMoveQuantities, wobei die Shop-Verkäufe bereits im Wawi-Zielwert berücksichtigt sind. - Pro API-Operation oder Teilpaket einen eigenen
@idempotent-Schlüssel vergeben und speichern. Die Wiederholungsregeln stehen im Abschnitt zum Bestand. - Relative Mengenänderungen nach Status und außerhalb von
availablezusätzlich nachledgerDocumentUrigruppieren. Pakete auf 250 Einträge begrenzen undextensions.costsowiethrottleStatusmitlesen, wenn vorhanden. - Bei
THROTTLEDmindestens eine Sekunde warten und die identische Operation mit demselben Schlüssel wiederholen. - Doppelte Zustellungen anhand der Webhook-ID überspringen und den Kundenauftrag anhand der Shopify-Order-ID atomar anlegen oder aktualisieren.
- Zeitliche Einordnung über
X-Shopify-Triggered-Atoder ein vorhandenesupdated_at. Einen verspäteten älteren Stand nicht neuere Daten überschreiben lassen und bei unklarer Reihenfolge den aktuellen Zustand per API lesen. - Täglichen Abgleichlauf einrichten: Für Bestellungen
ordersmit dem Filterupdated_atverwenden. Für benötigte Bestandsstatus die Mengen je Bestandsartikel und Standort regelmäßig direkt lesen und mit dem gespeicherten Stand vergleichen, bei Bedarf über den Zeitstempel des einzelnenInventoryQuantity. - Prüfen, ob das Webhook-Abonnement noch besteht, und bei Ausfall alarmieren.
- Fehlgeschlagene Vorgänge mit Beleg-Referenz in einer Liste halten, damit sie ohne Doppelbuchung wiederholbar sind.
Wenn Ihre Warenwirtschaft keinen passenden Shopify-Anschluss hat oder Ihre Preis- und Lagerlogik nicht in die Standardfelder passt, entwickeln wir Software-Schnittstellen und integrieren Ihre Systeme so, dass Bestand, Preis und Bestellung nachvollziehbar zwischen Shop und Wawi laufen.
Mehr dazu: Software-Schnittstellen entwickeln und Systeme integrieren
Quellen
- Shopify: Bestandsverwaltung mit der Admin-GraphQL-API, shopify.dev
- Shopify: Mengen und Status verwalten, Compare-and-swap, shopify.dev
- Shopify: Idempotenz in der GraphQL-Admin-API, shopify.dev
- Shopify: Webhook-Zustellungen prüfen, shopify.dev
- Shopify: Zugriffsbereiche (Access Scopes), shopify.dev
- Shopify: GraphQL-Admin-API, Rate Limits, shopify.dev
- Shopify: API-Limits (allgemein), shopify.dev
- Shopify: Webhooks, Grundlagen und Best Practices, shopify.dev
- Shopify: Mutation inventorySetQuantities (2026-10), shopify.dev
- Shopify: Mutation inventoryAdjustQuantities (2026-10), shopify.dev
- Shopify: Mutation inventoryMoveQuantities (2026-10), shopify.dev
- Shopify: Eingabeobjekt InventoryChangeInput (2026-10), shopify.dev
- Shopify: Eingabeobjekt InventoryMoveQuantityTerminalInput (2026-10), shopify.dev
- Shopify: Änderung, changeFromQuantity wird Pflichtfeld, shopify.dev
- Shopify: Änderung, Schutz vor gleichzeitigen Änderungen, shopify.dev
- Shopify Community: InventoryLevel.updatedAt, community.shopify.dev
- Shopify: Objekt ProductVariant, shopify.dev
- Shopify: Änderung barcode zu barcodes, shopify.dev
- Shopify: Objekt InventoryItem, shopify.dev
- Shopify: Objekt InventoryLevel, shopify.dev
- Shopify: Objekt Location, shopify.dev
- Shopify: Objekt Order, shopify.dev
- Shopify: Objekt LineItem, shopify.dev
- Shopify: Objekt FulfillmentOrder, shopify.dev
- Shopify: Bestellungen und Fulfillment verwalten, shopify.dev
- Shopify: Mutation orderCreate, shopify.dev
- Shopify: Mutation productVariantsBulkUpdate, shopify.dev
- Shopify: Bestandsverhalten bei der Erzeugung eines Auftrags, shopify.dev
- Shopify: Geschützte Kundendaten, shopify.dev
Alle Quellen gelesen am 19.11.2026.
Erstellt von der Redaktion Die Netzhandwerker mit KI-Unterstützung. Die Sachangaben wurden vor der Veröffentlichung automatisch gegen die genannten Quellen geprüft.