Shopify GraphQL: Der komplette Guide fuer Entwickler und Shop-Betreiber (2026)

Was ist Shopify GraphQL?

GraphQL ist eine Abfragesprache fuer APIs, die Facebook 2015 als Open-Source-Projekt veroeffentlicht hat. Der Kerngedanke: du definierst exakt, welche Daten du brauchst, und bekommst genau diese zurueck. Nicht mehr, nicht weniger. Bei einer klassischen REST API fragst du einen festen Endpunkt ab und erhaeltst eine vordefinierte Datenstruktur, oft mit Feldern, die du gar nicht brauchst.

Shopify hat 2018 begonnen, GraphQL als API-Standard einzufuehren. Seit Oktober 2024 gilt die REST Admin API offiziell als Legacy. Seit April 2025 muessen alle neuen oeffentlichen Apps im Shopify App Store ausschliesslich die GraphQL Admin API nutzen. Das ist keine optionale Empfehlung, sondern eine klare Richtung.

Fuer Shop-Betreiber und Entwickler bedeutet das: Wer mit der Shopify API arbeiten will, kommt an GraphQL nicht mehr vorbei. Die gute Nachricht: GraphQL ist nach der ersten Lernkurve deutlich effizienter als REST. Eine Anfrage statt fuenf, praezise Daten statt aufgeblaehter Antworten.

GraphQL vs REST bei Shopify

Die Entscheidung zwischen GraphQL und REST ist bei Shopify keine Frage mehr. Sie ist gefallen. Trotzdem hilft der direkte Vergleich, um zu verstehen, warum Shopify diesen Weg geht und wo die praktischen Unterschiede liegen.

Der wichtigste Unterschied in der Praxis: Overfetching. Wenn du per REST die Bestellungen eines Kunden abfragst, bekommst du jedes Mal die komplette Bestellstruktur. Bei GraphQL gibst du in der Query an, dass du nur Bestellnummer, Datum und Gesamtsumme brauchst. Das spart Bandbreite, reduziert Ladezeiten und macht deine Anwendung effizienter.

Shopify GraphQL Admin API einrichten

Ich habe letzte Woche mit einem Shopify-Haendler gesprochen, der dachte, GraphQL sei nur fuer grosse Entwicklerteams. Er hatte seine erste Query nach 20 Minuten laufen. Der Einstieg ist einfacher, als die meisten denken.

Fuer die Shopify GraphQL Admin API brauchst du drei Dinge: einen Shopify-Shop mit einem Custom-App-Zugang, einen Admin API Access Token und einen HTTP-Client. Shopify bietet zusaetzlich den GraphiQL Explorer direkt im Admin-Bereich an, perfekt zum Testen.

Der GraphQL-Endpunkt fuer die Admin API folgt diesem Schema:

Hier eine erste einfache Query mit curl, die deine Shop-Informationen abruft:

Die wichtigsten Queries und Mutations

GraphQL unterscheidet zwischen Queries (Daten lesen) und Mutations (Daten aendern). In der Praxis wirst du beide taeglich brauchen. Hier sind die Abfragen, die ich in fast jedem Shopify-Projekt als erstes einrichte.

Produkte abfragen

Diese Query holt die ersten 10 Produkte mit jeweils bis zu 5 Varianten. Du erhaeltst ID, Titel, Status, Preis, Lagerbestand und SKU. Bei REST muesstest du zuerst die Produkte abfragen, dann fuer jedes Produkt die Varianten separat laden.

Bestellungen abfragen

Bestellungen, Kundendaten und Preise in einer Anfrage. sortKey und reverse sortieren nach Erstelldatum absteigend. Das ist die Art von Effizienz, die man nach der Umstellung nicht mehr missen moechte.

Ein Produkt erstellen (Mutation)

Mutations geben immer ein userErrors-Array zurueck. Das ist kein optionales Feature, sondern dein primaerer Fehlerkanal. Wenn userErrors leer ist, war die Operation erfolgreich. Wenn nicht, sagt dir das message-Feld genau, was schiefgelaufen ist.

Paginierung und grosse Datenmengen

Shopify GraphQL nutzt Cursor-basierte Paginierung. Das bedeutet: du bekommst nicht Seite 1, 2, 3, sondern einen Cursor, der auf den naechsten Datensatz zeigt. Das ist zuverlaessiger als Offset-Paginierung, besonders bei grossen und sich aendernden Datensaetzen.

