Shopify Customer Account MCP: How to Use (2026)

What the Shopify Customer Account MCP Actually Is

If you have ever tried wiring up an AI assistant that can answer "Where is my order?" without bouncing the shopper through three support tickets, you already know the wall you hit: the AI has no idea who the customer is. That is the gap Shopify's Customer Account MCP server closes. It is the only one of Shopify's four MCP servers that exposes authenticated, per-shopper data — order history, fulfillment status, return requests, account details — through a standardized Model Context Protocol interface that large language models can call directly.

The catch? It is also the trickiest to implement. Unlike the Storefront MCP (which is anonymous and plug-and-play) or the Dev MCP (which runs locally for developers), the Customer Account MCP requires a full OAuth 2.0 authorization code flow with Proof Key for Code Exchange (PKCE), a custom domain on your Shopify store, and Level 2 protected customer data approval. Most engineering teams budget 3-5 days and then spend 1-2 weeks untangling redirect URIs, token storage, and the dreaded "invalid client credentials" error.

This guide walks through the whole thing end-to-end. We cover what the Customer Account MCP does differently, how OAuth + PKCE actually work, the exact setup steps with code, how to test against a real customer account, production deployment considerations, privacy and GDPR obligations, and the AI concierge use cases that justify the effort. If you are building agentic commerce experiences, bookmark this alongside our broader Shopify development resources and the AI and emerging tech hub.

How It Compares to the Dev and Storefront MCPs

Shopify now ships four production MCP servers (Dev, Storefront, Customer Account, and Checkout). They sound similar but solve very different problems. Picking the wrong one is the single most common mistake teams make on their first MCP integration.

The Dev MCP runs locally via npx @shopify/dev-mcp@latest. It exposes Shopify documentation search, GraphQL Admin API schema introspection, and Liquid validation. There is no authentication because it never touches production data — it is a developer productivity tool that plugs into Claude Code, Cursor, or any MCP-compatible client.

The Storefront MCP is the shopping assistant server. It lets an AI browse a store's catalog, add items to a cart, and answer policy questions — all anonymously. No login, no tokens, no PKCE. It is perfect for conversational shopping widgets on the homepage or an embedded ChatGPT experience. For the full breakdown, see Shopify's Storefront MCP documentation.

The Customer Account MCP is where things get interesting — and complicated. It assumes the shopper has already logged in, then exposes tools that read and mutate that specific customer's data: their orders, their saved addresses, their open returns. Because it handles personal data, Shopify requires OAuth 2.0 with PKCE for authentication.

Quick Comparison Table

When to Pick the Customer Account MCP

Use it when your assistant needs to say "Your order #1084 shipped yesterday via UPS and will arrive Thursday" — not "Here is a link to our order lookup page." If your assistant can solve the problem without knowing who the shopper is, use Storefront MCP instead. Teams also commonly pair the two so an anonymous shopping conversation can seamlessly upgrade into an authenticated support flow after login.

OAuth 2.0 + PKCE: The Primer You Wish You Had

Before writing any code, internalize the mental model. PKCE exists because public clients (browsers, mobile apps, anything where you cannot safely store a client secret) need a way to prove they started an OAuth flow without shipping a static secret that attackers could steal.

Here is how the choreography works. Your app generates a random string called a code verifier (between 43 and 128 characters). It hashes that verifier with SHA-256 and base64url-encodes the result to produce a code challenge. The challenge gets sent to Shopify's authorization endpoint when the customer clicks "Log in." After the customer authenticates, Shopify redirects back to your app with an authorization code. Your app then exchanges that code for an access token by POSTing both the code and the original verifier. Shopify re-hashes the verifier, compares it to the challenge it stored earlier, and only issues tokens if they match.

The elegance: even if an attacker intercepts the authorization code in the redirect URL, they cannot redeem it without also knowing the verifier — which never leaves your app. For the full specification, see OAuth.com's PKCE guide and RFC 7636.

Generating Verifier and Challenge in Node

Shopify's Customer Account API requires the S256 challenge method. Here is the minimum viable helper:

import crypto from "node:crypto";

export function generatePkcePair() {
  const verifier = crypto.randomBytes(64).toString("base64url");
  const challenge = crypto
    .createHash("sha256")
    .update(verifier)
    .digest("base64url");
  return { verifier, challenge };
}

Store the verifier server-side (Redis, signed cookie, or database) keyed by the state parameter you also generate. Never put the verifier in a URL — that defeats the point.

The Shopify-Specific Wrinkle

Before you can hit the authorization endpoint, you need to discover it. Shopify publishes an OpenID Connect configuration document at https://<shop-custom-domain>/.well-known/openid-configuration. That document returns the real authorization_endpoint, token_endpoint, jwks_uri, and end_session_endpoint. Hardcoding these URLs will bite you the first time Shopify rotates them.

