Shopify Storefront API: Der vollständige Leitfaden für Entwickler und Merchants

Die Shopify Storefront API ist eine öffentliche GraphQL-API, mit der Sie vollständig benutzerdefinierte Kauferlebnisse erstellen können - von Headless-Storefronts und Mobile Apps bis hin zu IoT- und AI-Agent-Integrationen. Shopify kümmert sich um das Commerce-Backend. Im Gegensatz zur Admin API ist sie dafür ausgelegt, sicher von Browsern und mobilen Clients aus aufgerufen zu werden. Wenn Sie sie gerade für ein Projekt evaluieren, ist die aktuelle stabile Version 2026-04 und ein Release Candidate 2026-07 ist bereits zum Testen verfügbar.

Wichtigste Erkenntnisse

• Die Storefront API ist öffentlich und kann sicher client-seitig aufgerufen werden. Die Admin API muss auf einem sicheren Server bleiben.
• Cart-Mutationen (cartCreate, cartLinesAdd, cartBuyerIdentityUpdate) sind die zentralen Schreibvorgänge, die jeder Build benötigt.
• API-Versionen folgen einem vierteljährlichen Rhythmus: 2026-01, 2026-04, 2026-07, 2026-10. Die alte Version 2024-10 wird im Oktober 2026 eingestellt.
• Hydrogen 2026.4.0 machte den Storefront API-Proxy erforderlich und aktivierte standardmäßig den Backend-Consent-Modus. Zwei Breaking Changes, die vor dem Upgrade ein Audit erfordern.
• Seit Hydrogen 2026.1.4 stellt jeder Hydrogen-Storefront auf Oxygen automatisch einen MCP-Endpoint unter /api/mcp bereit, was ihn zu einem AI-Agent-ready Commerce-Endpoint mit null benutzerdefinierten Code macht.

Was ist die Shopify Storefront API?

Die Storefront API ist Shopifys kundenorientierte GraphQL-API. Sie gibt Entwicklern Lesezugriff auf Produkte, Sammlungen, Metaobjects und Menus, sowie Schreibzugriff für die zwei Dinge, die Käufer tatsächlich tun: einen Warenkorb verwalten und sich als Kunde authentifizieren.

So definiert Shopifys Dokumentation das Zugangsmodell: Die Storefront API ist primär schreibgeschützt, mit Ausnahme von Authentifizierung und Verwaltung eines Warenkorbs. Diese Grenze ist absichtlich. Sie können jeden Produktdetail abrufen, eine Live-Filter-UI erstellen und einen kompletten Checkout-Flow konstruieren, ohne jemals ein geheimes Credential zu verwenden.

Das Endpoint-Muster ist einfach:

https://{dein-shop}.myshopify.com/api/2026-04/graphql.json

Jede Anfrage benötigt einen Shopify-Storefront-Public-Token-Header (oder das private-token-Äquivalent für serverseitige Hydrogen-Aufrufe). Das Token ist nicht geheim und kann in Browser- oder Mobile-Code eingebettet werden. Dein Admin API-Schlüssel und Passwort dürfen dagegen niemals in client-seitigem Code erscheinen.

Storefront API vs. Admin API: Der echte Unterschied

Das ist die Frage, die jeder Merchant und Entwickler zuerst stellt, und die Antwort ist architektonisch, nicht nur eine Funktionsliste.

Die Admin API bietet dir vollständigen Lese- und Schreibzugriff auf deine Shopify-Shop-Daten: Bestellungen, Kunden, Produkte, Inventar, Fulfillment, Analytics und mehr. Die Storefront API fehlen absichtlich diese administrativen Funktionen. Du kannst Bestellungen nicht ändern, Inventar nicht verwalten oder auf interne Analytics zugreifen. Das ist nicht eine Einschränkung, die man umgehen muss. Es ist die Sicherheitsgrenze, die es dir ermöglicht, das Token sicher in eine React-Komponente einzubetten.

Ein häufiger Fehler: Verwendung von Admin API-Credentials in client-seitigem Code. Das setzt deine Shop-Credentials der Öffentlichkeit aus. Halte Admin API-Aufrufe immer auf einem sicheren Backend-Server. Wenn du client-seitigen Zugriff auf Shop-Daten benötigst, ist genau dafür die Storefront API gedacht.

Kernfunktionalitäten: Was du tatsächlich erstellen kannst

Produkt- und Sammlungsabfragen

Rufe Produkttitel, Beschreibungen, Varianten-Preise, Bestandsstatus, Bilder und Metafields ab. Da GraphQL es dir ermöglicht, nur die benötigten Felder anzufordern, kann eine Produktkarten-Abfrage eine schlanke 3-Feld-Antwort statt einer aufgeblähten REST-Payload zurückgeben. Die Geschwindigkeit und Effizienz, nur die angeforderten Daten zu erhalten, macht sie ideal für performancesensitive Anwendungen.

Eine wichtige kürzliche Änderung: GraphQL-Produktvarianten unterstützen jetzt bis zu 2.000 pro Produkt, erweitert von der bisherigen 100-Varianten-Obergrenze. Wenn du konfigurierbare Produkte verkaufst (Größe x Farbe x Material), ist das relevant.

