---
title: Environment Variables
description: Required storefront credentials and optional settings for customer accounts, chat, and integrations.
url: "https://shop-docs.labs.vercel.dev/docs/reference/env-vars"
docs_index: /llms.txt
lastUpdated: 2026-10-11
type: reference
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

Use `.env.local` for local development and your hosting platform's environment settings for deployments. Do not commit local credentials. Only browser-safe values belong in variables prefixed with `NEXT_PUBLIC_`.

## Required

These three values identify your Shopify store and connect the storefront.

| Variable                                      | Description                                                                                                                           |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `NEXT_PUBLIC_SHOPIFY_STORE_DOMAIN`            | Store domain, such as `your-store.myshopify.com`. Find it in **Settings → Domains** in Shopify admin.                                 |
| `NEXT_PUBLIC_SHOPIFY_STOREFRONT_ACCESS_TOKEN` | Public, browser-safe Storefront API token. In Shopify admin, under **Sales channels**, click **Headless** and select your storefront. |
| `NEXT_PUBLIC_SHOPIFY_SHOP_ID`                 | Numeric Shopify shop ID, distinct from the Headless storefront ID.                                                                    |

Shopify's default customer accounts URL has the form `https://shopify.com/123456789/account`, where `123456789` is the shop ID. `pnpm dev`, `pnpm build`, and `pnpm start` fail if any of the three values is missing.

## Customer authentication

Customer sign-in is **disabled by default**. These values are required when you enable `auth.isEnabled` in [Shop Configuration](/docs/reference/shop-config). Follow [Authentication](/docs/anatomy/authentication) to configure Shopify and its callback URLs.

| Variable                                     | Description                                                                                   |
| -------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `CUSTOMER_ACCOUNT_SESSION_SECRET`            | App-generated secret for encrypting customer session cookies. Shopify does not supply it.     |
| `SHOPIFY_CUSTOMER_ACCOUNT_API_CLIENT_ID`     | Client ID from **Sales channels → Headless → Customer Account API** in Shopify admin.         |
| `SHOPIFY_CUSTOMER_ACCOUNT_API_CLIENT_SECRET` | Server-only client secret issued by Shopify for the confidential Customer Account API client. |

Generate `CUSTOMER_ACCOUNT_SESSION_SECRET` with `openssl rand -base64 32`. Keep the same value across all instances of a deployment. Rotating it signs out existing customers. Keep both the session secret and Shopify client secret server-only.

## Shop Agent

Shop Agent is **disabled by default** and needs no AI credentials while disabled. To enable it, follow [Shop Agent setup](/docs/anatomy/agent).

| Variable                | When to set it                                                                                                                                                                                |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AI_GATEWAY_API_KEY`    | Set a server-only Gateway key when running Shop Agent without Vercel deployment identity authentication, including local development without that authentication.                             |
| `UCP_AGENT_PROFILE_URL` | Override the public profile used for Shopify catalog search. Defaults to `/agent/ucp-profile.json` at `site.url`; local development and Vercel previews use Shopify's public example profile. |

## Optional

| Variable                            | When to set it                                                                                                                        |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `DEBUG_SHOPIFY`                     | Set to `1` or `true` when troubleshooting Shopify API requests. Enables detailed operation and timing logs.                           |
| `NEXT_PUBLIC_SHOPIFY_STOREFRONT_ID` | Set to the numeric ID of your Headless storefront. Shopify uses it to attribute storefront traffic and analytics to that storefront.  |
| `SHOPIFY_API_VERSION`               | Override the Storefront API version. Defaults to the version Hydrogen targets; this does not select the Customer Account API version. |
| `SHOPIFY_WEBHOOK_SECRET`            | Set when configuring Shopify webhooks. Used to verify signatures on `POST /api/webhooks/shopify`.                                     |

## Platform-provided values

Vercel supplies `VERCEL_PROJECT_PRODUCTION_URL`, which sets the default production origin. Without it, `site.url` defaults to `http://localhost:3000`. For another host or a custom origin, set `site.url` in [Shop Configuration](/docs/reference/shop-config).

Vercel supplies `VERCEL_ENV`, and `eve dev` sets `EVE_DEV`. You do not need to set either value.

`V0_CALLBACK_URL` is supplied by v0 previews to disable image optimization there. You do not need to set it for ordinary development or deployment.

---

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)