Shopify Storefront API: De Complete Gids voor Developers en Merchants

De Shopify Storefront API is een openbare GraphQL API waarmee je volledig aangepaste winkelervaring kunt bouwen, van headless storefronts en mobiele apps tot IoT en AI agent-integraties, terwijl Shopify de commerce backend verzorgt. In tegenstelling tot de Admin API is het veilig om aan te roepen vanuit browsers en mobiele clients. Als je het nu voor een project evalueert, is de huidige stabiele versie 2026-04 en is al een 2026-07 release candidate beschikbaar voor testen.

Belangrijkste punten

• De Storefront API is openbaar en veilig om client-side aan te roepen; de Admin API moet op een veilige server blijven.
• Cart mutaties (cartCreate, cartLinesAdd, cartBuyerIdentityUpdate) zijn de kernbewerkingen die elke build nodig heeft.
• API-versies volgen een kwartaals schema: 2026-01, 2026-04, 2026-07, 2026-10. De oude versie 2024-10 wordt in oktober 2026 buiten gebruik gesteld.
• Hydrogen 2026.4.0 maakte de Storefront API proxy verplicht en activeerde backend consent mode standaard, twee breaking changes die een audit vereisen voordat je upgradet.
• Vanaf Hydrogen 2026.1.4 stelt elke Hydrogen storefront op Oxygen automatisch een MCP endpoint bloot op /api/mcp, wat het tot een AI-agent-ready commerce endpoint maakt zonder aangepaste code.

Wat is de Shopify Storefront API?

De Storefront API is de GraphQL API van Shopify voor klanten. Het geeft developers leestoegang tot producten, collecties, metaobjecten en menu's, plus schrijftoegang voor de twee dingen die klanten daadwerkelijk doen: een winkelwagen beheren en zich authenticeren als klant.

Zo beschrijft Shopify's eigen documentatie het toegangsmodel: de Storefront API is vooral alleen-lezen, met uitzondering van authenticatie en het beheren van een winkelwagen. Die grens is opzettelijk. Je kunt elk productdetail ophalen, een live filterinterface bouwen en een volledige checkout flow construeren zonder ooit een geheim inloggegevens aan te raken.

Het endpoint-patroon is eenvoudig:

https://{your-store}.myshopify.com/api/2026-04/graphql.json

Elk verzoek heeft een Shopify-Storefront-Public-Token header nodig (of het private-token equivalent voor server-side Hydrogen calls). Het token is niet geheim en kan in browser- of mobilecode worden ingebed. Je Admin API sleutel en wachtwoord mogen daarentegen nooit in client-side code verschijnen.

Storefront API vs. Admin API: het echte verschil

Dit is de vraag die elke merchant en developer eerst stelt, en het antwoord is architecturaal, niet slechts een lijst met functies.

De Admin API geeft je volledige lees- en schrijftoegang tot je Shopify winkelgegevens: bestellingen, klanten, producten, inventaris, fulfillment, analytics en meer. De Storefront API mist opzettelijk die administratieve functies. Je kunt bestellingen niet wijzigen, inventaris niet beheren of interne analytics er niet via benaderen. Dat is geen beperking om omheen te werken; het is de beveiligingsgrens die het veilig maakt om het token in een React-component in te sluiten.

Een veel gemaakte fout: Admin API inloggegevens gebruiken in client-side code. Dat stelt je shop inloggegevens bloot aan het publiek. Bewaar Admin API-aanroepen altijd op een veilige backend server. Als je client-side toegang tot winkelgegevens nodig hebt, is dat precies waarvoor de Storefront API is.

Kernmogelijkheden: wat je daadwerkelijk kunt bouwen

Product- en collectiequery's

Haal product titels, beschrijvingen, variant prijzen, voorraadstatus, afbeeldingen en metavelden op. Omdat GraphQL je alleen de velden laat aanvragen die je nodig hebt, kan een productkaartquery een slank 3-veld antwoord retourneren in plaats van een opgezwollen REST payload. De snelheid en efficiëntie van het alleen ophalen van de gegevens die je aanvraagt maakt het ideaal voor prestatie-gevoelige toepassingen.

Een belangrijke recente verandering: GraphQL product varianten ondersteunen nu tot 2.000 per product, uitgebreid van de vorige plafond van 100 varianten. Als je configureerbare producten verkoopt (maat x kleur x materiaal), is dit van belang.

