Shopify-Entwickler in Essen

#Wie binde ich Shopify an ERP und Lager an, ohne dass die Bestände auseinanderlaufen?

Die technische Frage hinter den meisten Anbindungen ist eine Zuständigkeitsfrage: Welches System führt Bestand, Preise und Bestellstatus, und in welche Richtung fließen die Daten? Meist führt das ERP oder die Warenwirtschaft die Bestände, und Shopify meldet Bestellungen zurück. Erst wenn das geklärt ist, lohnt sich die Wahl der Schnittstelle. Diese Seite beschreibt, wie ich die Shopify-Seite baue: Admin API, Versionen, Grenzen, Webhooks und große Exporte. Alle Angaben zu Shopify stammen aus shopify.dev, abgerufen am 11. November 2026.

In Essen findet jährlich die SPIEL statt, nach Wikipedia die weltweit größte Publikumsveranstaltung für Gesellschaftsspiele, in der Messe Essen. Händler, die rund um solche Termine mehr Bestellungen erwarten, brauchen eine Anbindung, die Spitzen puffert, statt bei jeder Bestellung sofort das ERP zu belasten. Das ist der Grund für die Warteschlange im Webhook-Abschnitt weiter unten.

Foto: Steffen Schmitz, CC BY-SA 4.0, Wikimedia Commons.

#GraphQL oder REST: was Shopify zur Admin API sagt

Auf der Referenzseite der REST Admin API steht, sie sei seit dem 1. Oktober 2024 eine Legacy-API. Seit dem 1. April 2025 müssen neue öffentliche Apps ausschließlich mit der GraphQL Admin API gebaut werden. Eine Abschaltung nennt die Seite nicht. Sie weist aber darauf hin, dass einige neuere Plattformfunktionen nur in GraphQL verfügbar sind.

Für eine Anbindung folgt daraus:

• Neue Anbindung: GraphQL, ohne Umweg über REST.
• Bestehende REST-Anbindung: Sie läuft weiter, wird aber mit jeder neuen Funktion ein Sonderfall. Ich liste zuerst die genutzten Endpunkte auf und stelle zuerst die um, für die es in GraphQL etwas Besseres gibt, etwa Bulk Operations statt seitenweiser Abfrage.
• Zugang für den eigenen Shop: Vom Händler im Shopify-Admin angelegte Custom Apps lassen sich nicht mehr neu erstellen. Bestehende bleiben unverändert. Neue Apps entstehen über das Dev Dashboard oder die Shopify CLI.

Mit GraphQL fragen Sie genau die Felder ab, die das ERP braucht. Das spart Datenmenge und, wie der nächste Abschnitt zeigt, auch Aufwandspunkte.

#Was bedeuten vierteljährliche API-Versionen für eine laufende Anbindung?

Shopify veröffentlicht alle drei Monate eine neue Version, jeweils am ersten Tag des Quartals um 17 Uhr UTC. Die Namen sind datumsbasiert, etwa 2026-04. Jede stabile Version bleibt mindestens zwölf Monate zugänglich, zwischen zwei Versionen liegen mindestens neun Monate Überschneidung.

Der heikle Punkt steht in der Dokumentation selbst: Fragt eine Anbindung eine nicht mehr zugängliche Version an, antwortet Shopify mit der ältesten noch zugänglichen stabilen Version. Es gibt also keinen Fehler, sondern eine Antwort in einer anderen Version. Hat sich dort ein Feld oder eine Pflichtangabe geändert, merkt es das ERP erst am Ergebnis.

Mein Vorgehen: Die Version steht an genau einer Stelle der Konfiguration. Jede Antwort enthält den Header X-Shopify-API-Version, und die Anbindung schlägt Alarm, wenn er von der angefragten Version abweicht. Einmal im Quartal teste ich gegen die neue stabile Version auf einem Entwicklungsshop, bevor die alte ausläuft.

Wie viel sich ändern kann, zeigt inventorySetQuantities. Seit 2026-04 muss jede Menge einen Wert changeFromQuantity enthalten, und der Idempotenz-Schlüssel per @idempotent ist Pflicht. Fehlt eines von beiden, gibt die Mutation einen Fehler zurück.

#Wie funktionieren die Rate Limits der GraphQL Admin API?

