How to Fetch and Update Customer Data in Shopify Headless with Next.js 15

The Shopify Customer Account API is a powerful GraphQL API that allows you to build custom customer account experiences in headless storefronts. Unlike the traditional Storefront API, the Customer Account API provides full CRUD operations for customer data, including orders, addresses, and profile information.

One mistake I initially made was trying to use the Storefront API or Admin API to manage customer data. Shopify has specifically protected customer data and launched a dedicated Customer Account API for this purpose. I wrote about the different APIs here.

What we'll cover:

• Setting up Customer Account API queries and mutations
• Implementing comprehensive customer data management
• Handling authentication and permissions
• Best practices for type safety with GraphQL Code Generation

Tech Stack:

• Next.js 15 with App Router
• TypeScript
• GraphQL Code Generation (graphql-codegen)
• Shopify Customer Account API

Why this matters: Using the Customer Account API works a bit differently from other Shopify APIs.

For the Storefront API, you only need a client because it deals with publicly accessible data. The Admin API requires creating a private app with a client ID and secret, which must be stored securely.

The Customer Account API requires OAuth. This means the user must log in to Shopify, and there's a token exchange process that you need to handle and store yourself.

Crucial Security Distinction: The Customer Account API can only be used by the logged-in user themselves. You cannot change customer data as an admin or programmatically from your backend. Only the logged-in user performing the OAuth2 flow can access and modify their own data. This applies to fetching orders, updating profiles, and managing addresses. This user-centric approach significantly increases security by ensuring that sensitive customer information can only be accessed by the customer who owns it.

OAuth is required for authentication, but understanding how to implement it properly for customer account operations can be challenging. Many developers struggle with the Customer Account API because it requires OAuth and follows a different pattern than the Storefront API.

I wrote a detailed article that shows you exactly how to implement all customer data operations — with proper error handling and type safety: Implementing Customer Account API authentication

Customer Account API Capabilities

The Customer Account API is specifically designed to power comprehensive customer account experiences in headless Shopify storefronts. This API enables you to build fully featured customer dashboards where users can manage their entire relationship with your store. You can create personalized account portals that rival traditional e-commerce platforms, allowing customers to view their complete order history, manage multiple shipping addresses, update personal information, and handle account preferences. The API is particularly valuable for businesses that want to provide a premium, branded customer experience while maintaining complete control over the user interface and user journey.

Common use cases include building customer account dashboards for subscription services, B2B portals where customers need to manage multiple addresses and users, loyalty program interfaces that require deep order history analysis, and mobile applications that need offline-capable customer data. The API's OAuth-based security model ensures that customer data remains protected while giving you the flexibility to create sophisticated account management experiences.

The Customer Account API supports these operations:

Customer Profile Management

• Get customer details
• Update customer information (name, email, phone)

Address Management

• List customer addresses
• Create new addresses
• Update existing addresses
• Delete addresses
• Set default addresses

Order Management

• List customer orders
• Get detailed order information
• View order history with line items, addresses, and pricing

Authentication

• OAuth-based authentication
• Token refresh handling
• Session management

Implementation Guide

Step 1: Define GraphQL Queries and Mutations

If you've worked with Shopify's Storefront API or Admin API before, you'll find the Customer Account API refreshingly familiar. The GraphQL query structure follows the exact same patterns you're already used to - the same syntax, the same field selection principles, and the same mutation patterns. The only difference is the schema fields and authentication method, but the fundamental GraphQL approach remains identical across all Shopify APIs.

We need to create comprehensive GraphQL operations for customer data management. This step forms the foundation of our type-safe implementation, ensuring we have all the necessary queries and mutations to handle complete customer lifecycle operations. The key here is to structure our operations to match the Customer Account API schema while ensuring we get all the data we need for a complete customer experience.

// lib/shopify/queries/customer-account/customer.ts

