Build performant mobile commerce experiences using Magento 2 GraphQL API with optimized queries, caching strategies, and offline-first architecture.
GraphQL for Mobile Commerce
Mobile commerce demands fast, efficient API calls over potentially slow cellular connections. REST APIs return fixed data structures, often sending more data than the client needs or requiring multiple round-trips to assemble a single screen. GraphQL solves both problems by letting the client specify exactly which fields to fetch in a single request.
Magento 2 ships with a comprehensive GraphQL API covering catalog, cart, checkout, customer accounts, and CMS content. This guide covers how to build performant mobile applications against this API, with optimization patterns proven in Magento 2 production environments.
Optimized Query Patterns
Product Listing Page
Mobile screens display less data than desktop. Fetch only what the UI renders:
query CategoryProducts($id: String!, $page: Int!, $size: Int!) {
products(
filter: { category_uid: { eq: $id } }
pageSize: $size
currentPage: $page
sort: { position: ASC }
) {
total_count
items {
uid
sku
name
url_key
price_range {
minimum_price {
final_price { value currency }
discount { percent_off }
}
}
small_image {
url
label
}
review_count
rating_summary
}
page_info {
current_page
total_pages
}
}
}
This query returns approximately 200 bytes per product versus 2-3KB from the equivalent REST endpoint. For a 20-product listing page, that is a 90 percent reduction in payload size.
Product Detail Page
query ProductDetail($urlKey: String!) {
products(filter: { url_key: { eq: $urlKey } }) {
items {
uid
sku
name
description { html }
short_description { html }
price_range {
minimum_price {
regular_price { value currency }
final_price { value currency }
discount { amount_off percent_off }
}
}
media_gallery {
url
label
position
... on ProductVideo {
video_content { video_url video_title }
}
}
... on ConfigurableProduct {
configurable_options {
attribute_uid
label
values {
uid
label
swatch_data {
value
... on ImageSwatchData { thumbnail }
... on ColorSwatchData { value }
}
}
}
variants {
attributes {
uid
label
code
}
product {
uid
sku
price_range {
minimum_price {
final_price { value currency }
}
}
stock_status
}
}
}
related_products {
uid
name
url_key
small_image { url }
price_range {
minimum_price {
final_price { value currency }
}
}
}
}
}
}
Use GraphQL fragments to share field selections across queries and reduce duplication in your mobile codebase.
Cart Operations
Efficient Cart Management
mutation AddToCart($cartId: String!, $sku: String!, $qty: Float!) {
addProductsToCart(
cartId: $cartId
cartItems: [{ sku: $sku, quantity: $qty }]
) {
cart {
id
total_quantity
prices {
grand_total { value currency }
subtotal_excluding_tax { value currency }
applied_taxes { label amount { value } }
discounts { label amount { value } }
}
items {
uid
quantity
product {
name
sku
small_image { url }
}
prices {
row_total { value currency }
total_item_discount { value }
}
}
}
}
}
Return the full cart state after every mutation. This eliminates the need for a separate cart fetch, saving a round-trip on every cart interaction.
Authentication Flow
Customer Token Management
mutation CustomerLogin($email: String!, $password: String!) {
generateCustomerToken(email: $email, password: $password) {
token
}
}
// Mobile client token management
class AuthManager {
private token: string | null = null;
private refreshTimer: NodeJS.Timeout | null = null;
async login(email: string, password: string): Promise<void> {
const { data } = await this.client.mutate({
mutation: LOGIN_MUTATION,
variables: { email, password },
});
this.token = data.generateCustomerToken.token;
await SecureStore.setItemAsync("auth_token", this.token);
// Magento tokens expire after 1 hour by default
this.refreshTimer = setInterval(() => this.refreshToken(), 50 * 60 * 1000);
}
getHeaders(): Record<string, string> {
return this.token ? { Authorization: `Bearer ${this.token}` } : {};
}
}
Caching Strategy for Mobile
Apollo Client Configuration
import { ApolloClient, InMemoryCache } from "@apollo/client";
import { persistCache, AsyncStorageWrapper } from "apollo3-cache-persist";
import AsyncStorage from "@react-native-async-storage/async-storage";
const cache = new InMemoryCache({
typePolicies: {
Query: {
fields: {
products: {
keyArgs: ["filter", "sort"],
merge(existing, incoming, { args }) {
if (args?.currentPage === 1) return incoming;
return {
...incoming,
items: [...(existing?.items || []), ...incoming.items],
};
},
},
},
},
SimpleProduct: { keyFields: ["uid"] },
ConfigurableProduct: { keyFields: ["uid"] },
},
});
// Persist cache to device storage for offline access
await persistCache({
cache,
storage: new AsyncStorageWrapper(AsyncStorage),
maxSize: 10 * 1024 * 1024, // 10MB
});
Network-Aware Fetching
import NetInfo from "@react-native-community/netinfo";
async function fetchWithNetworkAwareness<T>(
query: DocumentNode,
variables: Record<string, unknown>
): Promise<T> {
const netState = await NetInfo.fetch();
if (!netState.isConnected) {
// Return cached data only
return client.readQuery({ query, variables });
}
const fetchPolicy = netState.type === "cellular" && !netState.isInternetReachable
? "cache-first"
: "cache-and-network";
const { data } = await client.query({ query, variables, fetchPolicy });
return data;
}
Performance Optimization
Server-Side Query Complexity Limits
Protect the Magento backend from expensive queries:
// app/etc/env.php
'graphql' => [
'query_complexity' => 300,
'query_depth' => 10,
],
Response Compression
Enable gzip compression on the Magento server for GraphQL responses:
# nginx.conf
location /graphql {
gzip on;
gzip_types application/json;
gzip_min_length 256;
proxy_pass http://magento_backend;
}
GraphQL JSON responses compress extremely well - typical 60-80 percent size reduction.
Image Optimization for Mobile
Request appropriately sized images using Magento's resize parameters:
query {
products(filter: { category_uid: { eq: "MjA=" } }) {
items {
small_image {
url # Returns full-size image
}
thumbnail {
url # Returns thumbnail-size image
}
}
}
}
On the mobile client, use the thumbnail URL for list views and the full image URL for detail views. Implement progressive image loading with blur placeholders for a smooth experience on slow connections.
Best Practices
- Use query batching to combine multiple small queries into a single HTTP request
- Implement infinite scroll pagination instead of loading all products at once
- Cache product catalog data aggressively - prices and stock can have shorter TTL
- Prefetch the next page of products while the user scrolls for seamless experience
- Monitor GraphQL query performance with custom server monitoring metrics
- Use persisted queries in production to reduce request payload size and improve security
- Test on real devices over throttled connections to validate performance
A well-optimized GraphQL integration delivers native-quality performance in mobile commerce applications while leveraging the full power of the Magento 2 commerce engine.
Frequently asked questions
Why use Magento 2 GraphQL instead of REST for a mobile app?
Magento 2 GraphQL lets the mobile client ask for exactly the fields a screen renders in a single request, where REST returns fixed structures that often carry extra data or need several round-trips. A trimmed product listing query returns approximately 200 bytes per product against 2-3KB from the equivalent REST endpoint, a 90 percent payload reduction for a 20-product page. The API covers catalog, cart, checkout, customer accounts and CMS content.
How do I paginate products with Magento 2 GraphQL?
Pass pageSize and currentPage to the products query along with a filter such as category_uid, then read total_count and page_info with current_page and total_pages from the response. Use infinite scroll instead of loading all products at once, and prefetch the next page while the user scrolls. In Apollo Client, a merge function on the products field appends incoming items to the existing list and starts over when currentPage is 1.
How do I add a product to the cart with Magento 2 GraphQL?
Call the addProductsToCart mutation with the cartId and a cartItems list of sku and quantity. Request the full cart in the mutation response, including total_quantity, prices such as grand_total, applied_taxes and discounts, and each item's row_total. Returning the whole cart state after every mutation removes the need for a separate cart fetch and saves a round-trip on each cart interaction.
How long do Magento 2 GraphQL customer tokens last?
Magento customer tokens expire after 1 hour by default. A mobile app gets one from the generateCustomerToken mutation with the customer's email and password, keeps it in secure storage such as SecureStore, and sends it in an Authorization header as a Bearer token. A sample client refreshes the token every 50 minutes on a timer, ahead of the expiry.
How do I cache Magento GraphQL data for offline use in a React Native app?
Apollo Client's InMemoryCache can key SimpleProduct and ConfigurableProduct by uid, and apollo3-cache-persist writes that cache to device storage through AsyncStorage, for example with a maxSize of 10MB. Check the connection with NetInfo before each fetch. With no connection, read from the cache only. Otherwise use cache-and-network, or cache-first on cellular when the internet is not reachable. Catalog data can be cached aggressively, while prices and stock need a shorter TTL.
How do I limit GraphQL query complexity in Magento 2?
Set the limits in app/etc/env.php under the graphql key, for example query_complexity at 300 and query_depth at 10. Those caps protect the Magento backend from expensive queries sent by clients. Persisted queries in production also reduce request payload size and improve security.
Should I enable gzip for Magento GraphQL responses?
Yes, GraphQL JSON responses compress extremely well, typically by 60-80 percent. In nginx, a location /graphql block with gzip on, gzip_types application/json and gzip_min_length 256 ahead of proxy_pass to the Magento backend turns it on. Query batching can also combine several small queries into a single HTTP request.
How do I load smaller product images in a Magento mobile app?
Request both small_image and thumbnail on products in the GraphQL query. The small_image url returns the full-size image and thumbnail returns a thumbnail-size one, so list views should use the thumbnail URL and detail views the full image URL. Progressive loading with blur placeholders helps on slow connections, and testing on real devices over throttled connections validates the performance.
Read how we handle it in DevOps for e-commerce.
Related Articles
Why Magento 2 Indexers Get Stuck and How to Unstick Them
A Magento indexer stuck at Processing or Reindex required usually comes down to one of six causes, from cron not running the index group to a killed reindex, missing triggers or batches too big for memory. Each one comes with its check and its fix, taken from the Magento 2.4.9 source and Adobe's documentation.
MagentoHow to Disable OpenSearch Security in Magento 2 While Keeping It Private on Ubuntu
OpenSearch ships with SSL and authentication enabled by default, which can complicate Magento 2 integration in development or internal environments. This guide explains how to safely turn off OpenSearch security while restricting access to localhost using Ubuntu's firewall.
MagentoHow to Run Magento 2 on Kubernetes Without Overpaying
Most Magento clusters cost more than they need to because every tier gets replicated as if every tier were the bottleneck, when only PHP-FPM ever is. This is the shape that keeps the bill honest, with sessions and cache moved to Valkey or Redis, media moved to object storage instead of a shared filesystem, and cron running on exactly one scheduler because Adobe documents that it can only run on one node. It also covers the case for not doing this at all, since a single well-sized server with a warm standby reaches the same uptime for a single steady store.