Die GraphQL Admin API begrenzt nicht die Zahl der Anfragen, sondern den berechneten Aufwand. Jedes Feld hat einen Punktwert: Skalare und Enums null, Objekte einen, Connections richten sich nach first und last, eine Mutation zehn. Das Limit gilt je Kombination aus App und Shop und hängt vom Tarif des Shops ab.

Dahinter steht ein Leaky Bucket: Das Kontingent füllt sich laufend wieder auf, kurze Spitzen sind erlaubt, solange der Durchschnitt unter der Auffüllrate bleibt. Eine einzelne Abfrage darf unabhängig vom Tarif höchstens 1000 Punkte kosten. Vor der Ausführung muss der Bucket Platz für den angeforderten Aufwand haben, danach erstattet Shopify die Differenz zum tatsächlichen Aufwand.

Jede Antwort enthält unter extensions.cost den angeforderten und den tatsächlichen Aufwand sowie throttleStatus mit maximumAvailable, currentlyAvailable und restoreRate. Daran steuere ich die Anbindung. Wird das Limit überschritten, kommt der Fehlercode THROTTLED, nach Shopifys Beschreibung vergleichbar mit 429 Too Many Requests. Als Wartezeit empfiehlt Shopify eine Sekunde. Anders ist MAX_COST_EXCEEDED: Die Abfrage selbst ist zu groß, ein erneuter Versuch hilft nicht, sie muss kleiner werden.

const URL = `https://${process.env.SHOP}.myshopify.com/admin/api/2026-10/graphql.json`;

export async function gql(query, variables = {}) {
  for (let attempt = 0; attempt < 5; attempt++) {
    const res = await fetch(URL, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Shopify-Access-Token": process.env.SHOP_TOKEN,
      },
      body: JSON.stringify({ query, variables }),
    });
    const body = await res.json();
    if (!body.errors?.some((e) => e.extensions?.code === "THROTTLED")) return body;
    await new Promise((r) => setTimeout(r, 1000));
  }
  throw new Error("Shopify throttled the request five times in a row");
}

Das ist bewusst klein. In einem Projekt kommt dazu, dass die Anbindung currentlyAvailable liest und die Abfragen selbst drosselt, bevor Shopify es tut.

#Wie schreibe ich Bestände aus dem ERP nach Shopify zurück?

Für ein ERP, das die Bestände führt, ist inventorySetQuantities die passende Mutation. Die Dokumentation sagt ausdrücklich, dass man sie nur für ein System verwenden soll, das die Quelle der Wahrheit für Bestände ist. Sonst gehört inventoryAdjustQuantities an diese Stelle. Der Schutz gegen gleichzeitige Änderungen ist eingebaut: Mit changeFromQuantity geben Sie den erwarteten Ist-Bestand mit. Weicht er ab, scheitert die Mutation mit CHANGE_FROM_QUANTITY_STALE, statt eine zwischenzeitliche Verkaufsbuchung zu überschreiben. Den Wert null setze ich nur, wenn das ERP wirklich allein führt.

mutation SetStock($input: InventorySetQuantitiesInput!, $key: String!) {
  inventorySetQuantities(input: $input) @idempotent(key: $key) {
    inventoryAdjustmentGroup { changes { name delta quantityAfterChange } }
    userErrors { code field message }
  }
}

{
  "key": "3f5b6ebf-143c-4da5-8d0f-fb8553bfd85d",
  "input": {
    "name": "available",
    "reason": "correction",
    "referenceDocumentUri": "gid://erp-connector/SyncJob/2026-11-11-001",
    "quantities": [{
      "inventoryItemId": "gid://shopify/InventoryItem/1",
      "locationId": "gid://shopify/Location/1",
      "quantity": 42,
      "changeFromQuantity": 40
    }]
  }
}

Zwei Details tragen die Arbeit. Der Schlüssel hinter @idempotent sorgt dafür, dass ein wiederholter Aufruf nach einem Verbindungsabbruch nur einmal wirkt. Und referenceDocumentUri zeigt in der Bestandshistorie im Shopify-Admin, welcher Abgleichslauf die Änderung ausgelöst hat. Das hilft dem Lager, wenn jemand nachfragt, woher eine Zahl kommt.

#Wie bekomme ich Bestellungen zuverlässig ins ERP?

Webhooks melden Ereignisse wie orders/create an einen Endpunkt, statt dass das ERP ständig nachfragt. Für den Endpunkt gilt:

