Magento 2 GraphQL: building a real storefront query

GraphQL is the public API surface of modern Magento 2 — it powers PWA Studio, custom headless front ends, and the storefront app. This post goes past "what is GraphQL" to the queries you'll actually write.

The endpoint

POST /graphql with a JSON { "query": "..." } body. Introspect it with any GraphQL client; the schema is large but well-organized by domain (catalog, cart, customer, CMS).

Fetching a product

{
  products(filter: { sku: { eq: "24-MB01" } }) {
    items {
      name
      sku
      price_range { minimum_price { regular_price { value currency } } }
      media_gallery_entries { file label }
    }
  }
}

Only request the fields you render — over-fetching is the most common headless perf mistake.

Cart and checkout

The cart is a mutation-driven flow: createEmptyCart → addProductsToCart → setShippingAddressesOnCart → setPaymentMethodOnCart → placeOrder. Each step returns the updated cart, so the client holds state by re-querying.

Customer and auth

Customer tokens come from generateCustomerToken, then sent as the Authorization: Bearer header. Store that token; don't re-auth per request.

Test it against a real stack

GraphQL behavior depends on the search engine, cache, and PHP version — a SQLite dev box lies. Bring up a production-shaped local Magento 2 stack with Govard, then query /graphql from govard shell or your HTTP client against the real Nginx/Varnish front end.

Where this fits

GraphQL is the bridge from the "Magento 2 in practice" architecture to a decoupled storefront — the topic of the earlier PWA/headless post. Use it when the front end is a product in its own right; for a single storefront, Hyva still wins on operational cost.

Next in this series: Magento 2 B2B quotes & negotiation — /blog/magento2-b2b-quotes