// Customer Profile Query
export const getCustomerQuery = /* GraphQL */ `
  query getCustomer {
    customer {
      id
      displayName
      firstName
      lastName
      emailAddress {
        emailAddress
      }
      phoneNumber {
        phoneNumber
      }
      defaultAddress {
        id
        firstName
        lastName
        company
        address1
        address2
        city
        province
        country
        zip
      }
    }
  }
`;

// Customer Orders Query with comprehensive data
export const getCustomerOrdersQuery = /* GraphQL */ `
  query getCustomerOrders($first: Int = 10) {
    customer {
      orders(first: $first) {
        nodes {
          id
          name
          processedAt
          fulfillmentStatus
          financialStatus
          totalPrice {
            amount
            currencyCode
          }
          subtotal {
            amount
            currencyCode
          }
          totalShipping {
            amount
            currencyCode
          }
          totalTax {
            amount
            currencyCode
          }
          lineItems(first: 50) {
            nodes {
              id
              title
              quantity
              totalPrice {
                amount
                currencyCode
              }
              image {
                url
                altText
              }
              variantId
            }
          }
          billingAddress {
            firstName
            lastName
            company
            address1
            address2
            city
            province
            country
            zip
          }
          shippingAddress {
            firstName
            lastName
            company
            address1
            address2
            city
            province
            country
            zip
          }
        }
      }
    }
  }
`;

// Update Customer Profile Mutation
export const updateCustomerMutation = /* GraphQL */ `
  mutation updateCustomer($input: CustomerUpdateInput!) {
    customerUpdate(input: $input) {
      customer {
        id
        displayName
        firstName
        lastName
        emailAddress {
          emailAddress
        }
        phoneNumber {
          phoneNumber
        }
      }
      userErrors {
        field
        message
      }
    }
  }
`;

// Create Customer Address Mutation with default address support
export const createCustomerAddressMutation = /* GraphQL */ `
  mutation createCustomerAddress(
    $input: CustomerAddressInput!
    $defaultAddress: Boolean
  ) {
    customerAddressCreate(address: $input, defaultAddress: $defaultAddress) {
      customerAddress {
        id
        firstName
        lastName
        company
        address1
        address2
        city
        province
        country
        zip
      }
      userErrors {
        field
        message
      }
    }
  }
`;

// Update Customer Address Mutation
export const updateCustomerAddressMutation = /* GraphQL */ `
  mutation updateCustomerAddress(
    $addressId: ID!
    $input: CustomerAddressInput!
    $defaultAddress: Boolean
  ) {
    customerAddressUpdate(
      addressId: $addressId
      address: $input
      defaultAddress: $defaultAddress
    ) {
      customerAddress {
        id
        firstName
        lastName
        company
        address1
        address2
        city
        province
        country
        zip
      }
      userErrors {
        field
        message
      }
    }
  }
`;

// Delete Customer Address Mutation
export const deleteCustomerAddressMutation = /* GraphQL */ `
  mutation deleteCustomerAddress($addressId: ID!) {
    customerAddressDelete(addressId: $addressId) {
      deletedAddressId
      userErrors {
        field
        message
      }
    }
  }
`;

// Set Default Address Mutation
export const setDefaultAddressMutation = /* GraphQL */ `
  mutation setDefaultAddress($addressId: ID!) {
    customerAddressUpdate(
      addressId: $addressId
      address: {}
      defaultAddress: true
    ) {
      customerAddress {
        id
      }
      userErrors {
        field
        message
      }
    }
  }
`;

// Get Customer Addresses Query
export const getCustomerAddressesQuery = /* GraphQL */ `
  query getCustomerAddresses($first: Int = 10) {
    customer {
      addresses(first: $first) {
        edges {
          node {
            id
            firstName
            lastName
            company
            address1
            address2
            city
            province
            country
            zip
          }
        }
      }
      defaultAddress {
        id
      }
    }
  }
`;

The GraphQL operations above follow Shopify's Customer Account API patterns. Notice how customer queries structure nested data like emailAddress.emailAddress because Shopify wraps some fields in objects for better type safety and API consistency. The order query includes comprehensive order data including line items, addresses, and pricing breakdowns. We use variantId instead of a variant object because the Customer Account API has this specific limitation compared to the Storefront API.