Prerequisites Before You Write a Single Line

The Customer Account MCP has hard gating requirements. Miss one and you will see cryptic 401s for days.

• Custom domain configured on the store. You cannot use *.myshopify.com. You need a domain the merchant owns, verified in the Shopify admin under Settings → Domains.
• New Customer Accounts enabled. Classic (legacy) customer accounts do not support the OAuth flow. Toggle this in the admin under Settings → Customer accounts.
• Partner app with Customer Account API scopes. Create your app in the Shopify Partner Dashboard and enable customer-account-api:full access.
• Level 2 protected customer data approval. Shopify separates customer data into Level 1 (basic) and Level 2 (name, address, email, phone). Customer Account MCP requires Level 2. Request this in your app's Partner Dashboard settings — approval usually takes 2-5 business days and requires answering a questionnaire about how you store, encrypt, and purge customer data. See Shopify's protected customer data documentation for the full checklist.
• HTTPS redirect URI. Your callback URL must be served over HTTPS in production. For local testing, a tunnel like Cloudflare Tunnel or ngrok works, but plain http://localhost will fail.

Skip the scopes step and you will spend an afternoon Googling "authentication failed client credentials invalid." Skip the Level 2 approval and the MCP server will return empty tool lists with no error.

Setup Walkthrough: From Zero to First Token

Let's build the minimum viable integration in Node with React Router (Shopify's current recommended framework for apps). The same pattern maps cleanly to Next.js, Remix, or Rails.

Step 1 — Discover the OIDC Configuration

async function discoverEndpoints(shopDomain) {
  const res = await fetch(
    `https://${shopDomain}/.well-known/openid-configuration`
  );
  if (!res.ok) throw new Error(`Discovery failed: ${res.status}`);
  return res.json();
}

Cache the result for 15 minutes. Do not call this on every request.

Step 2 — Build the Authorization URL

import { generatePkcePair } from "./pkce.js";

export async function buildAuthUrl({ shopDomain, clientId, redirectUri }) {
  const config = await discoverEndpoints(shopDomain);
  const { verifier, challenge } = generatePkcePair();
  const state = crypto.randomUUID();
  const nonce = crypto.randomUUID();

  // Persist verifier + state server-side, keyed by state
  await sessionStore.set(state, { verifier, nonce });

  const params = new URLSearchParams({
    client_id: clientId,
    response_type: "code",
    redirect_uri: redirectUri,
    scope: "openid email customer-account-api:full",
    state,
    nonce,
    code_challenge: challenge,
    code_challenge_method: "S256",
  });

  return `${config.authorization_endpoint}?${params.toString()}`;
}

The shopper clicks a "Log in to see your orders" button, you redirect them to this URL, and Shopify handles the credential collection and MFA if enabled.

Step 3 — Exchange the Authorization Code

Shopify redirects back to your redirect_uri with ?code=...&state=.... Look up the verifier by state, then exchange:

export async function exchangeCodeForToken({
  shopDomain,
  code,
  state,
  clientId,
  clientSecret,
  redirectUri,
}) {
  const config = await discoverEndpoints(shopDomain);
  const session = await sessionStore.get(state);
  if (!session) throw new Error("Invalid state");

  const body = new URLSearchParams({
    grant_type: "authorization_code",
    client_id: clientId,
    client_secret: clientSecret,
    redirect_uri: redirectUri,
    code,
    code_verifier: session.verifier,
  });

  const res = await fetch(config.token_endpoint, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body,
  });

  if (!res.ok) {
    const err = await res.text();
    throw new Error(`Token exchange failed: ${err}`);
  }

  return res.json(); // { access_token, refresh_token, expires_in, id_token }
}

Store the access_token encrypted at rest. Tokens expire (usually 3600 seconds) — keep the refresh_token so you can silently renew without bouncing the shopper back through the login flow.

Step 4 — Call the Customer Account MCP Server

Now the fun part. With a valid access token, you can hit the MCP endpoint directly:

