Shopify Storefront API: Was sich geändert hat und woran du handeln musst

Die Shopify Storefront API ist eine öffentlich zugängliche GraphQL API, mit der Entwickler vollständig benutzerdefinierte Shopping-Erfahrungen auf jeder Plattform erstellen können, von Headless-Storefronts über Mobile Apps bis zu KI-Agenten. 2026 hat sie schneller entwickelt als je zuvor: Version 2026-04 ist das aktuelle stabile Release, 2026-07 wird heute (30. Juni 2026) als Release Candidate mit Breaking Changes veröffentlicht, und die Version 2024-10 wird im Oktober eingestellt und gibt Teams eine fünfmonatige Frist zur Migration. Wenn dein Headless Store derzeit nicht auf einer unterstützten Version läuft, zählt die Zeit bereits.

Wichtigste Erkenntnisse

• 2026-04 ist die aktuelle stabile Storefront API Version; 2026-07 ist der aktive Release Candidate mit Breaking Changes bei Cart und Product Queries.
• Die Legacy-Version 2024-10 wird im Oktober 2026 eingestellt, benutzerdefinierte Builds erfordern Behebungskosten von 8.000 bis 40.000 Dollar, wenn es zu lange dauert.
• Version 2025-10 führte den Parameter visitorConsent in der Direktive @inContext ein und codiert GDPR/Datenschutz-Zustimmung direkt in die Checkout-URL.
• Ab 2026-07 gibt der Cart die Warnsignale PRODUCT_UNAVAILABLE_IN_BUYER_LOCATION und DELIVERY_SELECTED_OPTION_NOT_AVAILABLE aus, damit deine UI diese Käufern anzeigen kann.
• Die Tools Storefront MCP get_cart/update_cart sind ab sofort zugunsten von UCP Cart MCP veraltet, die alten Tools werden nur bis 31. August 2026 beibehalten.

Das Versionierungsmodell: Wie Shopifys quartalsweiser Release-Zyklus funktioniert

Shopify veröffentlicht alle drei Monate eine neue Storefront API Version, im Januar, April, Juli und Oktober. Jede stabile Version wird während ihrer gesamten Lebensdauer nicht geändert, und jede stabile Version wird mindestens 12 Monate unterstützt, was bedeutet, dass es zwischen zwei aufeinanderfolgenden Releases mindestens neun Monate Überlappung gibt. Diese Überlappung ist dein Migrations-Fenster.

Es gibt drei Spurtypen, die du verstehen solltest:

• Stable (z.B. 2026-04), sicher für die Produktion, garantierte Rückwärtskompatibilität.
• Release Candidate (z.B. 2026-07), veröffentlicht am selben Tag wie das neue stabile Release, jetzt verfügbar zum Testen, aber nicht für die Produktion empfohlen.
• Unstable, kontinuierlich aktualisiert, Features können ohne Ankündigung verschwinden; nur für Entwicklung/Test.

Ein wichtiger Haken: Wenn deine Integration auf eine nicht zugängliche (veraltete) Version abzielt, leitet Shopify stillschweigend weiter und gibt die älteste verfügbare stabile Version zurück. Der Header X-Shopify-API-Version unterscheidet sich von dem, was du angefordert hast, das ist dein Signal, dass du eine nicht unterstützte Version verlassen hast und Risiko für stille Breaking Changes besteht.

Für Apps, die im Shopify App Store veröffentlicht sind, sind die Einsätze höher. Apps, die weiterhin unsupported Ressourcen nach dem Upgrade-Stichtag nutzen, werden aus dem App Store delisted, Benutzer können sie mindestens sieben Tage lang nicht installieren.

API-Versionsvergleich: Stable, Release Candidate und Unstable Spuren

Was sich tatsächlich in 2026-04 geändert hat (die aktuelle stabile Version)

Hydrogen Skeleton erhielt Bump auf 2026-04. Wenn du deine Hydrogen-Konfiguration auf 2026-01 festgelegt hast, musst du aktualisieren. Das Skeleton-Paket (skeleton@2026.4.0) zielt jetzt auf 2026-04 für alle Storefront API und Customer Account API Aufrufe ab.

Metaobject-Zugriff in Shopify Functions. 2026-04 macht es möglich, dass Shopify Functions Metaobject-Daten direkt abfragen. Wenn du Functions-basierte Discount oder Delivery-Logik hast, die von der Laufzeit-Metaobject-Definitionen profitieren könnte, steht dies jetzt zur Verfügung.

JSON-Metafield-Deckel bei 128KB. Starting with API version 2026-04, setzt Shopify JSON-Metafield-Werte auf 128KB begrenzt. Wenn dein Storefront große JSON-Metafelder liest, überprüfe deine Daten jetzt, bevor ein Version-Upgrade Payloads stillschweigend unterbricht.

Die 2026-07 Breaking Changes: Was Headless Builds patchen müssen

Shopifys Summer 2026 Edition (Codename Compass) lieferte 65 Produkt-Updates. Die Storefront API 2026-07 führt Breaking Changes in Cart und Product Query Strukturen ein, die jeden Headless Build betreffen, sei es Hydrogen, Next.js Commerce, Nuxt oder vollständig benutzerdefiniert.