• Signatur prüfen. Jede HTTPS-Zustellung trägt eine Base64-kodierte HMAC-Signatur im Header X-Shopify-Hmac-SHA256. Sie wird aus dem unveränderten Rohtext der Anfrage mit dem Client Secret der App berechnet. Ein Body-Parser vor der Prüfung ist der häufigste Fehler, weil er den Rohtext verändert.
• Schnell antworten. Shopify erwartet 200 OK. Es gilt ein Timeout von einer Sekunde für die Verbindung und fünf Sekunden für die gesamte Anfrage. Jede Antwort außerhalb von 2xx, auch 3xx, zählt als Fehler.
• Retries einplanen. Ohne Antwort versucht Shopify es achtmal innerhalb von vier Stunden. Nach acht Fehlschlägen in Folge wird ein über die Admin API angelegtes Abonnement gelöscht.
• Doppelte erkennen. Shopify minimiert Dubletten, kann dieselbe Zustellung aber mehrfach senden. X-Shopify-Webhook-Id identifiziert die einzelne Zustellung.
• Lücken schließen. Shopify nennt als gängige Praxis einen Abgleichslauf, der regelmäßig Daten nachholt, die verpasst wurden.

import crypto from "node:crypto";
import express from "express";

const app = express();

app.post("/webhooks", express.raw({ type: "*/*" }), (req, res) => {
  const expected = crypto
    .createHmac("sha256", process.env.CLIENT_SECRET)
    .update(req.body)
    .digest();
  const given = Buffer.from(req.get("X-Shopify-Hmac-SHA256") ?? "", "base64");

  if (given.length !== expected.length || !crypto.timingSafeEqual(given, expected)) {
    return res.sendStatus(401);
  }
  enqueue(req.get("X-Shopify-Webhook-Id"), req.get("X-Shopify-Topic"), req.body);
  res.sendStatus(200);
});

enqueue legt die Nachricht in eine Warteschlange und kehrt sofort zurück. Das ERP arbeitet sie in seinem Tempo ab, und die Webhook-Id verhindert, dass eine doppelte Zustellung zwei Belege erzeugt. Der Abgleichslauf fragt in festen Abständen über die API nach Bestellungen, die im ERP fehlen. Erst die Kombination aus Webhook und Abgleich macht die Anbindung belastbar.

#Wann lohnen sich Bulk Operations?

Für Kataloge mit vielen Varianten, den Erstabgleich mit dem ERP oder nächtliche Vollexporte sind Bulk Operations der richtige Weg. Nach Shopifys Beschreibung unterliegen sie nicht den Kostengrenzen einzelner Abfragen. Eine normale Abfrage kann bei geschachtelten Connections auch trotz erlaubter Kosten mit einem 5xx-Fehler scheitern, und Shopify nennt Bulk Operations ausdrücklich als Ausweg.

mutation {
  bulkOperationRunQuery(query: """
    { products { edges { node { id title variants { edges { node { id sku } } } } } } }
  """) {
    bulkOperation { id status }
    userErrors { field message }
  }
}

Das Ergebnis ist eine JSONL-Datei, eine Zeile pro Objekt. Verschachtelte Objekte stehen nach ihrem Elternobjekt, und jede Variantenzeile trägt ein Feld __parentId, das auf das Produkt verweist. Das Feld gibt es im Schema nicht, man kann es nicht selbst abfragen. Die Datei lässt sich zeilenweise lesen, ohne sie ganz in den Speicher zu laden.

Die Grenzen laut Dokumentation: höchstens fünf Connections je Abfrage, höchstens zwei Ebenen Verschachtelung, zehn Tage Laufzeit, danach wird die Operation als fehlgeschlagen beendet. Ab API-Version 2026-01 laufen bis zu fünf Bulk-Abfragen je Shop und App gleichzeitig, davor war es eine je Typ. Die Download-URL ist signiert und eine Woche gültig. Das Ende meldet das Webhook-Thema bulk_operations/finish. Shopify weist selbst darauf hin, dass die Zustellung nicht garantiert ist, deshalb frage ich zusätzlich den Status ab, ab 2026-01 mit bulkOperation(id:).

Für Importe in die andere Richtung gibt es bulkOperationRunMutation: Eine hochgeladene JSONL-Datei, jede Zeile führt die angegebene Mutation einmal aus. Der Idempotenz-Schlüssel kann dabei als Variable in der Zeile stehen, die Wirkung gilt je Zeile.