All mutations follow Shopify's standard pattern of returning both the updated object and potential userErrors. This error handling pattern is crucial because Shopify returns validation errors in the userErrors field rather than throwing exceptions. The defaultAddress parameter in create and update mutations is how you set default addresses in the Customer Account API - this was a key discovery that solved our original missing function problem.

Step 2: Generate TypeScript Types

After defining your GraphQL operations, we need to generate the TypeScript types. This step is crucial for maintaining type safety throughout your application and catching errors at compile time rather than runtime. The code generation process reads our GraphQL operations and creates corresponding TypeScript interfaces and SDK functions.

pnpm codegen

Always run codegen after modifying GraphQL operations. This ensures your TypeScript types are in sync with your schema and prevents the runtime errors we discussed earlier. The generated types will include all the proper interfaces for your queries, mutations, and variables, giving you complete type safety across your application.

Setting up GraphQL Code Generation: If you haven't configured GraphQL code generation for your Next.js project yet, check out my comprehensive setup guide: Shopify + TypeScript Codegen in Next.js. This walkthrough covers the complete configuration for multi-API GraphQL codegen with Shopify.

Step 3: Create SDK Utility

This is a crucial step. We're now creating the GraphQL client that can communicate with the Customer Account API. The access token is critical here and must be handled on the server side for security reasons.

The authentication architecture follows a server-side pattern where tokens are stored securely using Next.js 15's cookies() function in HTTP-only cookies. When we interact with the Customer Account API, we must fetch the access token from the server context. This approach ensures that sensitive authentication tokens never reach the client side, maintaining the security model that Shopify requires for customer data access.

Authentication Setup: The complete OAuth2 implementation for Customer Account API authentication is covered in detail in my dedicated article: Implementing Customer Account API authentication. The session management utilities are implemented in lib/auth/session.ts which handles token storage, retrieval, and formatting.

We need to create a utility function that initializes the Customer Account API SDK with proper authentication and token formatting. This step centralizes our API configuration and handles the critical shcat_ token prefix requirement.

// lib/shopify/utils/customer-account-sdk.ts
import { GraphQLClient } from "graphql-request";
import { getSdk } from "../generated/customer-account";
import { SHOPIFY_CUSTOMER_ACCOUNT_API_ENDPOINT } from "lib/constants";

/**
 * Creates Customer Account API SDK client with authentication
 */
export function createCustomerAccountSdk(accessToken: string) {
  // Create a client with custom fetch that handles token formatting
  const client = new GraphQLClient(SHOPIFY_CUSTOMER_ACCOUNT_API_ENDPOINT, {
    fetch: async (url: RequestInfo | URL, init?: RequestInit) => {
      const { formatAccessToken } = await import("lib/auth/session");
      const formattedToken = formatAccessToken(accessToken);

      return fetch(url, {
        ...init,
        headers: {
          ...init?.headers,
          "Content-Type": "application/json",
          Authorization: formattedToken, // Customer Account API expects token directly, no "Bearer" prefix
        },
      });
    },
  });

  return getSdk(client);
}

Critical Details:

• Token Formatting: The formatAccessToken function ensures tokens have the required shcat_ prefix
• No Bearer Prefix: Unlike most APIs, Customer Account API expects the token directly
• Endpoint Constant: Uses SHOPIFY_CUSTOMER_ACCOUNT_API_ENDPOINT for consistency
• Generated SDK: getSdk() is auto-generated by graphql-codegen and provides all your query/mutation methods

Constants Setup:

// lib/constants.ts
export const SHOPIFY_CUSTOMER_ACCOUNT_API_ENDPOINT = `https://shopify.com/${process.env.NEXT_PUBLIC_SHOPIFY_SHOP_ID!}/account/customer/api/2025-04/graphql`;

Token Formatting Function:

// lib/auth/session.ts
export function formatAccessToken(token: string): string {
  return token.startsWith("shcat_") ? token : `shcat_${token}`;
}