Cart mutaties

Het Cart object is het hart van elke Storefront API build. Het huidige mutatieoppervlak omvat:

• cartCreate, maak een nieuwe winkelwagen en voeg optioneel in één aanroep een regelitem toe
• cartLinesAdd, voeg een of meer productvarianten toe aan een bestaande winkelwagen
• cartLinesUpdate, werk de hoeveelheid op bestaande regels bij (accepteert tot 250 waarden per aanroep)
• cartLinesRemove, verwijder regels per ID
• cartDiscountCodesUpdate, pas kortingscodes toe of wis ze (vervangt alle bestaande codes door de gegeven lijst)
• cartGiftCardCodesAdd / cartGiftCardCodesRemove, beheer giftcard-inlossing
• cartBuyerIdentityUpdate, koppel een ingelogde klant, stel een B2B bedrijfslocatie in of configureer checkout-voorkeuren zoals leveringsmethode
• cartMetafieldsSet, schrijf willekeurige metavelden naar de winkelwagen voor aangepaste checkout logica

Een recente toevoeging die het waard is om te weten: het CartLine type retourneert nu een viewKey veld, dus je kunt geretourneerde regels correleren met de view_key die naar cartLinesUpdate en cartLinesRemove is verzonden. Handig wanneer je optimistische UI updates bouwt.

Privacy-conforme toestemming

Sinds Storefront API versie 2025-10 en hoger accepteert de @inContext directive een visitorConsent argument. Dit stelt je in staat om de toestemmingsstatus rechtstreeks in de winkelwagencreatie aanroep in te coderen en deze automatisch in de resulterende checkoutUrl op te nemen. Het resultaat: GDPR en CCPA compliance flows zonder een aparte cookie-schrijfllaag.

Metaobjecten en token-gated toegang

Sommige functies vereisen token-gebaseerde authenticatie naast het openbare access token. Producttags, metaobjecten, metavelden, navigatiemenu's in de winkel en klantgegevens zitten allemaal achter token-scoped toegang. Het aanvragen van deze scopes gebeurt wanneer je de Storefront API app in de Shopify admin aanmaakt.

API versioning: wat merchants en developers moeten volgen

De Storefront API van Shopify volgt een kwartaals releaseschema: versies heten 2026-01, 2026-04, 2026-07 en 2026-10. Elke versie wordt 12 maanden na release ondersteund. Aanroepen naar niet-ondersteunde API-versies resulteren in apps die uit de lijst worden verwijderd of niet kunnen worden geïnstalleerd.

De belangrijkste data's zijn nu:

• 2026-04 is de huidige stabiele (nieuwste) versie.
• 2026-07 is de release candidate, gekoppeld aan Shopify's Summer 2026 Edition (codenaam Compass), die 65 productupdates bevat inclusief breaking changes in cart en product query structuren.
• 2024-10 wordt in oktober 2026 buiten gebruik gesteld. Als je headless build nog op die versie staat, heb je een beperkte tijd om te migreren.

De breaking changes van 2026-07 beïnvloeden elke headless build, Hydrogen, Next.js Commerce, Nuxt of volledig aangepast. Shopify biedt codemods voor Hydrogen projecten om de query migraties te automatiseren.

Voor merchants die moeten beoordelen of ze nu moeten handelen: als je een aangepaste headless build op een versie ouder dan 2025-04 uitvoert, plan je deze kwartaal een version audit in met je developer. Zie onze Shopify developer services pagina voor wat een version audit meestal inhoudt.

De Hydrogen verbinding: Storefront API proxy is nu verplicht

Hydrogen is het React-gebaseerde framework van Shopify dat direct op de Storefront API is gebouwd, en in 2026 werd de relatie tussen de twee aanzienlijk strakker.

Hydrogen 2026.4.0 (verzonden 17 april 2026) introduceerde twee breaking changes:

1. De Storefront API proxy is nu altijd ingeschakeld. De proxyStandardRoutes configuratie optie werd verwijderd. Als een request handler wordt uitgevoerd zonder een storefront instantie in zijn load context, genereert het een runtime error. Elke aangepaste Hydrogen setup die de proxy omzeilde, moet worden bijgewerkt.
2. Backend consent mode is nu de standaard. Hydrogen vertrouwt niet langer op de client-side _tracking_consent cookie. Toestemming wordt nu beheerd via server-set cookies die via de Storefront API proxy zijn geschreven. Aangepaste toestemmingsbannersdie document.cookie lezen op _tracking_consent zien na upgrade een lege waarde.

