magento-graphql

Magento GraphQL API

Overview

Magento 2 (and Adobe Commerce) ships a comprehensive GraphQL API for storefront operations — product catalog, search, cart, checkout, customer authentication, and order history. The endpoint is /graphql and does not require an admin token for public catalog data. Cart and customer operations require a guest cart ID (UUID) or a Bearer token from customer login. PWA Studio (Venia) is built entirely on this API, making it the reference implementation for headless Magento.

When to Use This Skill

• When building a React, Vue, or Next.js headless storefront on Magento 2
• When creating a native mobile app that needs Magento product and checkout data
• When implementing PWA Studio extensions that fetch custom data via GraphQL resolvers
• When replacing REST API calls with more efficient GraphQL queries in existing headless projects
• When building a custom GraphQL resolver to expose third-party or custom module data
• When integrating a headless CMS with Magento's product catalog

Core Instructions

1. Set up the GraphQL client

   Magento GraphQL uses standard HTTP POST to /graphql. Use Apollo Client or a lightweight fetch wrapper:

   // lib/magento.ts
   const MAGENTO_URL = process.env.NEXT_PUBLIC_MAGENTO_URL; // e.g. https://magento.example.com
   
   export async function magentoQuery<T>(
     query: string,
     variables: Record<string, unknown> = {},
     token?: string
   ): Promise<T> {
     const headers: Record<string, string> = {
       "Content-Type": "application/json",
       Store: process.env.NEXT_PUBLIC_MAGENTO_STORE_CODE ?? "default",
     };
   
     if (token) {
       headers["Authorization"] = `Bearer ${token}`;
     }
   
     const response = await fetch(`${MAGENTO_URL}/graphql`, {
       method: "POST",
       headers,
       body: JSON.stringify({ query, variables }),
       next: { revalidate: 300 }, // Next.js ISR caching
     });
   
     if (!response.ok) {
       throw new Error(`Magento GraphQL HTTP error: ${response.status}`);
     }
   
     const { data, errors } = await response.json();
     if (errors?.length) {
       throw new Error(errors[0].message);
     }
     return data as T;
   }