Headless mit der Shopify Storefront API

Die Shopify Storefront API ist die technische Grundlage jedes Headless-Projekts mit Shopify. Sie trennt das Commerce-Backend von Shopify vom Frontend, das du selbst baust. Was auf den ersten Blick nach maximaler Flexibilität klingt, bringt echten Aufwand mit sich. Dieser Artikel erklärt, was die Storefront API leistet, wie sie sich von anderen Shopify-APIs unterscheidet und wann ein direkter API-Ansatz Sinn ergibt.

Was ist die Shopify Storefront API?

Die Storefront API ist eine öffentliche GraphQL-Schnittstelle, die Shopify für jeden Shop bereitstellt. Über sie kannst du Produktdaten, Kollektionen, Warenkorb-Operationen und mehr abrufen, ohne ein Liquid-Theme zu verwenden. Das Frontend liegt dann vollständig außerhalb von Shopify: als Next.js-App, als Astro-Seite, als native Mobile-App oder als Teil eines Content-Management-Systems.

Die API läuft ausschließlich über GraphQL, ein REST-Äquivalent gibt es nicht. Das bedeutet: Du beschreibst in jeder Anfrage genau, welche Felder du brauchst. Du bekommst kein Overfetching, keine unnötigen Daten. Das ist effizient, erfordert aber Vertrautheit mit GraphQL.

Gegenüber der Shopify Admin API (GraphQL) gibt es einen zentralen Unterschied: Die Storefront API ist für öffentliche Clients gedacht. Der Zugriffstoken ist sicher im Browser-Code einsetzbar, da er nur Lesezugriff auf öffentliche Daten und Schreibzugriff auf Warenkorb-Operationen gewährt. Die Admin API bleibt für serverseitige Backend-Operationen.

Authentifizierung und Rate Limiting

Für den Zugriff brauchst du einen Storefront Access Token. Den erzeugst du im Shopify-Admin unter “Apps und Vertriebskanäle” oder programmatisch über die Admin API (Mutation storefrontAccessTokenCreate). Dieser Token gehört in deinen Frontend-Code, da er bewusst öffentlich ist.

Ohne Token ist der Zugriff auf öffentliche Daten eingeschränkt möglich, mit einem Komplexitätslimit von 1.000 Cost Units pro Anfrage, berechnet wie bei der GraphQL Admin API. Mit gültigem Storefront Access Token unterliegt echter Buyer-Traffic keiner festen Request-pro-Minute-Grenze. Shopify drosselt stattdessen automatisierten Bot- und Crawler-Traffic. Für hochvolumige Storefronts ist die API damit sehr großzügig dimensioniert.

Customer Account API: der wichtigste Wechsel 2026

Wenn du Kundenauthentifizierung in dein Headless-Frontend integrieren willst, solltest du auf die Customer Account API setzen. Shopify hat die Legacy-Customer-Mutations der Storefront API (unter anderem customerAccessTokenCreate) als deprecated markiert. Die passwortbasierte Variante wurde bereits mit API-Version 2025-04 entfernt. Ein finales Abschaltdatum für den Rest steht noch aus, Nachfolger ist die Customer Account API mit OAuth 2.0 und PKCE.

Das neue System funktioniert per PKCE-Flow (Proof Key for Code Exchange), gibt kurzlebige Access Tokens mit einer Stunde Laufzeit aus und liefert Refresh Tokens für automatische Erneuerung. Der Vorteil: sicherer als die bisherige Token-Mechanik. Der Nachteil: komplexer zu implementieren, vor allem wenn dein Team noch keine OAuth-Erfahrung hat.

Wer jetzt ein Headless-Projekt plant, sollte die Customer Account API von Anfang an einplanen. Nachträgliche Migration kostet Zeit.

Storefront API direkt oder Hydrogen?

Hier liegt eine Entscheidung, die viele Projekte unterschätzen. Shopify Hydrogen und Oxygen sind Shopifys eigenes Headless-Framework und Hosting-Stack. Hydrogen bringt fertige Commerce-Komponenten, ein durchdachtes Caching-System und direkte Storefront-API-Integration mit. Für commerce-first Projekte ist Hydrogen 2026 die vernünftige Standardwahl.

Die Storefront API direkt verwenden, ohne Hydrogen, ergibt Sinn in diesen Szenarien:

• Das Frontend basiert auf einem Framework mit eigenem Ökosystem (Next.js, Astro, Nuxt, native Mobile-App), das du aus Content- oder Infrastrukturgründen bevorzugst.
• Shopify ist nur eines von mehreren Commerce-Systemen, die du ansprechen musst.
• Du hast ein bestehendes Frontend, das du um Shopify-Commerce ergänzen willst, ohne alles neu zu bauen.
• Deine Hosting- und CI/CD-Anforderungen verlangen eine Lösung außerhalb von Oxygen.