Hier ist, worauf du vor Oktober achten musst:

Cart Warnsignale. Ab 2026-07 gibt das Cart-Objekt zwei neue Warntypen aus:

• PRODUCT_UNAVAILABLE_IN_BUYER_LOCATION, wird ausgelöst, wenn eine Cart-Zeile ein Produkt enthält, das in der Region des Käufers nicht verfügbar ist. Jede betroffene Cart-Zeile gibt ihre eigene Warnung zurück, mit dem target, der auf die Cart Line ID gesetzt ist, damit du sie zurück zur richtigen Zeile in deiner UI zuordnen kannst.
• DELIVERY_SELECTED_OPTION_NOT_AVAILABLE, wird ausgelöst, wenn die gewählte Lieferoption eines Käufers nicht mehr verfügbar ist (beispielsweise nach einer Cart-Adressänderung). Früher wechselte das System die Lieferoptionen stillschweigend ohne Benachrichtigung des Käufers. Jetzt kannst du dies programmgesteuert erkennen und den Käufer auffordern, erneut zu wählen.

Metaobject-Enum-Entfernung. Die veralteten Enums PRIVATE und PUBLIC_READ für die Zugriffskontrolle bei Metaobject-Definitionen werden in 2026-07 entfernt. Wenn deine App oder dein Storefront auf diese Enum-Werte verweist, aktualisiere auf das aktuelle Zugriffskontrollmodell, bevor das Release stabil wird.

Discount-Feld-Umstrukturierung. 2026-07 strukturiert die Discount-bezogenen Felder im Cart um. Wenn dein Storefront eine benutzerdefinierte Discount-Anzeige oder Coupon-Logik hat, beginne jetzt mit der Umgestaltung gegen den Release Candidate. Hydrogen-Benutzer erhalten Codemods für die meisten Feld-Umbenennungen; benutzerdefinierte Frameworks sind auf sich allein gestellt, und Behebungsschätzungen liegen zwischen 8.000 und 40.000 Dollar, je nach Storefront-Komplexität.

Der Oktober 2026 Stichtag ist verbindlich. API-Version 2024-10 wird im Oktober 2026 eingestellt. Fünf Monate klingen komfortabel, sind es aber nicht, wenn du Staging-Deploys, Regressionstests und die Tatsache berücksichtigst, dass Cart-Logik typischerweise der fragile Teil eines Headless Stacks ist. Beginne jetzt mit Tests gegen den 2026-07 Release Candidate.

Datenschutzkonforme Checkouts mit @inContext visitorConsent

Das ist eine Ergänzung aus 2025-10 und bleibt eine der praktischsten Storefront API Ergänzungen in jüngster Zeit. Die Direktive @inContext akzeptiert nun einen Parameter visitorConsent, der es Entwicklern ermöglicht, Käufer-Zustimmungspräferenzen (Analytics, Präferenzen, Marketing und Datenverkauf) an Cart-Operationen zu übergeben.

Die Mechanik ist sauber: Du codierst die Zustimmung in die Mutation cartCreate oder cartBuyerIdentityUpdate wie folgt:

@inContext(visitorConsent: {
  analytics: true,
  preferences: true,
  marketing: false,
  saleOfData: false
})

Die Zustimmungsinformation wird automatisch codiert und in die resultierende checkoutUrl eingefügt, was Datenschutzeinhaltung während des gesamten Checkout-Prozesses gewährleistet. Shopify liest den Parameter _cs, den es an die URL anhängt, während des Checkout, entferne ihn nicht.

Das ist wichtig für GDPR und ähnliche Regelungen. Headless Storefronts, die zuvor keine saubere Möglichkeit hatten, die Zustimmung von einem Cookie Banner durch den Checkout zu leiten, haben jetzt einen First-Party-Mechanismus, der in die API selbst eingebaut ist. Es gibt keine Entschuldigung für einen modernen Headless Build, dies nicht zu implementieren.

Rate Limits: die neue Bot und Agent Realität

Shopify wendet jetzt strengere Rate Limits auf Bots und Agenten an, die auf die Storefront API und Shopify-gehostete Online Store Seiten zugreifen. Bots und Agenten, die ihre Anfragen nicht signieren, unterliegen den strengsten Limits; um sich für höhere Rate Limits zu qualifizieren, sollten Betreiber Anfragen mit Web Bot Auth signieren.

Für legitime Händler und Entwickler sind die praktischen Auswirkungen zweifach:

1. Wenn du einen benutzerdefinierten Crawler, eine Preisuche oder einen KI-Shopping Agenten betreibst, der auf Storefront API Endpunkte zugreift, signiere deine Anfragen oder erwarte Drosselung.
2. Wenn du eine Storefront MCP Integration baust (siehe nächsten Abschnitt), stelle sicher, dass dein Agent-Profil ordnungsgemäß registriert ist, damit er die angemessene Zugriffsstufe erhält.