Implementation Examples

This section demonstrates practical examples of using the Customer Account API in real applications. These examples show you how to integrate the fetcher functions we've created into Next.js components and server actions, providing concrete patterns you can follow in your own implementation.

The following examples illustrate common scenarios like fetching customer profile data, managing addresses, and retrieving order history. Each example includes proper error handling and follows Next.js 15 App Router best practices.

Fetching Customer Profile Data

Now we'll create wrapper functions around the generated SDK methods. These functions provide proper error handling, TypeScript types, and a clean interface for our React components to consume. The fetchers act as a business logic layer, handling common concerns like authentication, error transformation, and data formatting.

// lib/shopify/fetchers/customer-account/customer.ts
import { createCustomerAccountSdk } from "../../utils/customer-account-sdk";
import type {
  GetCustomerQuery,
  UpdateCustomerMutation,
  CustomerUpdateInput,
} from "../../generated/customer-account";

/**
 * Gets customer profile data with automatic token fallback
 */
export async function getCustomer(
  accessToken?: string
): Promise<GetCustomerQuery["customer"]> {
  let token = accessToken;

  if (!token) {
    const { getTokens } = await import("lib/auth/session");
    const tokens = await getTokens();
    if (!tokens) throw new Error("No access token available");
    token = tokens.accessToken;
  }

  const sdk = createCustomerAccountSdk(token);
  const result = await sdk.getCustomer();
  return result.customer;
}

/**
 * Updates customer profile information
 */
export async function updateCustomer(
  accessToken: string,
  input: CustomerUpdateInput
): Promise<UpdateCustomerMutation["customerUpdate"]> {
  const sdk = createCustomerAccountSdk(accessToken);
  const result = await sdk.updateCustomer({ input });
  return result.customerUpdate;
}

From Read to Write Operations: Now that we've established the basic pattern for reading customer data, let's implement the mutation operations that allow us to actually modify customer information. The Customer Account API provides full CRUD capabilities, enabling us to create, update, and delete customer data while maintaining the same type safety and error handling patterns we've established with our getter functions.

These basic fetchers demonstrate the pattern we'll follow throughout the implementation. Each function creates an SDK instance with the provided access token, calls the appropriate method, and returns the relevant data. The return types are extracted from the generated GraphQL types, ensuring complete type safety.

Update customer data

Now let's implement the more complex address management functions:

// lib/shopify/fetchers/customer-account/addresses.ts
import { createCustomerAccountSdk } from "../../utils/customer-account-sdk";
import type {
  CreateCustomerAddressMutation,
  UpdateCustomerAddressMutation,
  DeleteCustomerAddressMutation,
  SetDefaultAddressMutation,
  CustomerAddressInput,
} from "../../generated/customer-account";

export async function getCustomerAddresses(
  accessToken: string,
  first: number = 10
) {
  const sdk = createCustomerAccountSdk(accessToken);
  const result = await sdk.getCustomerAddresses({ first });
  return result.customer;
}

/**
 * Creates a new customer address
 */
export async function createCustomerAddress(
  accessToken: string,
  input: CustomerAddressInput,
  defaultAddress?: boolean
): Promise<CreateCustomerAddressMutation["customerAddressCreate"]> {
  const sdk = createCustomerAccountSdk(accessToken);
  const result = await sdk.createCustomerAddress({
    input,
    defaultAddress: defaultAddress ?? null,
  });
  return result.customerAddressCreate;
}

/**
 * Updates an existing customer address
 */
export async function updateCustomerAddress(
  accessToken: string,
  addressId: string,
  input: CustomerAddressInput,
  defaultAddress?: boolean
): Promise<UpdateCustomerAddressMutation["customerAddressUpdate"]> {
  const sdk = createCustomerAccountSdk(accessToken);
  const result = await sdk.updateCustomerAddress({
    addressId,
    input,
    defaultAddress: defaultAddress ?? null,
  });
  return result.customerAddressUpdate;
}

