Die Shopify Admin API und GraphQL erklärt

Wenn du Shopify über die Oberfläche hinaus nutzen willst, führt fast kein Weg an der Admin API vorbei. Sie ist die zentrale Schnittstelle für alles, was du programmgesteuert in deinem Shop tun kannst: Produkte anlegen, Bestellungen auslesen, Inventar synchronisieren, Metadaten pflegen. Seit Shopify den Schwerpunkt auf GraphQL verlagert hat, ist das Verständnis dieser Abfragesprache keine optionale Zusatzkompetenz mehr, sondern Grundvoraussetzung für jeden ernsthaften Integrationsauftrag.

Was die Admin API leistet und was nicht

Die Shopify Admin API gibt dir Lese- und Schreibzugriff auf nahezu alle Daten deines Shops, die auch im Backend sichtbar sind. Produkte, Varianten, Bestellungen, Kunden, Fulfillment, Inventar, Metafelder, Discounts, Webhooks, Staffelpreise, B2B-Kataloge (ab Shopify Plus) und vieles mehr lassen sich über sie abfragen und verändern.

Was die Admin API nicht kann: Sie ist kein Werkzeug für Besucher deines Shops. Wer den Storefront gestalten oder Warenkorb-Daten für anonyme Nutzer abrufen will, braucht die Storefront API. Die beiden APIs haben unterschiedliche Zwecke und unterschiedliche Authentifizierungsmodelle.

REST war gestern: Warum Shopify auf GraphQL setzt

Jahrelang gab es zwei Wege, mit der Shopify Admin API zu arbeiten: REST und GraphQL. Seit Oktober 2024 ist die REST Admin API offiziell als Legacy eingestuft. Neue öffentliche Apps müssen seit April 2025 ausschließlich die GraphQL API nutzen. Bestehende Integrationen sollten migriert werden, neue Anbindungen beginnen direkt mit GraphQL.

Der Grund ist strukturell: REST liefert bei einer Bestellabfrage immer einen vollständigen Datensatz zurück, ob du die Adresse brauchst oder nicht. GraphQL hingegen lässt dich exakt definieren, welche Felder zurückgegeben werden sollen. Das reduziert die übertragene Datenmenge, senkt die Auswirkung auf das Rate-Limit und macht den Code lesbarer.

Ein einfaches Beispiel: Du willst aus 50 Bestellungen nur die Bestellnummer und den Gesamtbetrag. Per REST bekommst du 50 vollständige Objekte mit Dutzenden Feldern. Per GraphQL beschreibst du die Abfrage so:

{
  orders(first: 50) {
    edges {
      node {
        name
        totalPriceSet {
          shopMoney {
            amount
            currencyCode
          }
        }
      }
    }
  }
}

Nur diese Felder kommen zurück. Sauberer, sparsamer, schneller.

Authentifizierung: Offline- und Online-Token

Bevor ein API-Aufruf funktioniert, muss die App sich ausweisen. Shopify unterscheidet dabei zwischen zwei Token-Typen:

Offline-Token (auch Admin API Access Token genannt) sind dauerhaft gültig und werden für Hintergrundprozesse verwendet, also für Synchronisierungen, Cron-Jobs oder Webhooks, die ohne aktive Nutzersession laufen.

Online-Token sind an eine Nutzersession gebunden und laufen ab. Sie kommen zum Einsatz, wenn eine App im Auftrag eines bestimmten Shop-Mitarbeiters handelt und das Berechtigungsmodell auf Mitarbeiterebene greifen soll.

Für die meisten Custom-App-Szenarien, etwa eine ERP-Anbindung oder ein Daten-Synchronisierungstool, reicht ein Offline-Token. Dieser wird beim Installationsprozess der App generiert und liegt sicher beim App-Backend.

Bei der Konfiguration musst du außerdem die Access Scopes festlegen: Das sind granulare Berechtigungen, die bestimmen, auf welche Ressourcen die App zugreifen darf. read_orders, write_products, read_inventory sind typische Beispiele. Nur anfordern, was wirklich gebraucht wird. Shopify prüft das, und im Review-Prozess für öffentliche Apps wird unnötig breiter Scope-Zugriff als Qualitätsproblem bewertet.

Rate Limits: Wie das Kostensystem funktioniert

Die GraphQL Admin API arbeitet mit einem berechneten Kostensystem statt mit simplen Request-Zählern. Jede Abfrage hat eine berechnete Kosten-Punktzahl, die davon abhängt, wie viele Felder und Verbindungen du abfragst. Pro Minute steht dir ein Kontingent zur Verfügung, das sich automatisch regeneriert.

Komplexe Abfragen mit vielen verschachtelten Objekten kosten mehr Punkte als einfache Abfragen. Wer eine einzelne Order mit allen Line Items, zugehörigen Produktvarianten und Fulfillment-Details auf einmal abfragt, nähert sich dem Limit schneller als jemand, der dieselbe Information in zwei schlankere Abfragen aufteilt.

Shopify liefert in der API-Antwort Metadaten zum aktuellen Punktestand zurück. Diese solltest du in deiner App aktiv auswerten und bei Bedarf einen kurzen Backoff-Mechanismus einbauen. Ohne das läufst du bei intensiven Synchronisierungen in Rate-Limit-Fehler, die dann in der Agenturpraxis schwer zu debuggen sind.