Beachte, dass die Storefront API keine Rate Limits auf die Anzahl der legitimen Käufer-Anfragen anwendet, sie ist entworfen, um Flash-Sales ohne dich zu handhaben, die Concurrency verwalten. Die neuen Limits zielen speziell auf bösartige oder unidentifizierte Bot-Traffic.

Agentic Commerce: Storefront API trifft UCP und MCP

Dies ist die strukturell bedeutendste Verschiebung in der Rolle der Storefront API im Jahr 2026. Die API ist nicht mehr nur die Säule für Headless Human-facing Storefronts. Sie ist jetzt der Einstiegspunkt für KI-Agenten.

Shopify co-entwickelte das Universal Commerce Protocol (UCP) mit Google als offener Standard für die Transaktionen von KI-Agenten mit Händlern. UCP deckt die gesamte Commerce-Journey von der Entdeckung über Carts zum Checkout ab, und es hat breite Industrieunterstützung, einschließlich Amazon, Meta, Microsoft, Salesforce, Stripe und Wayfair.

Für Entwickler ist die konkrete Implementierungsfläche der Storefront MCP Server. Jeder Shopify Store hat seinen eigenen MCP-Endpunkt, der Storefront-Features wie Produktsuche, Cart-Operationen und Policy-Fragen offenlegt. Die Tools search_catalog, lookup_catalog und get_product entsprechen der UCP-Spezifikation.

Wichtiger Migrations-Hinweis: Die Legacy Storefront MCP Cart-Tools (get_cart und update_cart) werden zugunsten des UCP Cart MCP eingestellt. Die veralteten Tools werden bis zum 31. August 2026 beibehalten, das ist das gleiche Quartal wie die API-Sunset 2024-10. Zwei Migrationen konvergieren auf den gleichen Herbst-Stichtag.

Wenn du einen Branded Agent oder eine benutzerdefinierte KI-Shopping-Erfahrung baust, ist die Architektur einfach:

• Nutze Storefront MCP für Katalog-Suche und Produkt-Detail Abruf.
• Nutze UCP Cart MCP für Cart-Operationen (hinzufügen, aktualisieren, Zeilenelemente lesen).
• Nutze Checkout Kit (oder das kommende Checkout MCP, derzeit in Partner Preview) für die Zahlungsübergabe.

Für Händler, die keine benutzerdefinierten Agenten bauen, ist die praktische Aktion einfacher: schalte die KI-Kanäle ein, über die du verkaufen möchtest, im Shopify Admin über Agentic Storefronts, und Shopify kümmert sich um die Protokoll-Arbeit. ChatGPT, Google AI Mode, Perplexity und Microsoft Copilot sind alle über eine einzige Admin-Konfiguration erreichbar.

Authentifizierung und Zugriffstokens: Was sich im Januar 2027 ändert

Ein Element, das außerhalb des 2026 API-Versionszyklus fällt, aber direkt Storefront API Integrationen betrifft: Ab dem 1. Januar 2027 müssen alle öffentlichen Apps ablaufende Offline-Zugriffstokens für Admin API Aufrufe verwenden. Dies ist eine Admin API Änderung, keine Storefront API Änderung, aber viele Integrationen nutzen beide zusammen, wenn dein Headless Build auf einem langlebigen Admin API Token für Backend-Operationen (Inventory Sync, Order Management, Metafield Writes) angewiesen ist, musst du diese Migration parallel zu deinem Storefront API Version-Upgrade planen.

Deine Migrations-Checkliste für den Rest von 2026

Hier ist die sequenzierte Aktionsliste, nach Dringlichkeit geordnet:

1. Überprüfe deine aktuell angeheftete Version. Öffne deine Hydrogen-Konfiguration oder GraphQL Query Header. Alles älter als 2025-07 braucht sofortige Aufmerksamkeit.
2. Teste gegen 2026-07 RC. Stelle eine Staging-Umgebung gegen den Release Candidate auf. Konzentriere dich auf Cart-Mutations und jede benutzerdefinierte Discount-Anzeige-Logik.
3. Implementiere visitorConsent auf @inContext. Wenn dein Headless Build noch nicht die Cookie-Zustimmung durch die checkoutUrl propagiert, füge es jetzt hinzu. Es erfordert API Version 2025-10 oder später.
4. Ersetze veraltete Metaobject-Enums. Entferne alle PRIVATE oder PUBLIC_READ Referenzen, bevor 2026-07 am 1. Juli stabil wird.
5. Migriere von Storefront MCP Cart-Tools zu UCP Cart MCP. Stichtag: 31. August 2026.
6. Überprüfe JSON-Metafelder über 128KB. Erforderlich vor einem Upgrade auf 2026-04+.
7. Registriere eine Web Bot Auth Signatur, wenn du einen Bot oder Agenten betreibst, der auf Storefront API Endpunkte zugreift.

Wenn du praktische Hilfe beim Planen oder Ausführen einer dieser Migrationen brauchst, decken die Shopify Developer Services, die ich anbiete, Version-Upgrades, Headless Architecture Reviews und Storefront API Performance Audits ab.