Cart-Mutationen

Das Cart-Objekt ist das Herz jedes Storefront API-Builds. Die aktuelle Mutations-Oberfläche umfasst:

• cartCreate, erstelle einen neuen Warenkorb und füge optional ein Zeilenelement in einem Aufruf hinzu
• cartLinesAdd, füge eine oder mehrere Produktvarianten zu einem vorhandenen Warenkorb hinzu
• cartLinesUpdate, aktualisiere die Menge auf vorhandenen Zeilen (akzeptiert bis zu 250 Werte pro Aufruf)
• cartLinesRemove, entferne Zeilen nach ID
• cartDiscountCodesUpdate, wende Rabattcodes an oder lösche sie (ersetzt alle vorhandenen Codes durch die bereitgestellte Liste)
• cartGiftCardCodesAdd / cartGiftCardCodesRemove, verwalte die Geschenkgutschein-Einlösung
• cartBuyerIdentityUpdate, verknüpfe einen angemeldeten Kunden, lege einen B2B-Firmenstandort fest oder konfiguriere Checkout-Vorlieben wie Lieferart
• cartMetafieldsSet, schreibe beliebige Metafields in den Warenkorb für benutzerdefinierte Checkout-Logik

Eine bemerkenswerte kürzliche Addition: Der CartLine-Typ gibt jetzt ein viewKey-Feld zurück, sodass du zurückgegebene Zeilen mit dem view_key korrelieren kannst, der an cartLinesUpdate und cartLinesRemove gesendet wird. Nützlich beim Erstellen von optimistischen UI-Updates.

Datenschutzkonforme Zustimmung

Seit der Storefront API-Version 2025-10 und später akzeptiert die @inContext-Direktive ein visitorConsent-Argument. Dies ermöglicht es dir, den Zustimmungsstatus direkt in den Cart-Creation-Aufruf zu codieren und ihn automatisch in die resultierende checkoutUrl einzubeziehen. Das Ergebnis: GDPR- und CCPA-Compliance-Flows ohne separate Cookie-Schreibschicht.

Metaobjects und Token-gated Access

Einige Funktionen erfordern Token-basierte Authentifizierung über den öffentlichen Zugangstoken hinaus. Produkttags, Metaobjects, Metafields, Shop-Navigationsmenus und Kundendaten sitzen alle hinter token-scoped Access. Das Anfordern dieser Scopes wird durchgeführt, wenn du die Storefront API-App im Shopify-Admin erstellst.

API-Versionierung: Was Merchants und Entwickler verfolgen müssen

Die Shopify Storefront API folgt einem vierteljährlichen Release-Rhythmus: Versionen heißen 2026-01, 2026-04, 2026-07 und 2026-10. Jede Version wird 12 Monate nach ihrer Veröffentlichung unterstützt. Aufrufe von nicht unterstützten API-Versionen führen dazu, dass Apps delisted oder von der Installation blockiert werden.

Die Schlüsseldaten sind derzeit:

• 2026-04 ist die aktuelle stabile (neueste) Version.
• 2026-07 ist der Release Candidate, gebunden an Shopifys Summer 2026 Edition (Codename Compass), die 65 Produktupdates mit Breaking Changes in Cart- und Product-Abfrage-Strukturen ausliefert.
• 2024-10 wird im Oktober 2026 eingestellt. Wenn dein Headless-Build noch auf dieser Version läuft, hast du eine begrenzte Laufzeit zur Migration.

Die 2026-07 Breaking Changes beeinflussen jeden Headless-Build, Hydrogen, Next.js Commerce, Nuxt oder vollständig benutzerdefiniert. Shopify bietet Codemods für Hydrogen-Projekte an, um die Abfragemigrationen zu automatisieren.

Für Merchants, die evaluieren, ob sie jetzt handeln sollen: Wenn du einen benutzerdefinierten Headless-Build auf einer beliebigen Version älter als 2025-04 betreibst, plane in diesem Quartal ein Versions-Audit mit deinem Entwickler. Besuche unsere Shopify Developer Services-Seite, um zu sehen, woraus ein Versions-Audit typischerweise besteht.

Die Hydrogen-Verbindung: Storefront API-Proxy ist jetzt erforderlich

Hydrogen ist Shopifys React-basiertes Framework, das direkt auf der Storefront API aufgebaut ist, und 2026 wurde die Beziehung zwischen den beiden erheblich enger.

Hydrogen 2026.4.0 (veröffentlicht 17. April 2026) führte zwei Breaking Changes ein:

1. Der Storefront API-Proxy ist jetzt immer aktiviert. Die proxyStandardRoutes-Konfigurationsoption wurde entfernt. Wenn ein Request Handler ohne eine Storefront-Instanz im Load Context läuft, wirft er einen Runtime Error. Jede benutzerdefinierte Hydrogen-Setup, die den Proxy umgangen hat, muss aktualisiert werden.
2. Backend Consent Mode ist jetzt der Standard. Hydrogen verlässt sich nicht mehr auf das client-seitige _tracking_consent-Cookie. Zustimmung wird jetzt durch vom Server gesetzte Cookies verwaltet, die über den Storefront API-Proxy geschrieben werden. Benutzerdefinierte Zustimmungs-Banner, die document.cookie auf _tracking_consent überprüfen, sehen nach dem Upgrade einen leeren Wert.

