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;
   }

2. Query the product catalog

   // 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

   // 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

   // 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
   // app/code/MyVendor/CustomGraphQL/etc/schema.graphqls

   type Query {
       myCustomProducts(
           brand: String @doc(description: "Filter by brand")
       ): MyCustomProductOutput @resolver(class: "MyVendor\\CustomGraphQL\\Model\\Resolver\\CustomProducts") @doc(description: "Get custom product list")
   }

   type MyCustomProductOutput {
       items: [CustomProductItem]
       total_count: Int
   }

   type CustomProductItem {
       sku: String
       name: String
       brand: String
       custom_attribute: String
   }

   <?php
   // app/code/MyVendor/CustomGraphQL/Model/Resolver/CustomProducts.php
   namespace MyVendor\CustomGraphQL\Model\Resolver;

   use Magento\Framework\GraphQl\Config\Element\Field;
   use Magento\Framework\GraphQl\Query\ResolverInterface;
   use Magento\Framework\GraphQl\Schema\Type\ResolveInfo;
   use Magento\Catalog\Model\ResourceModel\Product\CollectionFactory;

   class CustomProducts implements ResolverInterface
   {
       public function __construct(
           private readonly CollectionFactory $collectionFactory
       ) {}

       public function resolve(Field $field, $context, ResolveInfo $info, array $value = null, array $args = null)
       {
           $collection = $this->collectionFactory->create();
           $collection->addAttributeToSelect(['sku', 'name', 'brand', 'custom_attribute']);
           $collection->addAttributeToFilter('status', 1);
           $collection->addAttributeToFilter('visibility', ['neq' => 1]);

           if (!empty($args['brand'])) {
               $collection->addAttributeToFilter('brand', ['like' => '%' . $args['brand'] . '%']);
           }

           $items = [];
           foreach ($collection as $product) {
               $items[] = [
                   'sku'              => $product->getSku(),
                   'name'             => $product->getName(),
                   'brand'            => $product->getData('brand'),
                   'custom_attribute' => $product->getData('custom_attribute'),
               ];
           }

           return ['items' => $items, 'total_count' => $collection->getSize()];
       }
   }

Examples

Product detail page — configurable product with swatches

export async function getProductByUrlKey(urlKey: string) {
  return magentoQuery<{ products: { items: MagentoProduct[] } }>(`
    query GetProduct($urlKey: String!) {
      products(filter: { url_key: { eq: $urlKey } }) {
        items {
          uid sku name url_key
          meta_title meta_description
          description { html }
          short_description { html }
          ... on ConfigurableProduct {
            configurable_options {
              id uid label attribute_code position
              values {
                uid label
                swatch_data {
                  ... on ColorSwatchData { value }
                  ... on ImageSwatchData { thumbnail value }
                  ... on TextSwatchData { value }
                }
              }
            }
            variants {
              attributes { uid label code value_index }
              product {
                uid sku stock_status
                media_gallery { url label disabled }
                price_range {
                  minimum_price {
                    regular_price { value currency }
                    final_price { value currency }
                  }
                }
              }
            }
          }
          media_gallery { url label disabled position }
          reviews(pageSize: 5) {
            items {
              summary text created_at
              ratings_breakdown { name value }
              nickname
            }
          }
        }
      }
    }
  `, { urlKey });
}

Checkout flow — set shipping address and place order

export async function setShippingAddress(cartId: string, address: AddressInput) {
  return magentoQuery(`
    mutation SetShipping($cartId: String!, $address: CartAddressInput!) {
      setShippingAddressesOnCart(input: {
        cart_id: $cartId
        shipping_addresses: [{ address: $address }]
      }) {
        cart {
          shipping_addresses {
            available_shipping_methods {
              carrier_code method_code carrier_title method_title
              amount { value currency }
            }
          }
        }
      }
    }
  `, { cartId, address });
}

export async function placeOrder(cartId: string) {
  return magentoQuery<{ placeOrder: { order: { order_number: string } } }>(`
    mutation PlaceOrder($cartId: String!) {
      placeOrder(input: { cart_id: $cartId }) {
        order { order_number }
        errors { message code }
      }
    }
  `, { cartId });
}

Best Practices