Der HTTP-Header Shopify-GraphQL-Cost-Debug: 1 in der Anfrage liefert zusätzlich eine detaillierte Aufschlüsselung, welches Feld wie viele Punkte kostet. Ein nützliches Werkzeug beim Optimieren teurer Abfragen.

Versioning: Quartalsweise Releases, ein Jahr Stabilität

Shopify veröffentlicht vier API-Versionen pro Jahr, jeweils zum Quartalsstart. Die Versionsnummern folgen dem Schema YYYY-MM, also etwa 2026-04. Jede stabile Version wird mindestens zwölf Monate lang unterstützt, mit mindestens neun Monaten Überlappung zur nachfolgenden Version.

Was das praktisch bedeutet: Du hast nach dem Release einer neuen Version ausreichend Zeit, deine Integrations-Abhängigkeiten zu prüfen und bei Bedarf zu migrieren. Wer auf einer veralteten Version bleibt, riskiert irgendwann einen erzwungenen Upgrade, der mehr Aufwand bedeutet als kontinuierliche Pflege.

Für Custom Apps in Shopify empfiehlt sich daher ein jährliches API-Review als fester Bestandteil der Wartungsroutine. Neue Features, darunter ab Version 2026-04 unter anderem scopefreie App-eigene Metaobjekte, sind oft nur in aktuellen Versionen verfügbar.

Praxiseinsatz: Typische Anwendungsfälle aus der Agenturarbeit

In der täglichen Arbeit begegnen uns diese Szenarien am häufigsten:

• ERP-Synchronisierung: Bestellungen werden per Webhook ausgelöst und dann per Admin API angereichert, etwa um Fulfillment-Status zurückzuschreiben. Hier ist ein sauberes Offline-Token-Handling und ein robustes Retry-Konzept entscheidend.
• Produktdaten-Import: Tausende Produkte aus einem PIM-System landen via productCreate und productVariantsBulkCreate in Shopify. Batch-Operationen und Mutations mit mehreren Objekten auf einmal schonen das Rate-Limit erheblich.
• Metafield-Pflege: Technische Produktdaten, Zertifikate oder individuelle Attribute werden als Metafields gespeichert und über die API gepflegt. Mit den strukturierten Metaobject-Typen (ab 2023 eingeführt) sind auch komplexere Datenstrukturen sauber abbildbar.
• Inventar-Abgleich: Bei Multi-Location-Setups müssen Lagerbestände standortgenau geschrieben werden. Die inventoryAdjustQuantities-Mutation ist hier der richtige Einstiegspunkt.

Für alles, was über einfache Shop-Daten hinausgeht und externe Systeme verbindet, lohnt ein Blick auf unsere Schnittstellen-Entwicklung.

Häufige Fragen

Kann ich die Admin API ohne App-Entwicklungskenntnisse nutzen?

Für einfache, manuelle Abfragen gibt es Tools wie Shopify’s eigenen GraphiQL-Explorer, der direkt im Partnerdashboard verfügbar ist. Damit kannst du Abfragen testen und verstehen, ohne eine App zu deployen. Für produktive Automatisierungen brauchst du allerdings ein Backend, das die Tokens sicher verwaltet und die API programmgesteuert aufruft.

Brauche ich Shopify Plus für die Admin API?

Nein. Die Admin API steht auf allen Shopify-Plänen zur Verfügung. Einige Ressourcen, etwa B2B-Kataloge oder bestimmte Checkout-Extensibility-Features, sind jedoch Plus-exklusiv. Das betrifft nicht die API an sich, sondern die Daten, auf die zugegriffen werden kann. Die Shopify Plus-Seite gibt einen Überblick, welche Features nur auf Enterprise-Stufe verfügbar sind.

Was ist der Unterschied zwischen Admin API und Storefront API?

Die Admin API erfordert Authentifizierung und ist für Backend-Prozesse gedacht: Bestellverwaltung, Inventar, Kundendaten, Produkte. Die Storefront API ist für öffentlich zugängliche Frontends, etwa Headless-Shops oder native Apps, die den Einkaufsprozess für Endkunden abbilden. Beide APIs haben unterschiedliche Scopes, Rate-Limit-Modelle und Anwendungsfelder.

Was passiert, wenn ich eine veraltete API-Version verwende?

Shopify kündigt Deprecations mit ausreichend Vorlauf an und setzt veraltete Versionen nach Ende der Supportperiode außer Betrieb. Anfragen auf einer nicht mehr unterstützten Version werden abgelehnt. Shopify schickt außerdem Deprecation-Warnungen im Response-Header, bevor eine Version abgekündigt wird. Diese solltest du im Logging deiner App aktiv erfassen.

---

Wenn du eine neue Shopify-Integration planst oder eine bestehende REST-Anbindung auf GraphQL migrieren willst, schau dir gern unsere Leistungsseite zu Shopify an. Wir begleiten solche Projekte von der API-Konzeption bis zum laufenden Betrieb, inklusive Monitoring und API-Versionspflege im Rahmen einer Shopify-Betreuung.