pageInfo.hasNextPage sagt dir, ob weitere Daten existieren. pageInfo.endCursor ist der Wert, den du als after-Parameter in der naechsten Anfrage uebergibst. So iterierst du durch den gesamten Datenbestand.

Rate Limits und Performance

Shopify berechnet Rate Limits nicht nach Anzahl der Anfragen, sondern nach den Kosten jeder Query. Jede Query hat einen berechneten Kostenwert, der sich aus der Anzahl der abgefragten Objekte und Verbindungen ergibt. Das System heisst Calculated Query Cost.

Die Kosten einer Query werden vor der Ausfuehrung berechnet (requestedQueryCost). Nach der Ausfuehrung wird der tatsaechliche Verbrauch ermittelt (actualQueryCost). Die Differenz wird zurueckerstattet. Du kannst die Kosten jeder Query im Voraus optimieren, indem du nur die Felder abfragst, die du wirklich brauchst.

Schicke den Header Shopify-GraphQL-Cost-Debug: 1 mit, um eine detaillierte Aufschluesselung der Kosten pro Feld zu erhalten. Das ist der schnellste Weg, teure Queries zu identifizieren und zu optimieren.

Storefront API mit GraphQL

Neben der Admin API bietet Shopify eine zweite GraphQL-Schnittstelle: die Storefront API. Die Storefront API ist fuer kundenseitige Anwendungen gedacht, also Custom Storefronts, Mobile Apps, IoT-Geraete oder Headless-Commerce-Projekte mit Shopify Hydrogen.

Fuer Headless-Commerce-Szenarien ist die Kombination aus Storefront API, Hydrogen und Shopify Oxygen der von Shopify empfohlene Stack. Die Storefront API hat bewusst keine Anfrage-Rate-Limits, um auch Traffic-Spitzen wie Flash Sales abzufangen.

GraphQL in der Praxis: Automatisierung mit KI

Oeffne das Dashboard eines mittelstaendischen Garten-Onlineshops und du siehst, warum manuelle API-Aufrufe nicht skalieren. Hunderte Produkte, taegliche Bestandsaenderungen, saisonale Preisanpassungen. Genau hier wird GraphQL in Kombination mit KI-Mitarbeitern richtig stark.

Ein KI-Mitarbeiter kann ueber die GraphQL Admin API automatisch Produktdaten abfragen, um Kunden in Echtzeit zu beraten. Er kennt Lagerbestaende, Preise, Varianten und Verfuegbarkeiten, ohne dass ein Mensch diese Daten manuell pflegen muss. Bei einem unserer Kunden steigerte das den Warenkorbwert um 35%, weil die Produktberatung ploetzlich auf tatsaechlichen Live-Daten basierte.

Die Verbindung funktioniert auch in die andere Richtung: Shopify Webhooks koennen als Trigger dienen, um GraphQL-Mutations automatisch auszuloesen. Neue Bestellung eingegangen? Der KI-Mitarbeiter prueft per GraphQL den Lagerbestand und aktualisiert die Verfuegbarkeit. Kundenrueckfrage per WhatsApp? Der KI-Mitarbeiter holt per Query die Bestelldaten und antwortet in Sekunden.

Haeufige Fehler und Troubleshooting

Nach hunderten GraphQL-Integrationen kenne ich die fuenf Fehler, die fast jeder Entwickler am Anfang macht. Hier sind sie, mit der jeweiligen Loesung.

1. Authentifizierungsfehler (401): Der X-Shopify-Access-Token Header fehlt oder ist ungueltig. Pruefen, ob der Token korrekt kopiert wurde und die App installiert ist.
2. Fehlende Scopes (403): Die App hat nicht die benoetigten API-Berechtigungen. Im Shopify Admin unter App-Einstellungen die fehlenden Scopes hinzufuegen und den Token neu generieren.
3. Query-Syntax-Fehler: GraphQL ist streng typisiert. Ein fehlendes Komma oder eine falsche Verschachtelung fuehrt sofort zu einem Parsing-Fehler. Nutze den GraphiQL Explorer zum Testen, bevor du Queries in den Code uebernimmst.
4. Rate-Limit-Ueberschreitung (THROTTLED): Die Query-Kosten uebersteigen das verfuegbare Budget. Reduziere die Anzahl der abgefragten Objekte pro Query oder nutze Bulk Operations fuer grosse Datensaetze.
5. Typ-Fehler bei Mutations: Falsche Eingabetypen, zum Beispiel ein String statt einer ID oder ein fehlender Pflichtparameter. Pruefe die userErrors im Response, dort steht das betroffene Feld und die Fehlermeldung.

FAQ