Der Grund, warum diese zwei Changes gekoppelt sind: Der ganze Sinn des Backend Consent Mode ist, dass Zustimmungs-Schreibvorgänge nicht stillschweigend fehlschlagen können, wenn ein Proxy fehlt. Der Proxy wird erforderlich war die Voraussetzung.

Wenn du eine benutzerdefinierte Hydrogen-Setup betreibst (ein beliebiges Projekt, das kein sauberes create-hydrogen-Skeleton ist), überprüfe deine createRequestHandler-Aufrufe und Zustimmungs-Banner-Logik vor dem Upgrade auf 2026.4.x.

Die größte Verschiebung 2026: Dein Storefront ist jetzt ein AI Agent Endpoint

Das ist die Entwicklung, die die Rolle der Storefront API am fundamentalsten verändert.

Hydrogen 2026.1.4 fügte eingebaute Storefront MCP (Model Context Protocol) Proxy-Unterstützung hinzu. Jeder Hydrogen-Store auf Oxygen stellt jetzt einen MCP-Endpoint unter /api/mcp mit null benutzerdefinierten Setup bereit. Was das praktisch bedeutet: AI-Assistenten wie ChatGPT, Perplexity und benutzerdefinierte Shopping-Agenten können deine Produkte entdecken, Warenkorbe verwalten und Käufer durch den Checkout mit natürlicher Sprache führen, powered durch Echtzeit-Daten aus der Storefront API.

Shopify stellt drei unterschiedliche MCP-Oberflächen bereit:

• Catalog MCP, globale Produktentdeckung über Shopify-Merchants
• Storefront MCP, Merchant-spezifische Suche, Richtlinien und FAQs
• Checkout MCP, programmgesteuerte Cart-Erstellung, Updates und Checkout-Fertigstellung

Öffentliche Produktentdeckung durch Storefront MCP erfordert keine zusätzliche Authentifizierung. Authentifizierte Cart-Operationen verwenden den bestehenden Shopify-Storefront-Private-Token-Header, den deine Hydrogen-App bereits sendet.

Um zu überprüfen, ob der Proxy auf deinem Store aktiv ist: Rufe /api/mcp auf deiner Oxygen-Deployment auf. Wenn es zu Shopifys Storefront MCP-Server weitergeleitet wird, bist du live.

Für Merchants, die noch nicht auf Hydrogen sind, ist dies ein konkreter Grund, die Migration zu evaluieren. Liquid-Themen auf Shopifys CDN liefern konsistente, aber feste Performance. Hydrogen auf Oxygen liefert diese Performance-Basislinie plus AI Agent Integration ohne Verschlechterung. Die ROI-Berechnung für AI Commerce Features verschiebt sich zu Hydrogens Gunsten. Du kannst erkunden, was eine Hydrogen-Migration beinhaltet, auf unserer Shopify Headless Developer Seite.

Praktische Checkliste für Merchants und Entwickler

Wenn du einen Hydrogen Storefront betreibst:

• Bestätige, dass du auf Storefront API 2026-04 (dem aktuellen Neuesten) bist
• Überprüfe createRequestHandler auf die jetzt entfernte proxyStandardRoutes-Option
• Überprüfe, dass dein Zustimmungs-Banner vom Server gesetzte Cookies liest, nicht _tracking_consent
• Teste /api/mcp auf deiner Oxygen-Deployment, um zu bestätigen, dass MCP aktiv ist
• Starte jetzt mit Tests gegen den 2026-07 Release Candidate. Warte nicht bis Oktober.

Wenn du einen benutzerdefinierten Headless-Build betreibst (Next.js, Nuxt, etc.):

• Identifiziere deine aktuelle API-Version und prüfe sie gegen das Oktober 2026 Sunset von 2024-10
• Überprüfe das 2026-07 Changelog auf Breaking Changes in Cart- und Product-Abfrage-Strukturen
• Plane Codemods oder manuelle Abfrage-Updates vor dem nächsten Shopify Editions Zyklus

Wenn du ein Standard Liquid-Theme betreibst:

• Die Storefront API ist immer noch relevant, wenn du eine Drittanbieter-App verwendest, die sie client-seitig aufruft
• Überprüfe, dass diese Apps auf 2026-04 oder neuer zielen
• Erwäge, ob die AI Agent Capabilities in Hydrogen eine Migrations-Evaluierung rechtfertigen

Die Storefront API ist nicht mehr nur die "Headless Shopify" API. Sie ist die Datenschicht, die deinen Katalog mit jeder Oberfläche verbindet, die ein Käufer verwenden könnte, Browser, Mobile, Voice und jetzt AI Agents. Die Aufrechterhaltung deiner Version und die Ausrichtung deines Hydrogen-Setups mit Shopifys Proxy- und Consent-Anforderungen ist die Wartungsarbeit, die diese Oberflächen offen hält.