/**
 * Deletes a customer address
 */
export async function deleteCustomerAddress(
  accessToken: string,
  addressId: string
): Promise<DeleteCustomerAddressMutation["customerAddressDelete"]> {
  const sdk = createCustomerAccountSdk(accessToken);
  const result = await sdk.deleteCustomerAddress({ addressId });
  return result.customerAddressDelete;
}

/**
 * Sets the default address for a customer
 */
export async function setDefaultCustomerAddress(
  accessToken: string,
  addressId: string
): Promise<SetDefaultAddressMutation["customerAddressUpdate"]> {
  const sdk = createCustomerAccountSdk(accessToken);
  const result = await sdk.setDefaultAddress({ addressId });
  return result.customerAddressUpdate;
}

Each function returns the exact TypeScript type from the generated schema, giving you full autocompletion and compile-time error checking. The defaultAddress: defaultAddress ?? null pattern converts undefined to null, which matches GraphQL's InputMaybe<boolean> type requirement. This was one of the type errors we had to solve during implementation.

Customer Order Management

Order management represents one of the most valuable aspects of the Customer Account API. This functionality allows customers to access their complete purchase history, track shipments, view detailed order information, and understand their relationship with your store over time. The order data includes comprehensive details like line items, shipping addresses, billing information, fulfillment status, and pricing breakdowns - everything needed to build sophisticated order management interfaces.

The Customer Account API provides secure access to order data that respects the user-centric security model we discussed earlier. Only the authenticated customer can access their own orders, ensuring complete privacy and security. This makes it perfect for building customer dashboards, mobile apps with offline order viewing, or integration with customer service tools that need historical order context.

Now let's implement the order fetching functions:

Important API Limitation: The Customer Account API currently doesn't support fetching a single order by ID directly. The workaround is to fetch all customer orders and then filter the results using standard JavaScript array methods. This approach works well in practice since individual customers typically don't have an overwhelming number of orders, making the client-side filtering performant and practical.

// lib/shopify/fetchers/customer-account/orders.ts
import { createCustomerAccountSdk } from "../../utils/customer-account-sdk";

/**
 * Gets customer orders with Customer Account API
 */
export async function getCustomerOrders(
  accessToken?: string,
  first: number = 10
) {
  let token = accessToken;

  if (!token) {
    const { getTokens } = await import("lib/auth/session");
    const tokens = await getTokens();
    if (!tokens) throw new Error("No access token available");
    token = tokens.accessToken;
  }

  try {
    const sdk = createCustomerAccountSdk(token);
    const result = await sdk.getCustomerOrders({ first });
    return result.customer;
  } catch (error) {
    console.error("Error fetching customer orders:", error);
    throw new Error("Failed to fetch customer orders");
  }
}

/**
 * Gets a single customer order by filtering from all orders
 */
export async function getCustomerOrder(orderId: string, accessToken?: string) {
  try {
    // Get all orders using the existing function
    const orders = await getCustomerOrders(accessToken, 250);

    // Convert numeric ID to GID format for comparison
    const orderGid = `gid://shopify/Order/${orderId}`;

    // Find the specific order
    const order = orders
      ? orders.orders.nodes.find((o) => o.id === orderGid)
      : undefined;

    if (!order) {
      throw new Error("Order not found");
    }

    return order;
  } catch (error) {
    console.error("Error fetching customer order:", error);
    throw new Error("Failed to fetch customer order");
  }
}

Key Implementation Patterns:

Our order fetching functions follow several important patterns that ensure reliability and maintainability. The token fallback mechanism allows functions to work both with explicitly passed access tokens and automatic session retrieval, providing flexibility for different usage contexts. Comprehensive error handling uses try-catch blocks with meaningful error messages to help with debugging and user experience. Full TypeScript integration with generated types provides compile-time safety and excellent developer experience with autocompletion. Finally, proper Shopify Global ID format handling ensures that order lookups work correctly with Shopify's ID system, converting between numeric IDs and the required GID format automatically.

