Magento 2 GraphQL API: A Practical Frontend Guide
How to use Magento 2 GraphQL for headless and Hyvä storefronts — queries, mutations, caching, authentication, and performance pitfalls to avoid.
Queries, Mutations, and Store Headers
GraphQL is Magento's preferred storefront API for PWA Studio, Hyvä Checkout integrations, and custom headless apps. Always send Store and Content-Currency headers so localized catalog and price data resolve correctly.
Start with catalog, cart, and customer queries before custom modules. Keep fragments small and reusable — oversized product queries are the number-one cause of slow TTFB on GraphQL storefronts.
Authentication, Carts, and Checkout
Guest carts use cart IDs; logged-in customers use customer tokens from generateCustomerToken. Merge guest and customer carts explicitly after login so promotions and stock reservations stay intact.
Prefer Magento's checkout mutations over reinventing quote logic in your BFF. Custom payment and shipping methods should expose GraphQL resolvers that mirror their REST/XML-RPC capabilities.
Caching and Production Hardening
Use GET for cacheable queries where Magento and your CDN support it, and invalidate with cache IDs tied to customer/group and store. Never cache authenticated customer queries at the edge.
Rate-limit public GraphQL endpoints, disable introspection in production, and watch resolver N+1 patterns in custom modules. A clean schema with dataloaders often outperforms throwing more hardware at Varnish.
Need help with your Magento 2 project?
Talk to Our Team