De reden waarom deze twee wijzigingen gekoppeld zijn: het hele punt van backend consent mode is dat toestemmingsschrijvingen niet stilletjes kunnen mislukken wanneer een proxy ontbreekt. De proxy die verplicht wordt, was de voorwaarde.

Als je een aangepaste Hydrogen setup uitvoert (elk project dat geen schone create-hydrogen skeleton is), audit je createRequestHandler aanroepen en toestemmingsbannerslogica voordat je naar 2026.4.x upgradet.

De grootste verschuiving in 2026: je storefront is nu een AI agent endpoint

Dit is de ontwikkeling die de rol van de Storefront API het meest fundamenteel verandert.

Hydrogen 2026.1.4 voegde ingebouwde Storefront MCP (Model Context Protocol) proxy ondersteuning toe. Elke Hydrogen store op Oxygen stelt nu een MCP endpoint bloot op /api/mcp zonder aangepaste setup. Wat dat in praktijk betekent: AI assistenten zoals ChatGPT, Perplexity en aangepaste shopping agents kunnen je producten ontdekken, winkelwagens beheren en klanten door checkout leiden met natuurlijke taal, allemaal aangestuurd door real-time gegevens van de Storefront API.

Shopify stelt drie verschillende MCP surfaces bloot:

• Catalog MCP, wereldwijde productontdekking op Shopify merchants
• Storefront MCP, merchant-specifieke zoeken, beleid en veelgestelde vragen
• Checkout MCP, programmatische winkelwagencreatie, updates en checkout completion

Openbare productontdekking via Storefront MCP vereist geen aanvullende authenticatie. Geverifieerde cart operaties gebruiken de bestaande Shopify-Storefront-Private-Token header die je Hydrogen app al verstuurt.

Om te verifiëren dat de proxy actief is in je store: raak /api/mcp op je Oxygen deployment aan. Als het doorstuurt naar Shopify's Storefront MCP server, ben je live.

Voor merchants die nog niet op Hydrogen zijn, is dit een concrete reden om de migratie te evalueren. Liquid themes op Shopify's CDN leveren consistent maar vaste prestaties. Hydrogen op Oxygen levert die prestatiebasis plus AI agent integratie zonder degradatie. De ROI berekening voor AI commerce functies verschuift in het voordeel van Hydrogen. Je kunt op onze Shopify headless developer pagina verkennen waar een Hydrogen migratie mee gepaard gaat.

Praktische checklist voor merchants en developers

Als je een Hydrogen storefront uitvoert:

• Bevestig dat je op Storefront API 2026-04 bent (de huidige nieuwste)
• Audit createRequestHandler voor de nu verwijderde proxyStandardRoutes optie
• Controleer of je toestemmingsbanner server-set cookies leest, niet _tracking_consent
• Test /api/mcp op je Oxygen deployment om MCP bevestigd te hebben
• Begin nu met testen tegen de 2026-07 release candidate; wacht niet tot oktober

Als je een aangepaste headless build uitvoert (Next.js, Nuxt, enz.):

• Identificeer je huidige API-versie en zet deze af tegen de oktober 2026 sunset van 2024-10
• Beoordeel het 2026-07 changelog voor breaking changes in cart en product query structuren
• Plan codemods of handmatige query-updates voordat de volgende Shopify Editions cyclus

Als je een standaard Liquid theme uitvoert:

• De Storefront API is nog relevant als je apps van derden gebruikt die deze client-side aanroepen
• Verifieer dat deze apps gericht zijn op 2026-04 of nieuwer
• Overweeg of de AI agent mogelijkheden in Hydrogen een migratieëvaluatie rechtvaardigen

De Storefront API is niet langer slechts de "headless Shopify" API. Het is de data laag die je catalogus verbindt met elk oppervlak dat een klant zou kunnen gebruiken, browser, mobiel, spraak en nu AI agents. Je versie actueel houden en je Hydrogen setup afgestemd op de proxy- en toestemmingsvereisten van Shopify is het onderhoud dat deze oppervlakken open houdt.