---
title: Proxy
description: Add routing rules without interrupting Shopify services or storefront pages.
url: "https://shop-docs.labs.vercel.dev/docs/anatomy/proxy"
docs_index: /llms.txt
lastUpdated: 2026-09-21
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 supports cart updates, search suggestions, Shopify API access, and Shopify-compatible commerce endpoints. This includes legacy cart URLs and Shopify's business profile at `/.well-known/ucp`.

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.

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 are not intercepted unless they match a route explicitly reserved for an integration.

## 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.

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)