EXAMPLE : Usage in Server Components and Server Actions

The Customer Account API integrates perfectly with Next.js 15 App Router patterns. Here are focused examples:

Server Environment Advantage: One of the major benefits of working with the Customer Account API in Next.js 15 is the seamless access to authentication tokens in the server environment. Since tokens are securely stored in HTTP-only cookies and accessed via the cookies() function, you have direct, secure access to customer authentication without any client-side token exposure or management complexity.

Server Component Data Fetching:

// app/account/page.tsx
import { getTokens } from "lib/auth/session";
import { getCustomer } from "lib/shopify/fetchers/customer-account/customer";
import { redirect } from "next/navigation";

export default async function AccountPage() {
  const tokens = await getTokens();
  if (!tokens) redirect("/auth/login");

  const customer = await getCustomer(tokens.accessToken);

  return (
    <div>
      <h1>Welcome, {customer?.firstName}!</h1>
      <p>Email: {customer?.emailAddress?.emailAddress}</p>
    </div>
  );
}

Server Action for Updates:

// app/account/actions.ts
import { updateCustomer } from "lib/shopify/fetchers/customer-account/customer";
import { getTokens } from "lib/auth/session";
import { revalidatePath } from "next/cache";

export async function updateProfile(formData: FormData) {
  const tokens = await getTokens();
  if (!tokens) throw new Error("Not authenticated");

  const input = {
    firstName: formData.get("firstName") as string,
    lastName: formData.get("lastName") as string,
  };

  const result = await updateCustomer(tokens.accessToken, input);

  if (result?.userErrors && result.userErrors.length > 0) {
    throw new Error(result.userErrors[0].message);
  }

  revalidatePath("/account");
  return { success: true };
}

Complete Account Page Example:

// app/account/page.tsx
import { getTokens } from "lib/auth/session";
import { getCustomer } from "lib/shopify/fetchers/customer-account/customer";
import { getCustomerAddresses } from "lib/shopify/fetchers/customer-account/addresses";
import { getCustomerOrders } from "lib/shopify/fetchers/customer-account/orders";
import { redirect } from "next/navigation";

export default async function AccountPage() {
  // Server-side authentication check
  const tokens = await getTokens();
  if (!tokens) redirect("/auth/login");

  // Fetch all customer data in parallel
  const [customer, addressData, orderData] = await Promise.all([
    getCustomer(tokens.accessToken),
    getCustomerAddresses(tokens.accessToken),
    getCustomerOrders(tokens.accessToken, 10),
  ]);

  return (
    <div className="max-w-4xl mx-auto p-6">
      <h1 className="text-2xl font-bold mb-8">My Account</h1>

      {/* Profile Section */}
      <div className="mb-8">
        <h2 className="text-xl font-semibold mb-4">Profile</h2>
        <p>{customer?.firstName} {customer?.lastName}</p>
        <p>{customer?.emailAddress?.emailAddress}</p>
      </div>

      {/* Recent Orders */}
      <div>
        <h2 className="text-xl font-semibold mb-4">Recent Orders</h2>
        {orderData?.orders.nodes.map((order) => (
          <div key={order.id} className="border p-4 rounded mb-4">
            <h3>{order.name}</h3>
            <p>{order.totalPrice.amount} {order.totalPrice.currencyCode}</p>
            <p>{order.fulfillmentStatus} • {order.financialStatus}</p>
          </div>
        ))}
      </div>
    </div>
  );
}

Key Integration Points:

The integration architecture relies on several crucial patterns that work together seamlessly. Server-side token management uses secure HTTP-only cookies to store authentication tokens safely, ensuring that sensitive customer authentication never reaches the client side. The fetcher functions include automatic token fallback mechanisms that can retrieve tokens from the session when not explicitly provided, making the API easier to use across different contexts. Next.js 15 Server Actions handle all mutation operations, providing a secure and efficient way to modify customer data while maintaining proper error boundaries. Comprehensive error handling manages GraphQL validation errors properly, transforming Shopify's userErrors format into actionable feedback for users. Finally, parallel data fetching with Promise.all() optimizes performance by making multiple API calls simultaneously when loading customer account pages.