#Welche Datenschutzfragen stellt eine ERP-Anbindung in Nordrhein-Westfalen?

Bestellungen enthalten Namen, Adressen und Kaufhistorie. Mit der Anbindung wandern diese Daten von Shopify in ein weiteres System. Für den Verantwortlichen ist das ein Eintrag im Verzeichnis der Verarbeitungstätigkeiten. Die Landesbeauftragte für Datenschutz und Informationsfreiheit Nordrhein-Westfalen (LDI NRW) beschreibt auf ihrer Seite, dass dieses Verzeichnis nach Art. 30 DSGVO für Verantwortliche und Auftragsverarbeiter verpflichtend ist, als Grundlage einer strukturierten Datenschutzdokumentation dient und der Aufsichtsbehörde auf Anfrage vorzulegen ist.

Dafür liefere ich Ihnen am Projektende eine Übersicht der Schnittstelle: welche Daten in welche Richtung fließen, welche Webhook-Themen abonniert sind, welche Zugriffsrechte (Scopes) die App hat und wo Zugangsdaten liegen. Die rechtliche Bewertung bleibt bei Ihrer Beratung.

#Was ich für eine Anbindung von Ihnen brauche

Die Schnittstelle des ERP-Herstellers kenne ich erst nach Ihrer Auskunft. Bietet es keine brauchbare API, lege ich die Möglichkeiten schriftlich vor. Layout und Gestaltung der Shop-Oberfläche liefert der Kunde, hier geht es um Daten und Abläufe.

#Häufige Fragen

#Muss ich meine REST-Anbindung sofort auf GraphQL umstellen?

Die REST Admin API gilt seit dem 1. Oktober 2024 als Legacy. Eine Abschaltung nennt Shopify auf der Referenzseite nicht, neuere Funktionen gibt es aber teils nur in GraphQL. Ich prüfe, welche Aufrufe Ihre Anbindung nutzt, und stelle sie nach Aufwand und Risiko um.

#Was passiert, wenn meine Anbindung eine abgelaufene API-Version anfragt?

Shopify beantwortet die Anfrage mit der ältesten noch zugänglichen stabilen Version. Das Verhalten kann sich dadurch ändern, ohne dass ein Fehler auftritt. Deshalb prüft meine Anbindung den Antwort-Header X-Shopify-API-Version.

#Wie viele Anfragen pro Sekunde darf ein ERP an Shopify schicken?

Das hängt nicht an der Zahl der Anfragen, sondern am berechneten Aufwand jeder Abfrage. Bei Standard sind es 100 Punkte pro Sekunde, bei Shopify Plus 1000. Eine einzelne Abfrage darf höchstens 1000 Punkte kosten.

#Reicht ein Webhook, um Bestellungen sicher ins ERP zu bekommen?

Nein. Shopify versucht eine fehlgeschlagene Zustellung achtmal in vier Stunden und liefert Webhooks gelegentlich doppelt. Dazu gehören Signaturprüfung, Duplikaterkennung und ein Abgleichslauf, der Lücken schließt.

#Wann nehme ich Bulk Operations statt normaler Abfragen?

Bei großen Mengen, etwa dem vollständigen Katalog oder allen Varianten für einen Abgleich. Bulk Operations unterliegen den Aufwandsgrenzen einzelner Abfragen nicht und liefern das Ergebnis als JSONL-Datei.

#Arbeiten Sie vor Ort in Essen?

Ich arbeite remote und per Dokument. Abstimmung läuft per E-Mail, Ergebnis ist ein schriftlicher Umfang.

#Wie starte ich mit Ihnen?

Schicken Sie mir die URL Ihres Shops, den Namen Ihres ERP oder Ihrer Warenwirtschaft, die Frage, welches System Bestand und Bestellstatus führt, und Ihren Zeitrahmen. Daraus erstelle ich einen schriftlichen Umfang mit Schnittstellen, Risiken und Reihenfolge der Arbeiten. Die erste Einschätzung zu Ihrer Anbindung bekommen Sie schriftlich und ohne Rechnung. Der Weg dorthin ist das Kontaktformular. Einen Überblick über meine Shopify-Leistungen gibt die Seite Shopify-Entwickler.