magento-graphql

What this skill does

# 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:

   ```typescript
   // 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;
   }
   ```

2. **Query the product catalog**

   ```typescript
   // Fetch products by category UID or search
   export async function getProducts(params: {
     categoryUid?: string;
     search?: string;
     pageSize?: number;
     currentPage?: number;
   }) {
     return magentoQuery<{ products: MagentoProductList }>(`
       query GetProducts(
         $search: String
         $filter: ProductAttributeFilterInput
         $pageSize: Int
         $currentPage: Int
       ) {
         products(
           search: $search
           filter: $filter
           pageSize: $pageSize
           currentPage: $currentPage
           sort: { position: ASC }
         ) {
           total_count
           page_info { current_page page_size total_pages }
           aggregations {
             attribute_code label count
             options { label value count }
           }
           items {
             uid sku name url_key
             ... on SimpleProduct {
               price_range {
                 minimum_price {
                   regular_price { value currency }
                   final_price { value currency }
                   discount { percent_off amount_off }
                 }
               }
             }
             ... on ConfigurableProduct {
               configurable_options {
                 attribute_code label
                 values { uid label swatch_data { value } }
               }
               variants {
                 attributes { uid label code value_index }
                 product { sku stock_status price_range { minimum_price { final_price { value } } } }
               }
             }
             small_image { url label }
             thumbnail { url label }
             rating_summary review_count
             stock_status
           }
         }
       }
     `, {
       search: params.search,
       filter: params.categoryUid ? { category_uid: { eq: params.categoryUid } } : undefined,
       pageSize: params.pageSize ?? 20,
       currentPage: params.currentPage ?? 1,
     });
   }
   ```

3. **Create guest cart and add items**

   ```typescript
   // Create a guest cart and get the cart ID
   export async function createGuestCart(): Promise<string> {
     const data = await magentoQuery<{ createEmptyCart: string }>(`
       mutation { createEmptyCart }
     `);
     return data.createEmptyCart; // Returns a UUID cart ID
   }

   // Add a simple product to cart
   export async function addSimpleProductToCart(cartId: string, sku: string, qty: number) {
     return magentoQuery(`
       mutation AddSimpleProduct($cartId: String!, $sku: String!, $qty: Float!) {
         addSimpleProductsToCart(
           input: {
             cart_id: $cartId
             cart_items: [{ data: { sku: $sku, quantity: $qty } }]
           }
         ) {
           cart {
             items {
               uid quantity
               product { name sku }
               prices { price { value currency } }
             }
             prices {
               subtotal_excluding_tax { value currency }
               grand_total { value currency }
             }
           }
         }
       }
     `, { cartId, sku, qty });
   }

   // Add a configurable product with selected variant
   export async function addConfigurableProductToCart(
     cartId: string,
     parentSku: string,
     variantSku: string,
     qty: number
   ) {
     return magentoQuery(`
       mutation AddConfigurable($cartId: String!, $parentSku: String!, $variantSku: String!, $qty: Float!) {
         addConfigurableProductsToCart(
           input: {
             cart_id: $cartId
             cart_items: [{
               parent_sku: $parentSku
               data: { sku: $variantSku, quantity: $qty }
             }]
           }
         ) {
           cart {
             items { uid quantity product { name } }
           }
         }
       }
     `, { cartId, parentSku, variantSku, qty });
   }
   ```

4. **Authenticate customers and manage accounts**

   ```typescript
   // Customer login — returns a bearer token
   export async function loginCustomer(email: string, password: string): Promise<string> {
     const data = await magentoQuery<{ generateCustomerToken: { token: string } }>(`
       mutation Login($email: String!, $password: String!) {
         generateCustomerToken(email: $email, password: $password) {
           token
         }
       }
     `, { email, password });
     return data.generateCustomerToken.token;
   }

   // Get authenticated customer's cart
   export async function getCustomerCart(token: string) {
     return magentoQuery(`
       query {
         customerCart {
           id
           items {
             uid quantity
             product { name sku small_image { url } }
             prices { price { value currency } }
           }
           prices { grand_total { value currency } }
         }
       }
     `, {}, token);
   }

   // Get order history
   export async function getCustomerOrders(token: string, pageSize = 10) {
     return magentoQuery(`
       query GetOrders($pageSize: Int) {
         customer {
           orders(pageSize: $pageSize, sort: { sort_field: CREATED_AT, sort_direction: DESC }) {
             total_count
             items {
               id number status order_date
               total { grand_total { value currency } }
               items { product_name product_sku quantity_ordered }
               shipping_address { firstname lastname city region { code } country_code }
             }
           }
         }
       }
     `, { pageSize }, token);
   }
   ```

5. **Create a custom GraphQL resolver in a Magento 2 module**

   ```php
   <?php
   // app/code/MyVendor/CustomGraphQL/etc/schema.graphqls

   type Query {
       myCusto