Wenn kein konkreter Grund gegen Hydrogen spricht, lohnt sich der direkte API-Pfad nicht. Du baust dann Dinge, die Hydrogen bereits löst.

Typische Abfragen in der Praxis

Ein einfaches Beispiel aus einem Kundenprojekt: Produktlisting mit Paginierung und Filterung. Die Storefront API liefert dafür Cursor-based Pagination über pageInfo { hasNextPage, endCursor }. Das klingt nach mehr Code als bei klassischem REST, ist aber deterministischer bei großen Produktkatalogen.

Warenkorb-Operationen laufen über Mutations wie cartCreate, cartLinesAdd und cartLinesUpdate. Der Warenkorb lebt serverseitig als persistentes Shopify-Objekt mit einer eindeutigen ID. Das Frontend speichert diese ID (z.B. im localStorage oder Cookie) und manipuliert den Warenkorb ausschließlich über Mutations.

Produktsuche und Filterung laufen über die search- und collection-Queries, inklusive filters-Argument für Facettenfilterung. Für Shops mit tausenden Produkten ist das leistungsfähig genug. Für komplexe Suchen mit Elasticsearch-ähnlicher Relevanz stößt die native API an Grenzen. Dann kommen externe Search-as-a-Service-Anbieter ins Spiel.

Grenzen und Schwächen ehrlich bewertet

Die Storefront API ist nicht für alles optimiert:

• Checkout-Anpassungen sind über die Storefront API kaum möglich. Wer den Checkout erweitern will, braucht Shopify Functions oder Checkout Extensibility.
• B2B-Funktionen wie Preislisten, Bestellfreigaben und Unterkonten liegen im B2B-Bereich, der separaten Zugriff und Shopify Plus voraussetzt.
• Draftentwürfe, Metafield-Schreiboperationen und Admin-seitige Aktionen gehören zur Admin API, nicht hierher.
• Das Modell “Frontend frei, Shopify-Backend” klingt offen, du bist aber trotzdem an Shopifys Datenmodell gebunden. Wenn dein Produkt nicht ins Shopify-Schema passt, hilft auch die beste API-Integration nicht.

Häufige Fragen

Brauche ich Shopify Plus für die Storefront API?

Nein. Die Storefront API ist für alle Shopify-Pläne verfügbar. Erweiterte Headless-Features wie der native Hydrogen/Oxygen-Stack oder Checkout Extensibility setzen jedoch teilweise Shopify Plus voraus. Die Grundfunktionen, also Produkte, Kollektionen, Warenkorb und Suche, funktionieren auf allen Plänen.

Kann ich die Storefront API mit einem bestehenden Liquid-Theme kombinieren?

Ja. Du kannst einzelne Bereiche eines klassischen Shops headless umsetzen, zum Beispiel einen separaten Headless-Abschnitt für Konfiguratoren oder App-ähnliche Seiten, während der Rest über Liquid läuft. Das sogenannte Hybrid-Headless-Modell ist komplex, aber sinnvoll für Shops, die nicht komplett migrieren wollen.

Wie unterscheidet sich die Storefront API von der Shopify Admin API?

Die Storefront API ist für öffentliche Clients gedacht, der Token darf im Browser liegen. Sie deckt alles ab, was ein Käufer sieht und tut: Produktdaten lesen, Warenkorb befüllen, Bestellprozess starten. Die Admin API ist für serverseitige Apps, erfordert höhere Berechtigungen und deckt Verwaltungsoperationen ab: Bestellungen bearbeiten, Produkte anlegen, Webhooks konfigurieren.

Wie aufwendig ist ein Headless-Projekt mit der Storefront API wirklich?

Ehrlich: mehr als die meisten denken. Du baust nicht nur das Frontend, du trägst auch Verantwortung für Performance, Caching, SEO (Server-Side Rendering oder Static Generation), Authentifizierung und Checkout-Integration. Ein Headless-Projekt kostet typischerweise deutlich mehr als ein klassisches Theme-Projekt. Wenn du die Vorteile nicht klar benennen kannst (Performance-Ziele, Content-Integration, Multi-Channel-Anforderungen), ist Headless wahrscheinlich nicht der richtige Weg.

Weiterführende Unterstützung

Wenn du überlegst, ob ein Headless-Aufbau für deinen Shop Sinn ergibt, hilft ein Shopify Quick-Check dabei, die richtigen Fragen zu stellen. Wer die technische Umsetzung, also API-Integration, Custom-App-Entwicklung oder Verbindung zum ERP-System, in professionelle Hände geben will, findet bei unserer Shopify App-Entwicklung einen erfahrenen Ansprechpartner.