Alternative: Direct GraphQL Approach

While the SDK approach is not preferred for most use cases, it's still possible to call GraphQL directly if you have specific requirements that the generated SDK doesn't meet. Here's how both approaches compare:

SDK Approach (Recommended):

// Using generated SDK functions
const sdk = createCustomerAccountSdk(accessToken);
const result = await sdk.getCustomer();
return result.customer;

Direct GraphQL Approach:

// Direct GraphQL client usage
import { GraphQLClient } from "graphql-request";
import { getCustomerQuery } from "../queries/customer-account/customer";
import { SHOPIFY_CUSTOMER_ACCOUNT_API_ENDPOINT } from "lib/constants";
import { formatAccessToken } from "lib/auth/session";

const client = new GraphQLClient(SHOPIFY_CUSTOMER_ACCOUNT_API_ENDPOINT, {
  headers: {
    "Content-Type": "application/json",
    Authorization: formatAccessToken(accessToken),
  },
});

const result = await client.request(getCustomerQuery);
return result.customer;

Why SDK is Preferred:

• Type Safety: Generated SDK provides full TypeScript types
• Consistency: Centralized token handling and error patterns
• Maintainability: Schema changes automatically update SDK methods
• Developer Experience: Full autocompletion and compile-time error checking

Both approaches work, but the SDK approach scales better and provides superior developer experience.

Summary

This guide demonstrates a complete implementation of Shopify's Customer Account API with Next.js 15, covering:

✅ What We've Accomplished:

• Proper GraphQL schema setup with comprehensive queries and mutations
• Type-safe implementation using GraphQL Code Generation
• Correct token formatting with required shcat_ prefix
• Server-side authentication and session management
• Efficient fetcher functions with automatic token fallback
• Next.js 15 App Router integration patterns
• Real debugging solutions for common issues

🔑 Key Architectural Decisions:

• SDK over Direct GraphQL: Better developer experience and maintainability
• Server-Side Only Tokens: Secure authentication with HTTP-only cookies
• Token Fallback Pattern: Functions work with explicit or session-based tokens
• Parallel Data Fetching: Better performance with Promise.all()
• Comprehensive Error Handling: Proper GraphQL userErrors handling

Setting Up GraphQL Code Generation

Note: If you haven’t set up GraphQL Code Generation yet, I’ve written a step-by-step guide specifically for Next.js 15 projects.

Working with GraphQL and TypeScript requires precise query structure and accurate type definitions. To simplify this, I recommend using a codegen tool to automatically generate types from your schema and queries. If you’d like to see how to set this up, check out my walkthrough here: Shopify + TypeScript Codegen in Next.js

Conclusion

In this comprehensive guide, we've covered the complete implementation of customer data management using Shopify's Customer Account API. We started by understanding the common challenges developers face when working with GraphQL code generation and the specific requirements of the Customer Account API.

What we accomplished:

• Set up comprehensive GraphQL queries and mutations for all customer operations
• Implemented type-safe fetcher functions with proper error handling
• Created reusable React components that handle real-world user interactions
• Established debugging strategies for common issues
• Provided production-ready patterns for authentication and data management

Why this approach matters: The Customer Account API represents Shopify's modern approach to headless commerce, providing full control over customer experiences while maintaining security and performance. By using GraphQL code generation, we achieve type safety that prevents runtime errors and improves developer productivity. The pattern we've established scales well from simple profile updates to complex multi-address management scenarios.

The key takeaway: Success with the Customer Account API comes from understanding its OAuth requirements, properly handling GraphQL validation errors, and maintaining synchronization between your schema definitions and generated types. This foundation enables you to build sophisticated customer account experiences that rival or exceed traditional e-commerce platforms.

By following these patterns, you'll avoid the common pitfalls that trip up developers and create maintainable, scalable customer account functionality that your users will appreciate.

Thanks, Matija