• Use the `Store` HTTP header to target specific store views — without it, Magento defaults to the default store and returns incorrect pricing/currency for multi-store setups
• Enable GraphQL query caching in Magento via Varnish or built-in cache for public catalog queries — product list queries can be cached for minutes to reduce PHP execution
• Use inline fragments for polymorphic product types — always include ... on SimpleProduct, ... on ConfigurableProduct, ... on BundleProduct where applicable
• Persist the cart ID in a cookie — guest cart IDs (UUID) expire after 24 hours of inactivity; merge with customer cart after login using mergeCarts mutation
• Batch related queries — Apollo Client batching or manual query merging reduces RTTs for pages that need product + category + CMS block data simultaneously
• Implement proper error handling for `errors` array — GraphQL responses return 200 even for errors; always check errors property in the response body
• Cache customer tokens securely — store bearer tokens in httpOnly cookies, not localStorage, to prevent XSS token theft

Common Pitfalls

Related Skills

• @magento-module-development
• @magento-indexing-caching
• @magento-multi-store
• @headless-commerce-architecture
• @graphql-api-design

Shopping Cart and Login Integration for Headless Magento

Problem Description

A home furnishings brand has a Next.js headless storefront connected to Magento 2. Shoppers frequently browse while logged out, add items to their cart, and then log in at checkout — only to find their cart is empty. The current implementation creates a new cart session on login instead of carrying over the guest cart, causing significant cart abandonment.

Additionally, the team has reports that customers adding configurable products (sofas with selectable fabric/size) to the cart sometimes see the wrong variant or receive errors because the cart integration doesn't properly distinguish between the parent product and the chosen variant.

Your task is to build the cart and authentication module that resolves these issues.

Output Specification

Produce a TypeScript file lib/cart.ts containing functions for:

• Creating a new guest cart
• Adding a simple product to the cart
• Adding a configurable product (with a selected variant) to the cart
• Logging in a customer and handling the transition from guest cart to authenticated cart
• Fetching the current cart for display (both guest and authenticated scenarios)
• Fetching customer order history (most recent orders first)

Assume a magentoQuery helper is available (import from ./magento-client or stub it). Do not make live network calls — the code only needs to be structurally correct.

Also produce NOTES.md (max 25 lines) covering:

• How the guest-to-authenticated cart transition works and why it is necessary
• How configurable products are added differently from simple products

Magento Headless Storefront: Core API Client

Problem Description

A fashion retailer is rebuilding their online store as a Next.js headless application backed by Magento 2. The backend Magento instance serves multiple regional storefronts (UK, DE, US) that have different currencies and pricing, so every API request must clearly identify which storefront it is targeting. The team wants public catalog pages to benefit from Next.js incremental static regeneration so pages automatically refresh without a full rebuild.

The retailer's security team conducted a review of the previous prototype and raised concerns about how authentication tokens were stored on the client side. The new implementation must address these concerns and follow current web security best practices for token storage.

Output Specification

Implement a TypeScript Magento GraphQL client module in a file named lib/magento-client.ts. It should export at minimum:

• A generic query/mutation function that handles all communication with the Magento GraphQL endpoint
• A customer login function that authenticates with email and password and stores the token securely
• A function (or middleware) that demonstrates how to make an authenticated request using the stored token

Also produce a short NOTES.md file (max 20 lines) that explains:

• How the store view targeting works
• How authentication tokens are stored and why
• How GraphQL error responses are handled

The implementation should be TypeScript and work within a Next.js App Router project. Use environment variables for the Magento URL and store code. Do not make live network calls — the code only needs to be structurally correct and runnable.

Product Catalog Module for Headless Magento Storefront

Problem Description

An outdoor sports retailer runs a Magento 2 store with a broad product catalogue that includes both simple products (accessories, consumables) and configurable products (apparel with size/color variants). They are building a React-based headless storefront and need a product catalog module that powers two key pages: a category listing page with faceted filtering, and a product detail page.

The merchandising team has reported a recurring issue in staging: some products visible in the Magento admin panel do not show up when fetched through the API, and the stock status for clothing variants is always showing incorrectly. The new implementation should be designed so that these known data issues are handled correctly.

The listing page must support pagination and allow shoppers to filter by attributes (size, color, brand) using the facet counts returned by the API.

Output Specification

Produce a TypeScript file lib/catalog.ts containing:

• A getProducts function for category/search listing with facets and pagination
• A getProductDetail function for a single product's full details (suitable for a product detail page)

Also produce a NOTES.md file (max 30 lines) that explains:

• How the code handles different product types in the response
• Why stock status is queried the way it is
• A note about the visibility issue and what causes products to be missing from API results

Do not make live network calls — assume a magentoQuery helper function is available (you may import it from ./magento-client or stub it). The code only needs to be structurally correct with proper GraphQL query strings.