--- title: Proxy description: Add routing rules without interrupting Shopify services or storefront pages. url: "https://vercel.shop/docs/anatomy/proxy" docs_index: /llms.txt lastUpdated: 2026-10-13 type: guide --- > For an index of all documentation, see [/llms.txt](/llms.txt). The storefront's [Next.js proxy](https://nextjs.org/docs/app/getting-started/proxy), also called middleware, keeps Shopify's service routes separate from storefront pages and custom APIs. The default routing works without additional setup. ## What it handles The proxy serves cart updates at `/api/cart` and search suggestions at `/api/predictive-search`. It also hands these Shopify paths to Shopify before any storefront page renders: - `/api/mcp` and `/api/ucp/mcp`, Shopify's agent endpoints - `/.well-known/ucp`, Shopify's business profile - `/api//graphql.json`, Storefront API requests - `/checkout`, which redirects to Shopify checkout for the current cart - Cart permalinks such as `/cart/:` and buy permalinks under `/buy/` - Legacy cart URLs such as `/cart.js` and `/cart/add.js` Customer sign-in routes are available only when you enable [customer authentication](/docs/anatomy/authentication). Shop Agent is enabled separately and uses `/eve/v1/` for conversations. Requests under `/eve/` skip the proxy, so proxy rules never apply to Shop Agent conversations. Ordinary pages continue to Next.js. Home, product, collection-detail, and search pages can also return Markdown for clients that request it. See [Routes](/docs/reference/routes) for page URLs and service endpoints. Custom API routes and other requests that Shopify does not own continue to Next.js unchanged. ## Add routing without creating conflicts When extending `proxy.ts`, match only the routes an integration needs. Do not redirect every `/api/` request or claim all `/agent/` paths: Shopify and Shop Agent serve different endpoints. Do not redirect `/api/agent/session` or `/agent/ucp-profile.json`; Shop Agent uses them to prepare the shopper's cart and to identify itself to Shopify. Keep Shopify routing ahead of locale negotiation, experiments, and request-dependent redirects. A cart update or Shopify API request should not be redirected to a language-prefixed page. Use Next.js configuration for fixed redirects, such as moving an old page to a new URL. Use the proxy when the destination depends on the incoming request. ## Shopify redirects on missing pages Set `redirects.shopifyNotFound.isEnabled` to `true` in `lib/config/index.ts` to enable Hydrogen's built-in redirects for missing pages. It is disabled by default. Saved redirects require Shopify lookups, and the response may retain a `404` status. Use Next.js redirects when a permanent HTTP redirect is required. ## What’s next Add locale routing with [Shopify Markets](/docs/skills/enable-shopify-markets) or [i18n](/docs/skills/enable-i18n), or introduce request-dependent experiments and redirects. Keep those rules scoped to storefront pages so cart, sign-in, and API requests continue to work. --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)