const response = await fetch(
  `https://${shopDomain}/api/mcp/customer-account`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${accessToken}`,
    },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: 1,
      method: "tools/list",
    }),
  }
);

This returns the available tools — typically get_orders, get_order_details, get_customer_info, create_return_request, and a handful of others that Shopify ships or updates via the MCP registry. Wire these into your LLM of choice (Claude, GPT-4o, Gemini) using its native tool-calling interface.

Testing Locally with a Real Customer Account

Tunnel your local server through a public HTTPS endpoint. Cloudflare Tunnel is free and does not expire like ngrok's free tier does. Register the tunnel URL as a redirect URI in your Partner Dashboard app settings.

Create a test customer in your development store — Shopify development stores let you add fake customers with real-looking order data. Log in as that customer via your integration's front-end flow. If everything is wired correctly, you will land back on your callback route with code and state query params, exchange them for a token, and successfully call tools/list.

The Debug Checklist

When something breaks (and it will), work through this in order:

• Is the shop domain the custom domain, not the myshopify.com one?
• Did you fetch the OIDC config fresh, or are you hardcoding stale endpoints?
• Does your redirect URI match exactly — including trailing slash — what is registered in the Partner Dashboard?
• Is the code_challenge base64url (no padding, - not +, _ not /)?
• Is the code_verifier the same one you generated before the redirect, not a new one?
• Did you include openid in the scope list? Shopify requires it for Customer Account API.

The Shopify Developer Community forum thread on Customer Accounts MCP authentication failures is a rich vein of real-world gotchas if you hit something weirder.

Stubbing Tokens for Offline Tests

Do not mock the OAuth dance in unit tests — it hides bugs. Instead, record a real token exchange once, store the response as a fixture, and replay it. For integration tests, spin up a dev store and use vitest or jest with a tunnel that stays alive for the suite run.

Shipping to Production

Preview works. Now you need to keep it running reliably for real shoppers.

Token Storage and Rotation

Never put access tokens in localStorage. Store them in an HTTP-only, Secure, SameSite=Lax cookie bound to your domain, or server-side against a session ID. Encrypt tokens at rest using AES-GCM with a key managed by your secrets provider (AWS KMS, GCP KMS, Vercel environment variables for smaller teams).

Implement refresh on a 5-minute-before-expiry buffer. If the refresh token itself expires (Shopify sets this to 7 days of inactivity by default), force a re-authentication gracefully — redirect the shopper back to the login flow with a state param that returns them to the conversation mid-thread.

Rate Limits and Retries

The Customer Account API is subject to standard Shopify rate limits. Implement exponential backoff with jitter on 429 responses. If your MCP tool call fails mid-conversation, the LLM should surface a friendly "I am having trouble reaching your account right now — please try again in a moment" rather than throwing a raw error.

Monitoring and Observability

Log every tool invocation with the customer ID (hashed), the tool name, latency, and outcome. If a tool fails more than 1% of the time, alert. A good pattern is to tag traces with a conversation ID so you can trace one shopper's entire session across your app, the MCP server, and back.

For deployment specifics, Auth0's authorization code with PKCE reference and Spotify's code-with-PKCE tutorial are both worth reading — the Spotify guide is notable for showing a clean browser-side implementation pattern that adapts well to Shopify. If you are running a headless storefront, pair this with our Shopify headless commerce guide.

Privacy, GDPR, and the Level 2 Data Obligations

This is not a section to skim. Getting privacy wrong with Customer Account MCP is how apps get removed from the Shopify App Store and how merchants get fined.

What Level 2 Requires

Shopify's protected customer data program classifies order history, addresses, and contact details as Level 2. To access them you must attest to (and actually implement) the following:

• Data minimization. Only fetch the fields your AI actually needs. If the shopper asked "Where's my order?" do not pull the full customer record — pull the order and fulfillment only.
• Encrypted storage. Data at rest must be encrypted. Database column-level encryption or whole-disk encryption both satisfy this, but the former is safer.
• Backup encryption. Your nightly backups count. If you dump the database to S3, set default encryption on the bucket.
• Production/test separation. Do not seed your staging environment with production customer data. Ever.
• Staff access controls. Require MFA for any engineer who can query production customer data. Log every admin query.
• Data retention and purge. Define how long you keep MCP conversation logs. 30 days is a reasonable default; longer requires justification.

GDPR and CCPA Specifics

The EU's GDPR (and California's CCPA) give shoppers the right to export or delete their data. If a customer requests deletion, you must purge their MCP conversation history, any cached orders, and any derived data (embeddings, summaries) within 30 days. Build a deletion endpoint that accepts the customer ID and recursively purges across every data store.

Shopify sends GDPR webhooks (customers/data_request, customers/redact, shop/redact) that your app must subscribe to. Your redact handler is the piece most teams forget. The Shopify Partners blog on customer personal data requirements covers the exact webhook payloads.

Consent and Transparency

Before the first MCP tool call that uses the shopper's data, your UI should make clear that an AI assistant is accessing their account. A single sentence in your privacy policy is not enough — show it inline the first time. Consent logs matter if regulators ever come asking.

Use Case #1: The AI Concierge Chatbot

The headline use case. A shopper lands on your storefront, opens the chat widget, and asks "Where is my last order and when will it arrive?" Without Customer Account MCP, the bot pivots to "Please log in and check your order status page." With it, the bot prompts for login (or detects an existing session), then responds: "Your order #1084 shipped via UPS on April 18 and is scheduled to arrive Wednesday, April 22. Want the tracking link?"

Design the conversation so authentication is a natural step, not a roadblock. If the shopper asks a question that needs their data, prompt: "I can check that for you — mind signing in?" and trigger the OAuth flow inline via a popup or embedded iframe.

Multi-Turn Session Design

The MCP tool list changes what your LLM can do. Seed the system prompt with the available tools and concise descriptions. Most LLMs pick the right tool 90%+ of the time if the descriptions are clear. For failure modes, pair this with the broader patterns in our best AI chatbot for Shopify customer service roundup.

Use Case #2: Support Automation and Returns

The second-biggest win. Support tickets about "where's my order" are the highest-volume, lowest-value category for most DTC brands. An AI agent with Customer Account MCP can resolve 60-80% of them without human intervention.

Returns are the more interesting opportunity. The create_return_request tool lets an agent initiate a return, ask the shopper which items and why, generate the return label, and email it — all in one conversation. Shopify's standard return flow takes 5-8 clicks; an AI concierge can do it in 3 messages.

Pair this with agentic commerce patterns and you can build a support experience that feels like texting a friend who happens to work at the brand. Merchants on Shopify Plus often combine this with Flow automations — see our Shopify Plus resources for the downstream orchestration.

Personalized Post-Purchase Experiences

Less obvious but high-leverage. After a purchase, send a thank-you email that links to an AI assistant primed with the customer's order history. The assistant can recommend complementary products ("You bought the espresso machine — most customers also add the milk frother within 30 days"), surface care instructions, or proactively answer questions about shipping delays.

This pattern works especially well for brands with complex products (supplements, skincare regimens, tech). The assistant becomes a 24/7 onboarding specialist without the staffing cost. Teams at agencies like Presta's 2026 guide to Shopify MCP servers document similar post-purchase automations with measurable retention lift.

Common Mistakes That Waste Days

Every team building their first Customer Account MCP integration hits a subset of these. Knowing them in advance saves a week.

Mistake #1 — Using the myshopify.com Domain

The Customer Account API and MCP endpoints only work with the store's custom domain. my-store.myshopify.com will return 404s on the discovery endpoint. Always use the domain from Settings → Domains → Primary.

Mistake #2 — Skipping the Discovery Step

Hardcoding authorization_endpoint works until Shopify rotates the URL during a platform upgrade. Your integration then silently breaks. Always fetch /.well-known/openid-configuration and cache for 15 minutes max.

Mistake #3 — Storing the Code Verifier Client-Side

If you put the verifier in localStorage or a non-HttpOnly cookie, a rogue script can steal it and the interception protection PKCE provides collapses. Keep it server-side, period.

Mistake #4 — Forgetting the openid Scope

The scope list must include openid for the Customer Account API to return a usable token. Miss it and you get a 400 with an unhelpful error message.

Mistake #5 — Not Handling Refresh Tokens

Access tokens expire in an hour. If you do not handle refresh, every shopper has to re-authenticate every hour — a usability disaster. Build refresh into your middleware from day one.

Mistake #6 — Skipping GDPR Webhooks

Shopify will email your listed contact if you fail to respond to customers/redact requests. Repeated failures get apps delisted. Subscribe to all three mandatory webhooks (customers/data_request, customers/redact, shop/redact) before you ship.

Mistake #7 — Mocking OAuth in Tests

Teams that mock the token exchange miss real bugs. Record a real flow once, replay the fixtures, and run a weekly integration test against a dev store to catch Shopify-side changes early.

Mistake #8 — Over-Permissioning

Request only the scopes you actually use. Level 2 approval is harder to get if your justification is vague. "We need orders, returns, and basic profile" is defensible. "We need everything" is not.

Where to Go From Here

The Customer Account MCP is the most technically demanding of Shopify's MCP servers — and the one with the most commercial upside. AI concierges that can actually see a shopper's account turn support cost centers into retention engines. The 1-2 week integration cost is real, but it is a one-time investment for a capability that compounds every month after.

Start with the Dev MCP locally to build intuition, layer in the Storefront MCP for anonymous browsing, then graduate to Customer Account MCP once you have a working conversation pattern. For follow-up reading on the broader AI ecosystem, browse the Talk Shop blog or join the Talk Shop community to compare notes with other developers building agentic commerce experiences.

Have you shipped a Customer Account MCP integration yet, or are you stuck on a specific step? Drop into the community and tell us what broke — chances are someone else already solved it.

About Talk Shop

The Talk Shop team — insights from our community of Shopify developers, merchants, and experts.