@spree/docs 0.1.132 → 0.1.134

package/dist/developer/core-concepts/channels.md

@@ -20,6 +20,8 @@ Every store ships with one default channel named *Online Store*. You can add mor
 | `code` | URL-safe slug, stable identifier sent via the `X-Spree-Channel` header | `pos` |
 | `active` | When `false`, the channel stops accepting orders | `true` |
 | `default` | Exactly one channel per store is the default. Used as a fallback when no channel header is present and as the auto-publish target for new products | `true` |
+| `storefront_access` | Controls what an anonymous visitor may see: `public`, `prices_hidden`, or `login_required`. Unset inherits the store's setting. See [Storefront Access Gating](#storefront-access-gating) | `login_required` |
+| `guest_checkout` | Whether an order may be placed without an account on this channel. Unset inherits the store's setting | `false` |
 | `preferred_order_routing_strategy` | Optional per-channel override of the store's [Order Routing](shipments.md#order-routing) strategy | `Spree::OrderRouting::Strategy::Rules` |
 
 `code` is normalized to a URL-safe slug on save — `POS` becomes `pos`, `Point of Sale!` becomes `point-of-sale`. Leaving `code` blank derives it from `name`.
@@ -89,6 +91,52 @@ Every order is attributed to one channel. The channel is set from the `X-Spree-C
 
 This attribution drives reporting (best-selling by channel, revenue per channel) and per-channel order routing — see [Order Routing](shipments.md#order-routing).
 
+### Storefront Access Gating
+
+
+A channel's `storefront_access` decides what an **anonymous** visitor — a request with no authenticated customer — may see. Logged-in customers are never gated. The posture is one of three values:
+
+| Mode | Guest sees catalog | Guest sees prices | Use case |
+|---|---|---|---|
+| `public` | Yes | Yes | The default. An open storefront — anyone can browse; guests can also check out when `guest_checkout` is enabled. |
+| `prices_hidden` | Yes | No — prices come back `null` | A catalog you want discoverable, with pricing revealed only after sign-in (e.g. a trade catalog for lead generation). |
+| `login_required` | No — reads rejected with `401` | No | A fully gated surface — a guest can't read the catalog at all (e.g. a members-only or B2B wholesale portal). |
+
+The gate is enforced by the **Store API**, not the storefront, so a storefront app can't loosen it:
+
+- **`login_required`** — every gated read returns `401` for an unauthenticated request. Endpoints that must stay reachable before sign-in (authentication, password reset, reference data like countries and currencies) are exempt.
+- **`prices_hidden`** — reads succeed, but every money field is serialized as `null` for a guest. The storefront renders these as a sign-in prompt rather than a price.
+
+A companion control, **`guest_checkout`**, decides whether an order can be placed without an account on the channel. It's independent of `storefront_access` — a `public` channel can still require accounts, and the two are resolved separately.
+
+#### Store fallback
+
+Both controls fall back to the owning [Store](stores.md) when the channel's own value is unset — the same inheritance pattern as the channel's order-routing strategy. `storefront_access` resolves to the channel value, then the store value, and finally `public` when neither is set. This lets you set a store-wide default (e.g. "all channels require login") and override per channel where needed.
+
+
+```typescript Admin SDK
+// Gate a channel behind sign-in, and require accounts at checkout
+await adminClient.channels.update('ch_wholesale', {
+  storefront_access: 'login_required',
+  guest_checkout: false,
+})
+
+// Clear the channel value to inherit the store's default
+await adminClient.channels.update('ch_wholesale', {
+  storefront_access: null,
+})
+```
+
+```bash cURL
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/channels/ch_wholesale' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{ "storefront_access": "login_required", "guest_checkout": false }'
+```
+
+
+Switching a channel between modes takes effect immediately — the posture is resolved per request, so no cache warm-up or redeploy is needed. The Next.js storefront's [wholesale portal](../storefront/nextjs/wholesale.md) is a worked example of a `login_required` / `prices_hidden` channel driving the UI.
+
 ## Publishing Products on Channels
 
 ### Dashboard
@@ -172,3 +220,4 @@ The write contract is **full-set**: the array represents the complete desired st
 - [Order Routing](shipments.md#order-routing) — Channels can override the store's routing strategy
 - [Store SDK: Products](../sdk/store/products.md) — Channel-scoped product listing and filtering
 - [Admin SDK: Resources](../sdk/admin/resources.md) — How `adminClient.channels.addProducts` and other resource methods are structured
+- [Wholesale Portal](../storefront/nextjs/wholesale.md) — A gated channel driving the Next.js storefront's B2B surface

package/dist/developer/core-concepts/stores.md

@@ -5,7 +5,9 @@ description: Understand Spree Stores — the top-level tenant boundary that scop
 
 ## Overview
 
-The StThe Store is the top-level tenant in Spree. Every resource — products, orders, channels, markets, taxonomies — belongs to exactly one store. A store owns its [channels](channels.md) (online, POS, wholesale, …), its [markets](markets.md) (region/currency/locale), and its [product catalog](products.md).tore Attributes
+The Store is the top-level tenant in Spree. Every resource — products, orders, channels, markets, taxonomies — belongs to exactly one store. A store owns its [channels](channels.md) (online, POS, wholesale, …), its [markets](markets.md) (region/currency/locale), and its [product catalog](products.md).
+
+## Store Attributes
 
 | Attribute | Description |
 |-----------|-------------|
@@ -19,6 +21,8 @@ The StThe Store is the top-level tenant in Spree. Every resource — products, o
 | `mail_from_address` | Sender address for transactional emails |
 | `logo_url` | URL to the store's logo |
 | `facebook`, `twitter`, `instagram` | Social media links |
+| `storefront_access` | Store-wide default for anonymous [storefront access gating](channels.md#storefront-access-gating) (`public`, `prices_hidden`, `login_required`). Each channel can override it |
+| `guest_checkout` | Store-wide default for whether orders can be placed without an account. Each channel can override it |
 
 ## Fetching Store Information
 
@@ -54,6 +58,10 @@ Two different ways to split a store, often confused:
 
 A single Online Store channel can serve multiple markets (one storefront → many regions). Conversely, POS and Online channels can share the same market (same currency/locale, different selling surfaces).
 
+### Storefront access defaults
+
+The store sets the fallback for **storefront access gating** — whether anonymous visitors may browse, see prices, or must sign in first — via `storefront_access` (`public`, `prices_hidden`, `login_required`) and the companion `guest_checkout` control. Each channel inherits these unless it sets its own value, so you can gate a whole store or just one channel (e.g. a `login_required` wholesale channel on an otherwise `public` store). The full behavior of each mode and how the Store API enforces it lives in [Channels → Storefront Access Gating](channels.md#storefront-access-gating).
+
 ## Store Resources
 
 Each store owns its own resources. Products, orders, channels, markets, and taxonomies in one store are independent from another.
@@ -64,7 +72,7 @@ Each store owns its own resources. Products, orders, channels, markets, and taxo
 | [**Markets**](markets.md) | A store has many markets, each defining a geographic region with its own currency and locale |
 | [**Orders**](orders.md) | An order belongs to one store and one channel |
 | [**Products**](products.md) | A product belongs to one store. Its visibility across channels is controlled by [publications](channels.md#publishing-products-on-channels). |
-| [**Taxonomies**](products.md#categories) | A taxonomy belongs to one store |
+| [**Categories**](products.md#categories) | A category belongs to one store |
 | [**Payment Methods**](payments.md) | A payment method belongs to one store |
 | [**Shipping Methods**](shipments.md) | A shipping method belongs to one store |
 | [**Promotions**](promotions.md) | A promotion belongs to one store |
@@ -82,4 +90,5 @@ If you need one Spree backend to serve **multiple distinct merchant brands** —
 - [Markets](markets.md) — Multi-region commerce within a store
 - [Products](products.md) — Product catalog
 - [Orders](orders.md) — Order management and checkout
+- [Wholesale Portal](../storefront/nextjs/wholesale.md) — A gated B2B storefront surface built on channel access gating
 - [Admin SDK](../sdk/admin/quickstart.md) — TypeScript client for the Admin API used to read and update store configuration

package/dist/developer/storefront/nextjs/architecture.md

@@ -38,20 +38,29 @@ src/
 │       │   │   └── [slug]/          # Product details
 │       │   ├── t/[...permalink]/    # Category pages
 │       │   └── categories/          # Category overview
-│       └── (checkout)/              # Checkout layout (no header/footer)
-│           ├── checkout/[id]/       # Checkout flow
-│           └── order-placed/[id]/   # Order confirmation
+│       ├── (checkout)/              # Checkout layout (no header/footer)
+│       │   ├── checkout/[id]/       # Checkout flow
+│       │   └── order-placed/[id]/   # Order confirmation
+│       └── (wholesale)/             # Opt-in B2B portal (gated — see Wholesale guide)
+│           └── wholesale/
+│               ├── page.tsx         # Trade catalog
+│               ├── products/[slug]/ # Wholesale PDP
+│               ├── cart/            # Wholesale cart
+│               ├── quick-order/     # SKU quick-order form
+│               ├── apply/           # Trade-account application
+│               └── _components/     # Gate, header, sign-in wall, pending, guest browse
 ├── components/
 │   ├── cart/                        # CartDrawer
 │   ├── checkout/                    # AddressStep, DeliveryStep, PaymentStep, etc.
 │   ├── layout/                      # Header, Footer, CountrySwitcher
 │   ├── navigation/                  # Breadcrumbs
-│   ├── products/                    # ProductCard, ProductGrid, Filters, MediaGallery, VariantPicker
+│   ├── products/                    # ProductCard, ProductGrid, Filters, MediaGallery, HiddenPricePrompt
 │   └── search/                      # SearchBar
 ├── contexts/
 │   ├── AuthContext.tsx              # Auth state
 │   ├── CartContext.tsx              # Client-side cart state sync
 │   ├── CheckoutContext.tsx          # Checkout flow state
+│   ├── HiddenPricingContext.tsx     # Prices-hidden signal for wholesale guests
 │   └── StoreContext.tsx             # Store/locale/currency state
 ├── hooks/
 │   ├── useCarouselProducts.ts      # Product carousel data
@@ -72,7 +81,11 @@ src/
     │   ├── payment.ts               # Payment processing
     │   ├── products.ts              # Product queries
     │   ├── categories.ts            # Categories
-    │   └── utils.ts                 # Shared helpers (actionResult, withFallback)
+    │   ├── wholesale.ts             # Wholesale channel + catalog + quick-order
+    │   ├── utils.ts                 # Shared helpers (actionResult, withFallback)
+    │   └── …                        # One file per domain — see src/lib/data/
+    ├── spree/                       # Spree integration (client, cookies, auth refresh, middleware, surface)
+    ├── wholesale.ts                 # Approval check + volume-pricing helpers
     └── utils/                       # Client utilities
         ├── address.ts               # Address formatting
         ├── cookies.ts               # Cookie helpers
@@ -81,6 +94,8 @@ src/
         └── product-query.ts         # Product filter query builder
 ```
 
+The `(wholesale)` route group is an opt-in B2B portal, off unless a wholesale channel is configured. Its gating, surfaces, and pricing modes are covered in the [Wholesale Portal](wholesale.md) guide.
+
 ## Authentication Flow
 
 1. User submits login form
@@ -107,17 +122,9 @@ export async function getCustomer() {
 }
 ```
 
-## Multi-Region Support
-
-The storefront supports multiple countries and currencies via URL segments:
-
-```
-/us/en/products          # US store, English
-/de/de/products          # German store, German
-/uk/en/products          # UK store, English
-```
+## Multi-Region
 
-A middleware (`src/proxy.ts`) uses `createSpreeMiddleware` from `src/lib/spree` to detect the visitor's country and locale, then redirects to the correct URL prefix. The `CountrySwitcher` component lets users change regions manually.
+The storefront serves multiple countries, currencies, and languages from one deployment via `/{country}/{locale}` URL segments and an edge middleware that detects and persists the visitor's region. See the [Multi-Region](multi-region.md) guide.
 
 ## Server Actions
 

package/dist/developer/storefront/nextjs/customization.md

@@ -1,35 +1,19 @@
 ---
 title: Customization
-description: Fork, customize, and extend the Spree Next.js Storefront
+description: Customize and extend the Spree Next.js Storefront
 ---
 
-## Forking the Starter
+The storefront is yours to modify — the code ships in your project so you can restyle it, swap components, and change the data layer directly. Scaffold a project with [`create-spree-app`](quickstart.md#installation), then edit the storefront under `apps/storefront/`.
 
-The recommended approach is to fork the repository so you can customize freely while pulling upstream updates.
+## Tracking Upstream Updates
 
-### 1. Fork on GitHub
-
-Go to [github.com/spree/storefront](https://github.com/spree/storefront) and click **Fork**.
-
-### 2. Clone Your Fork
-
-```bash
-git clone https://github.com/YOUR_USERNAME/storefront.git
-cd storefront
-npm install
-```
-
-### 3. Add Upstream Remote
+The storefront evolves upstream. To keep pulling improvements while you customize, own the code in your own Git repository (a fork of [spree/storefront](https://github.com/spree/storefront), or your own repo with the storefront as an upstream remote):
 
 ```bash
+# Point an "upstream" remote at the official storefront
 git remote add upstream https://github.com/spree/storefront.git
-```
-
-### 4. Pull Upstream Updates
 
-When the official starter gets updates, pull them into your fork:
-
-```bash
+# Pull in the latest changes
 git fetch upstream
 git merge upstream/main
 ```
@@ -138,66 +122,8 @@ export default async function YourNewPage() {
 
 ## Transactional Emails
 
-Customer-facing emails are rendered in the storefront using [react-email](https://react.email) and sent via [Resend](https://resend.com). The Spree backend delivers order/shipment/password events to the storefront via [webhooks](../../core-concepts/webhooks.md).
-
-### Templates
-
-Email templates are React components in `src/lib/emails/`:
-
-| File | Event | Description |
-|------|-------|-------------|
-| `order-confirmation.tsx` | `order.completed` | Items, totals, addresses, delivery method |
-| `order-canceled.tsx` | `order.canceled` | Cancellation notice with items |
-| `shipment-shipped.tsx` | `order.shipped` | Tracking number and link |
-| `password-reset.tsx` | `customer.password_reset_requested` | Reset button and fallback link |
-| `newsletter-confirmation.tsx` | `newsletter_subscriber.subscription_requested` | Double opt-in confirmation link |
-
-Customize templates by editing these files directly. They use `@react-email/components` for email-safe layout primitives.
-
-### Previewing
-
-```bash
-npm run email:dev
-```
-
-Opens the react-email dev server with mock data for all templates at `http://localhost:3000`.
-
-### Webhook Handler
-
-The webhook route (`src/app/api/webhooks/spree/route.ts`) uses `createWebhookHandler` from `src/lib/spree/webhooks`:
-
-```typescript
-import { createWebhookHandler } from '@/lib/spree/webhooks'
-
-export const POST = createWebhookHandler({
-  secret: process.env.SPREE_WEBHOOK_SECRET!,
-  handlers: {
-    'order.completed': handleOrderCompleted,
-    'order.canceled': handleOrderCanceled,
-    'order.shipped': handleOrderShipped,
-    'customer.password_reset_requested': handlePasswordReset,
-    'newsletter_subscriber.subscription_requested': handleNewsletterConfirmation,
-  },
-})
-```
-
-To add a new email type:
-
-1. Create a template in `src/lib/emails/`
-2. Add a handler function in `src/lib/webhooks/handlers.ts`
-3. Register the event in `route.ts`
-4. Subscribe to the event in Spree Admin → Webhooks
-
-### Local Development
-
-In dev, emails are written to `.next/emails/` as HTML files — no Resend key needed. Use [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/) to receive webhooks locally:
-
-```bash
-cloudflared tunnel --url http://localhost:3001
-```
-
-For full setup details, see [Sending out Emails](../../deployment/emails.md).
+The storefront can render and send its own order, shipment, and account emails with react-email and Resend, driven by Spree webhooks. See the dedicated [Transactional Emails](emails.md) guide.
 
 ## Building a Custom Storefront
 
-If you prefer to build from scratch instead of forking the starter, you can use the `@spree/sdk` package directly in any Next.js application. The storefront's `src/lib/spree/` directory contains reusable helpers for cookie-based auth, locale resolution, middleware, and webhook verification that you can copy into your own project.
+If you prefer to build from scratch instead of using the starter, you can use the `@spree/sdk` package directly in any Next.js application. The storefront's `src/lib/spree/` directory contains reusable helpers for cookie-based auth, locale resolution, middleware, and webhook verification that you can copy into your own project.

package/dist/developer/storefront/nextjs/deployment.md

@@ -5,26 +5,7 @@ description: Deploy the Spree Next.js Storefront to Vercel, Docker, or any Node.
 
 ## Environment Variables
 
-Set these variables in your hosting platform's dashboard or `.env` file.
-
-### Required
-
-| Variable | Description |
-|----------|-------------|
-| `SPREE_API_URL` | Your Spree API endpoint (e.g., `https://api.mystore.com`) |
-| `SPREE_PUBLISHABLE_KEY` | Publishable API key from your Spree admin |
-
-> **NOTE:** These are server-side only variables — no `NEXT_PUBLIC_` prefix needed since all API calls happen in Server Actions.
-
-### Optional
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `GTM_ID` | Google Tag Manager container ID | _(disabled)_ |
-| `SENTRY_DSN` | Sentry DSN for error tracking | _(disabled)_ |
-| `SENTRY_ORG` | Sentry organization slug | _(none)_ |
-| `SENTRY_PROJECT` | Sentry project slug | _(none)_ |
-| `SENTRY_AUTH_TOKEN` | Sentry auth token (for source maps in CI) | _(none)_ |
+At minimum, set `SPREE_API_URL` and `SPREE_PUBLISHABLE_KEY` in your hosting platform's dashboard or `.env` file. See [Environment Variables](environment-variables.md) for the full reference — analytics, error tracking, wholesale, emails, and SEO.
 
 ## Production Build
 
@@ -43,7 +24,13 @@ Vercel is the recommended deployment platform for Next.js applications.
 
 1. Push your code to GitHub
 2. Go to [vercel.com/new](https://vercel.com/new) and import your repository
-3. Add environment variables (`SPREE_API_URL`, `SPREE_PUBLISHABLE_KEY`)
+3. Add environment variables:
+   - `SPREE_API_URL` and `SPREE_PUBLISHABLE_KEY` (required)
+   - `SPREE_WEBHOOK_SECRET`, `RESEND_API_KEY`, `EMAIL_FROM` — for [transactional emails](emails.md)
+   - `GTM_ID` — optional, Google Tag Manager
+   - `SENTRY_DSN`, `SENTRY_ORG`, `SENTRY_PROJECT`, `SENTRY_AUTH_TOKEN` — optional, error tracking with readable stack traces
+
+   See the [Environment Variables reference](environment-variables.md) for the full list.
 4. Click **Deploy**
 
 Vercel automatically detects the Next.js framework and configures the build settings.
@@ -61,56 +48,50 @@ Every pull request gets a unique preview URL, making it easy to test storefront
 
 ## Docker
 
-Create a `Dockerfile` in your project root:
+A multi-stage `Dockerfile` ships at the repo root. It uses Next.js standalone output to produce a small (~240 MB) image on `node:22-alpine`, runs as a non-root user, and exposes port `3001`.
 
-```dockerfile
-FROM node:20-alpine AS base
+> **NOTE:** `SPREE_API_URL` and `SPREE_PUBLISHABLE_KEY` are required at **build time** — the storefront prerenders pages against the Spree API. Point them at a Spree instance reachable from wherever you run `docker build` (hosted Spree, a tunnel, or `host.docker.internal` for a local backend on Docker Desktop).
 
-FROM base AS deps
-WORKDIR /app
-COPY package.json package-lock.json ./
-RUN npm ci --production=false
-
-FROM base AS builder
-WORKDIR /app
-COPY --from=deps /app/node_modules ./node_modules
-COPY . .
-RUN npm run build
+Build and run:
 
-FROM base AS runner
-WORKDIR /app
-ENV NODE_ENV=production
+```bash
+docker build \
+  --build-arg SPREE_API_URL=https://your-spree.example.com \
+  --build-arg SPREE_PUBLISHABLE_KEY=your_publishable_key \
+  -t spree-storefront .
 
-RUN addgroup --system --gid 1001 nodejs
-RUN adduser --system --uid 1001 nextjs
+docker run -p 3001:3001 --env-file .env.local spree-storefront
+```
 
-COPY --from=builder /app/public ./public
-COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
-COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+### Sentry source maps at build time
 
-USER nextjs
-EXPOSE 3000
-ENV PORT=3000
-ENV HOSTNAME="0.0.0.0"
+`SENTRY_AUTH_TOKEN` is passed via a BuildKit secret so it never lands in image layers or the build cache. The other Sentry vars are regular build args:
 
-CMD ["node", "server.js"]
+```bash
+SENTRY_AUTH_TOKEN=... docker build \
+  --build-arg SPREE_API_URL=... \
+  --build-arg SPREE_PUBLISHABLE_KEY=... \
+  --build-arg SENTRY_DSN=... \
+  --build-arg SENTRY_ORG=... \
+  --build-arg SENTRY_PROJECT=... \
+  --secret id=sentry_auth_token,env=SENTRY_AUTH_TOKEN \
+  -t spree-storefront .
 ```
 
-> **NOTE:** Enable standalone output in your `next.config.ts` for Docker deployments:
-> 
->   ```typescript
-  const nextConfig = {
-    output: 'standalone',
-  }
-  ```
+### Building against a local Spree backend
 
-Build and run:
+On Docker Desktop (macOS/Windows), reach the host's Spree via `host.docker.internal`:
 
 ```bash
-docker build -t spree-storefront .
-docker run -p 3000:3000 \
-  -e SPREE_API_URL=https://api.mystore.com \
-  -e SPREE_PUBLISHABLE_KEY=your_key \
+docker build \
+  --add-host=host.docker.internal:host-gateway \
+  --build-arg SPREE_API_URL=http://host.docker.internal:3000 \
+  --build-arg SPREE_PUBLISHABLE_KEY=your_publishable_key \
+  -t spree-storefront .
+
+docker run -p 3001:3001 \
+  --add-host=host.docker.internal:host-gateway \
+  --env-file .env.local \
   spree-storefront
 ```
 
@@ -131,7 +112,7 @@ npm run build
 npm start
 ```
 
-The server listens on port `3000` by default. Set the `PORT` environment variable to change it.
+The server listens on port `3001`. Set the `PORT` environment variable to change it.
 
 ## CI/CD
 

package/dist/developer/storefront/nextjs/emails.md

@@ -0,0 +1,86 @@
+---
+title: Transactional Emails
+description: Render and send order, shipment, and account emails from the Spree Next.js Storefront with react-email, Resend, and Spree webhooks
+---
+
+The storefront can own its customer-facing transactional emails instead of the Spree backend. Emails are rendered with [react-email](https://react.email) and sent via [Resend](https://resend.com); the Spree backend delivers order, shipment, and account events to the storefront over [webhooks](../../core-concepts/webhooks.md).
+
+```
+Spree Backend → Webhook POST → /api/webhooks/spree → render email → send via Resend
+(signed HMAC)                  (signature verified)  (react-email)  (or write to disk in dev)
+```
+
+## Templates
+
+Email templates are React components in `src/lib/emails/`:
+
+| File | Event | Description |
+|------|-------|-------------|
+| `order-confirmation.tsx` | `order.completed` | Items, totals, addresses, delivery method |
+| `order-canceled.tsx` | `order.canceled` | Cancellation notice with items |
+| `shipment-shipped.tsx` | `order.shipped` | Tracking number and link |
+| `password-reset.tsx` | `customer.password_reset_requested` | Reset button and fallback link |
+
+Customize a template by editing its file directly — they use `@react-email/components` for email-safe layout primitives.
+
+## Previewing
+
+Run the storefront in development and open [http://localhost:3001/dev/emails](http://localhost:3001/dev/emails):
+
+```bash
+npm run dev
+```
+
+Each template renders with sample data via `@react-email/render`. The route is gated to non-production environments.
+
+## Configuration
+
+Add these to `.env.local`:
+
+```env
+SPREE_WEBHOOK_SECRET=your_webhook_endpoint_secret_key
+RESEND_API_KEY=re_your_resend_api_key            # production only
+EMAIL_FROM=Your Store <orders@your-domain.com>   # production only
+```
+
+In development no `RESEND_API_KEY` is needed — emails are written to `.next/emails/` as HTML files with a `file://` link logged to the console.
+
+## Webhook Handler
+
+The webhook route (`src/app/api/webhooks/spree/route.ts`) wires events to handlers with `createWebhookHandler` from `src/lib/spree/webhooks`. Signature verification and event routing are handled for you:
+
+```typescript
+import { createWebhookHandler } from '@/lib/spree/webhooks'
+
+const handler = createWebhookHandler({
+  secret: process.env.SPREE_WEBHOOK_SECRET!,
+  handlers: {
+    'order.completed': handleOrderCompleted,
+    'order.canceled': handleOrderCanceled,
+    'order.shipped': handleOrderShipped,
+    'customer.password_reset_requested': handlePasswordReset,
+  },
+})
+```
+
+To add a new email type:
+
+1. Create a template in `src/lib/emails/`.
+2. Add a handler function in `src/lib/webhooks/handlers.ts`.
+3. Register the event in `route.ts`.
+4. Subscribe to the event in **Spree Admin → Settings → Developers → Webhooks**.
+
+## Setup
+
+1. **Create a webhook endpoint** in Spree Admin → Settings → Developers → Webhooks. Subscribe to `order.completed`, `order.canceled`, `order.shipped`, and `customer.password_reset_requested`, and copy the secret key into `SPREE_WEBHOOK_SECRET`.
+
+2. **Receive webhooks locally.** Expose the storefront with a public URL so Spree can reach it — the simplest option is a [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/):
+
+   ```bash
+   brew install cloudflared
+   cloudflared tunnel --url http://localhost:3001
+   ```
+
+   Use the tunnel URL as the webhook endpoint URL in Spree Admin.
+
+For the backend perspective on delivering these events, see [Sending out Emails](../../deployment/emails.md).

package/dist/developer/storefront/nextjs/environment-variables.md

@@ -0,0 +1,88 @@
+---
+title: Environment Variables
+description: Every environment variable the Spree Next.js Storefront reads, with defaults and when to set it
+---
+
+Configuration lives in `.env.local` (copy `.env.example` to start). Variables **without** a `NEXT_PUBLIC_` prefix are server-side only and never reach the browser; `NEXT_PUBLIC_` variables are inlined into the client bundle at build time, so only put non-secret values there.
+
+## Required
+
+| Variable | Description |
+|----------|-------------|
+| `SPREE_API_URL` | Your Spree API endpoint (e.g. `http://localhost:3000` in dev, `https://api.mystore.com` in production) |
+| `SPREE_PUBLISHABLE_KEY` | Publishable API key from your Spree admin |
+
+> **NOTE:** In a Docker build these two are also required at **build time** — the storefront prerenders pages against the Spree API. See [Deployment](deployment.md).
+
+## Store defaults
+
+Used by the middleware for initial redirects before API data loads, and as build-time fallbacks for sitemap/SEO generation.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `NEXT_PUBLIC_DEFAULT_COUNTRY` | Default country ISO code — should match your store's `default_country_iso` | `us` |
+| `NEXT_PUBLIC_DEFAULT_LOCALE` | Default locale code — should match your store's `default_locale` | `en` |
+| `NEXT_PUBLIC_SITE_URL` | Public site URL, used for sitemap and `robots.txt` generation (e.g. `https://mystore.com`) | _(required for sitemap)_ |
+| `NEXT_PUBLIC_STORE_NAME` | Store name used in metadata fallbacks | `Spree Store` |
+| `NEXT_PUBLIC_STORE_DESCRIPTION` | Store description used in metadata fallbacks | _(sample text)_ |
+
+## SEO & social
+
+Optional overrides for site metadata and the Organization JSON-LD. When unset, values fall back to store settings from the Spree API.
+
+| Variable | Description |
+|----------|-------------|
+| `STORE_SEO_TITLE` | Default `<title>` |
+| `STORE_META_DESCRIPTION` | Default meta description |
+| `STORE_META_KEYWORDS` | Default meta keywords |
+| `STORE_TWITTER` | Twitter/X handle or URL |
+| `STORE_FACEBOOK` | Facebook page URL |
+| `STORE_INSTAGRAM` | Instagram URL |
+| `STORE_LOGO_URL` | Logo URL for Organization JSON-LD |
+| `STORE_SUPPORT_EMAIL` | Customer support email |
+
+## Wholesale B2B portal
+
+The [wholesale portal](wholesale.md) is an opt-in addon, off by default.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SPREE_WHOLESALE_CHANNEL` | Enable switch — the code of a gated Spree channel to bind the `/wholesale` surface to. Unset means DTC-only: every wholesale entry point is hidden and the routes 404 | _(disabled)_ |
+| `SPREE_WHOLESALE_PUBLISHABLE_KEY` | Channel-scoped publishable key for the wholesale surface. Optional — the channel header selects the channel, so this falls back to `SPREE_PUBLISHABLE_KEY` | _(falls back to `SPREE_PUBLISHABLE_KEY`)_ |
+
+## Transactional emails
+
+See the [Transactional Emails](emails.md) guide for the full setup.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SPREE_WEBHOOK_SECRET` | Webhook endpoint secret key that signs incoming Spree webhooks | _(disabled)_ |
+| `RESEND_API_KEY` | [Resend](https://resend.com) API key for sending emails in production | _(dev: writes to disk)_ |
+| `EMAIL_FROM` | "From" address for transactional emails (e.g. `Store <orders@mystore.com>`) | `orders@example.com` |
+
+## Payments
+
+Publishable keys for client-side payment SDKs, read when the matching gateway is enabled. Set the key for whichever provider(s) you use.
+
+| Variable | Description |
+|----------|-------------|
+| `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` | Stripe publishable key (`pk_…`) |
+
+## Analytics
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `GTM_ID` | Google Tag Manager container ID (e.g. `GTM-XXXXXXX`). Leave empty to disable | _(disabled)_ |
+
+## Error tracking (Sentry)
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SENTRY_DSN` | Sentry DSN — set to enable error tracking (e.g. `https://key@o0.ingest.sentry.io/0`) | _(disabled)_ |
+| `SENTRY_ORG` | Sentry organization slug (for source map uploads) | _(none)_ |
+| `SENTRY_PROJECT` | Sentry project slug (for source map uploads) | _(none)_ |
+| `SENTRY_AUTH_TOKEN` | Sentry auth token (for source map uploads in CI) | _(none)_ |
+| `SENTRY_SEND_DEFAULT_PII` | Send PII (IP addresses, cookies, user data) to Sentry server-side | `false` |
+| `NEXT_PUBLIC_SENTRY_SEND_DEFAULT_PII` | Send PII to Sentry client-side | `false` |
+
+> **WARNING:** PII collection is disabled by default. Only set the `SENTRY_SEND_DEFAULT_PII` variables to `true` if you have appropriate user consent or a privacy policy covering this data.

package/dist/developer/storefront/nextjs/multi-region.md

@@ -0,0 +1,75 @@
+---
+title: Multi-Region
+description: How the Spree Next.js Storefront serves multiple countries, currencies, and languages from a single deployment via URL segments and edge middleware
+---
+
+The storefront serves multiple countries, currencies, and languages from a single deployment. Region is encoded in the URL, detected automatically for first-time visitors by middleware, and mapped to a [Spree Market](../../core-concepts/markets.md) — the model that bundles a country, currency, and locale — so every server-side fetch resolves prices and content for the right region.
+
+## URL structure
+
+Every route is prefixed with a country and locale segment:
+
+```
+/us/en/products          # US market, English
+/de/de/products          # German market, German
+/uk/en/products          # UK market, English
+```
+
+The `[country]` and `[locale]` segments are the first two dynamic params of the App Router tree (`src/app/[country]/[locale]/…`). Because region lives in the path, every URL is shareable and independently cacheable, and search engines index each region separately.
+
+## The middleware
+
+A visitor who lands on a bare path (no region prefix) is redirected to the correct `/{country}/{locale}/…` URL by an edge middleware. It's wired in `src/proxy.ts`:
+
+```typescript
+import { createSpreeMiddleware } from '@/lib/spree/middleware'
+import { getDefaultCountry, getDefaultLocale } from '@/lib/store'
+
+export const proxy = createSpreeMiddleware({
+  defaultCountry: getDefaultCountry(),
+  defaultLocale: getDefaultLocale(),
+})
+
+export const config = {
+  matcher: ['/((?!api/|_next/static|_next/image|favicon.ico|.*\\..*$).*)'],
+}
+```
+
+`createSpreeMiddleware` (from `src/lib/spree`) does three things:
+
+- **Redirects** bare paths to `/{country}/{locale}/…`.
+- **Detects** the visitor's country and locale (see below).
+- **Syncs** `spree_country` and `spree_locale` cookies with the URL segments, so server-side fetches via `getLocaleOptions()` resolve the same market the URL asks for.
+
+Requests that already carry a `/{country}/{locale}` prefix pass through untouched — the middleware only refreshes the cookies to match.
+
+### Detection chain
+
+For a request without a region prefix, each value is resolved from the first source that has it:
+
+| Value | Resolution order |
+|-------|------------------|
+| **Country** | `spree_country` cookie → `x-vercel-ip-country` / `cf-ipcountry` geo header → default |
+| **Locale** | `spree_locale` cookie → `Accept-Language` header (primary tag) → default |
+
+Geo headers are set by the hosting edge — `x-vercel-ip-country` on Vercel, `cf-ipcountry` behind Cloudflare. On a host that provides neither, detection falls back to `Accept-Language` for locale and the configured default for country. A returning visitor's cookie always wins, so a manual region change sticks.
+
+### Configuration
+
+`createSpreeMiddleware` accepts:
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `defaultCountry` | Fallback country ISO when nothing else matches | `us` |
+| `defaultLocale` | Fallback locale when nothing else matches | `en` |
+| `staticRoutes` | Path prefixes to skip | `['/_next', '/api', '/dev', '/favicon.ico']` |
+
+In the storefront these defaults come from `NEXT_PUBLIC_DEFAULT_COUNTRY` and `NEXT_PUBLIC_DEFAULT_LOCALE` (see [Environment Variables](environment-variables.md)). The `matcher` in `proxy.ts` additionally excludes API routes, Next.js internals, and any path with a file extension, so the middleware only runs on page navigations.
+
+## Switching regions
+
+The `CountrySwitcher` component (in `src/components/layout/`) lets a visitor change region manually. Selecting a new region navigates to the matching URL prefix; the middleware then updates the `spree_country` / `spree_locale` cookies so the choice persists across future visits.
+
+## How region reaches the data layer
+
+Region-aware reads don't take a country/locale argument — they call `getLocaleOptions()` from `src/lib/spree`, which reads the `spree_country` / `spree_locale` cookies the middleware keeps in sync with the URL. That value is passed to `@spree/sdk`, which sends it to the Store API so prices, currency, and translated content come back for the right [market](../../core-concepts/markets.md). See [Architecture](architecture.md) for the wider server-first data flow.

package/dist/developer/storefront/nextjs/quickstart.md

@@ -34,19 +34,19 @@ The [Spree Storefront](https://github.com/spree/storefront) is a production-read
 
 ## Installation
 
-### Option 1: Fork the Repository (Recommended)
+### Recommended: create-spree-app
 
-Fork the repository on GitHub, then clone your fork:
+The fastest way to get a full project — Spree backend, this Next.js storefront, and the `spree` CLI, wired together — is [`create-spree-app`](../../create-spree-app/quickstart.md):
 
 ```bash
-git clone https://github.com/YOUR_USERNAME/storefront.git
-cd storefront
-npm install
+npx create-spree-app my-store
 ```
 
-This gives you a full copy you can customize freely while still being able to pull upstream updates.
+The storefront is included by default (pass `--no-storefront` to skip it). It's scaffolded into `apps/storefront/` with its `.env.local` already pointing at the backend, so it boots against real data with no manual key wiring.
+
+### Standalone
 
-### Option 2: Clone Directly
+To run the storefront on its own — against an existing Spree backend, or to work on the storefront repo directly — clone it and install:
 
 ```bash
 git clone https://github.com/spree/storefront.git
@@ -54,6 +54,8 @@ cd storefront
 npm install
 ```
 
+Then follow [Configuration](#configuration) to point it at your Spree API. If you plan to customize and track upstream changes, [fork first](customization.md#tracking-upstream-updates).
+
 ## Configuration
 
 Copy the environment file:
@@ -81,6 +83,8 @@ npm run dev
 
 Open [http://localhost:3001](http://localhost:3001) in your browser.
 
+> **NOTE:** Testing Apple Pay / Google Pay locally needs a public HTTPS URL. See [Wallet Payments in Development](wallet-payments.md).
+
 ## Production Build
 
 ```bash

package/dist/developer/storefront/nextjs/testing.md

@@ -0,0 +1,81 @@
+---
+title: Testing
+description: Run the Spree Next.js Storefront's unit tests with Vitest and its end-to-end suite with Playwright against a real Spree backend
+---
+
+The storefront ships two test layers: fast unit/integration tests with Vitest, and a browser end-to-end suite with Playwright that runs against a real Spree backend booted in Docker.
+
+## Unit & integration (Vitest)
+
+```bash
+npm test            # one-shot
+npm run test:watch  # watch mode
+```
+
+## End-to-end (Playwright)
+
+The E2E suite drives a browser against a real Spree backend. `npm run e2e:up` boots the backend — Postgres, Redis, and the official `ghcr.io/spree/spree:latest` image from `e2e-backend/docker-compose.yml` — then seeds it and mints an API key through the official [`@spree/cli`](../../cli/quickstart.md) (`spree seed`, `spree sample-data`, `spree api-key create`), installed as a dev dependency. No `create-spree-app` setup is required.
+
+```bash
+# 1. Export a Stripe test-mode key pair from your own Stripe sandbox.
+#    Both keys must belong to the same account — Stripe no longer
+#    publishes a working sample secret key, and a mismatched pair makes
+#    the checkout payment step fail.
+export STRIPE_PUBLISHABLE_KEY=pk_test_…
+export STRIPE_SECRET_KEY=sk_test_…
+
+# 2. Boot Spree + Postgres + Redis, seed sample data, register a Stripe
+#    payment gateway, mint a publishable key, and write .env.e2e.
+npm run e2e:up
+
+# 3. Run the suite. Playwright boots `next dev` against .env.e2e.
+npm run test:e2e
+
+# Optional: interactive UI mode.
+npm run test:e2e:ui
+
+# Tear everything down.
+npm run e2e:down
+```
+
+The checkout test pays with card `4242 4242 4242 4242` through Stripe's [test mode](https://docs.stripe.com/keys). PaymentIntents land in whichever Stripe test account owns the keys you exported.
+
+### CI
+
+In CI, set `STRIPE_SECRET_KEY` as a repository secret and `STRIPE_PUBLISHABLE_KEY` as a repository variable (**Settings → Secrets and variables → Actions**). The E2E job skips itself on fork PRs, where GitHub never exposes repository secrets.
+
+## Testing against a customized backend
+
+> **NOTE:** By default the E2E suite runs against the stock official Spree image (`ghcr.io/spree/spree:latest`), so it verifies the storefront against a **vanilla Spree** — not a backend with your own extensions, serializers, or seed data.
+
+The E2E stack reads a `SPREE_IMAGE` env var and falls back to the stock image when it's unset. Set it to any image that exposes the Store API on the container's port `3000`, and the suite runs against that backend instead.
+
+### Your own Spree image
+
+If you already publish a customized Spree image:
+
+```bash
+SPREE_IMAGE=ghcr.io/your-org/your-spree:latest npm run e2e:up
+npm run test:e2e
+```
+
+### A `create-spree-app` project's backend
+
+A project scaffolded with [`create-spree-app`](../../create-spree-app/quickstart.md) has its customizable Spree in `backend/` (built from `backend/Dockerfile`) and this storefront in `apps/storefront/`. Build that backend into a local image and point the suite at it — this is what tests the storefront against the **exact Spree you deploy**, extensions and all:
+
+```bash
+# From the project root — build the customized backend image
+docker build -t project-spree:e2e ./backend
+
+# From apps/storefront — run E2E against it
+cd apps/storefront
+SPREE_IMAGE=project-spree:e2e npm run e2e:up
+npm run test:e2e
+npm run e2e:down
+```
+
+> **NOTE:** New `create-spree-app` projects wire this into the generated storefront CI workflow automatically — the workflow builds `backend/Dockerfile` and runs the storefront E2E against that image rather than stock Spree.
+
+### Interactive / manual
+
+To click through the storefront against a running backend (no E2E harness), point it there directly: set `SPREE_API_URL` and `SPREE_PUBLISHABLE_KEY` in `.env.local` (see [Environment Variables](environment-variables.md)) and run `npm run dev`.

package/dist/developer/storefront/nextjs/wallet-payments.md

@@ -0,0 +1,52 @@
+---
+title: Wallet Payments in Development
+description: Test Apple Pay and Google Pay against a local Spree Next.js Storefront using a public HTTPS URL
+---
+
+Apple Pay and Google Pay require HTTPS **and a publicly-reachable URL** — Stripe verifies the payment method domain from the internet, so `localhost` and locally-trusted certificates (e.g. `mkcert` + `lvh.me`) won't pass domain verification. The simplest way to expose your local storefront with a valid public HTTPS URL is [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/).
+
+## Setup
+
+1. Install `cloudflared`:
+
+   ```bash
+   brew install cloudflared
+   ```
+
+2. Start the dev server normally (HTTP on port 3001):
+
+   ```bash
+   npm run dev
+   ```
+
+3. In a second terminal, expose it through a quick tunnel:
+
+   ```bash
+   cloudflared tunnel --url http://localhost:3001
+   ```
+
+   The output will contain a URL like `https://<random-words>.trycloudflare.com`.
+
+4. Register that URL in your [Stripe Payment method domains](https://dashboard.stripe.com/settings/payment_methods/domains).
+
+5. Open the tunnel URL in your browser and test the Express Checkout buttons in the cart.
+
+## Stable tunnel URLs
+
+`next.config.ts` already allows `*.trycloudflare.com` via `allowedDevOrigins`, so quick tunnels work out of the box. Every time you restart `cloudflared tunnel --url ...` you get a new random subdomain — if you need a stable URL (to avoid re-registering in Stripe on each run), set up a [named tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/#using-named-tunnels) on your own domain.
+
+## The Spree backend must also be publicly reachable
+
+The storefront's server-side fetches go to `SPREE_API_URL`, but image URLs and a few other backend-served paths (e.g. the Apple Pay domain-verification file under `/.well-known/apple-developer-merchantid-domain-association`) are fetched by the browser directly and must resolve from the public internet.
+
+Point `SPREE_API_URL` at a hosted Spree (e.g. `*.spree.sh`, `*.vendo.dev`, your own staging) or expose your local Spree with another tunnel:
+
+```bash
+cloudflared tunnel --url http://localhost:3000
+```
+
+When tunneling a local Rails app, allow the tunnel host in the backend's `.env`:
+
+```env
+RAILS_DEVELOPMENT_HOSTS=.trycloudflare.com
+```

package/dist/developer/storefront/nextjs/wholesale.md

@@ -0,0 +1,82 @@
+---
+title: Wholesale Portal
+description: The opt-in B2B wholesale surface and how channel-backed surfaces work
+---
+
+## What the Wholesale Portal Is
+
+The storefront ships an optional **wholesale portal** at `/wholesale` — a gated B2B surface for approved trade buyers. It runs on a separate Spree sales channel but shares the same storefront app and Spree backend as the public direct-to-consumer (DTC) store, so a single deployment serves both audiences: the open catalog for shoppers and a login-gated trade catalog with volume pricing for wholesale buyers.
+
+The portal is an **opt-in addon**. It is off by default; a DTC-only storefront never renders any wholesale UI.
+
+> **NOTE:** The wholesale portal is a **reference implementation**, not a fixed feature. It demonstrates one shape — a gated B2B surface running *alongside* an open DTC store — but the same building blocks (channels, [surfaces](#surfaces-and-channel-switching), and [access gating](#gating-modes)) support the whole spectrum. You can invert the default and make the storefront closed or limited: gate the *primary* DTC channel with `login_required` or `prices_hidden` for a members-only or invite-only shop, drop the public catalog entirely and ship a login-first B2B storefront, or run several gated channels with no open surface at all. Treat this page as a worked example to adapt, not a prescription — the storefront is yours to reshape.
+
+## Surfaces and Channel Switching
+
+A **surface** is a distinct sales context backed by its own Spree [channel](../../core-concepts/channels.md). The storefront models two out of the box — `dtc` (the public storefront) and `wholesale` (the trade portal) — but the mechanism is general: any channel on your backend can back its own surface.
+
+The surface selects which SDK client a request goes through. A channel-bound client sends the channel code on every request via the `X-Spree-Channel` header, and the Store API [resolves the request against that channel](../../core-concepts/channels.md#resolution-at-request-time) — its catalog, pricing, and access rules. In the SDK this is the `channel` client option:
+
+```ts
+import { createClient } from '@spree/sdk'
+
+const wholesaleClient = createClient({
+  baseUrl: process.env.SPREE_API_URL,
+  publishableKey: process.env.SPREE_PUBLISHABLE_KEY,
+  channel: 'wholesale', // sent as X-Spree-Channel on every request
+})
+```
+
+Alternatively, a **channel-bound publishable key** carries the channel server-side: when a key is scoped to a channel on the backend, the API assigns that channel to the request without needing the header. Either path works; the header is the simplest and is what the storefront uses by default.
+
+Because each surface has its own client, cart cookies, and cache keys, a customer can hold an open DTC cart and an open wholesale cart at the same time without them mixing. The customer session (JWT) is shared — it's the same person signing in — so only the cart splits, never the auth.
+
+To add your own channel-backed surface, follow the same pattern: create the channel on the backend, add a client bound to its code, and thread the surface through the routes that should target it.
+
+## Enabling Wholesale
+
+Wholesale turns on through a single environment variable:
+
+- **`SPREE_WHOLESALE_CHANNEL`** — the enable switch. Set it to the code of a gated channel on your backend (e.g. `wholesale`). There is **no default**: when it is unset, the storefront runs DTC-only — the wholesale nav link, footer link, and homepage section are hidden, and every `/wholesale` route returns 404.
+- **`SPREE_WHOLESALE_PUBLISHABLE_KEY`** — optional. The channel header alone selects the channel, so this falls back to `SPREE_PUBLISHABLE_KEY`. Set it only to bind a channel-scoped publishable key.
+
+The backend must have a [channel](../../core-concepts/channels.md) whose code matches `SPREE_WHOLESALE_CHANNEL`. Its [`storefront_access`](../../core-concepts/channels.md#storefront-access-gating) posture decides how much a guest can see — the portal supports both `login_required` (guests are walled off entirely) and `prices_hidden` (guests browse the catalog but not prices). See [Gating Modes](#gating-modes) below. Spree installs seed a `login_required` wholesale channel by default; switching to `prices_hidden` is a single flag on that same channel — no new channel or seed data.
+
+## How Gating Works End to End
+
+Two independent checks gate the portal — one at the **channel** (how much of the catalog a guest may see), one at the **customer** (whether a buyer may transact at trade pricing). The channel check is set by the channel's [gating mode](#gating-modes); the customer check is always the same.
+
+**Channel access** is enforced by the Store API, not the storefront — the storefront can't loosen it. Depending on the channel's `storefront_access` posture, a guest is either rejected outright (`login_required`) or served the catalog with money fields returned as `null` (`prices_hidden`). This is a general channel feature; see [Channels → Storefront Access Gating](../../core-concepts/channels.md#storefront-access-gating) for how it's resolved and enforced.
+
+**Buyer approval.** Being logged in isn't enough; a buyer must be *approved*. Approval is membership in the **Wholesale** [customer group](../../core-concepts/pricing.md#customer-group-rule) — an admin adds an applicant to the group to approve them. The storefront reads `customer_groups` on `customers/me` and branches accordingly:
+
+- **Guest** — sees the sign-in / apply wall (`login_required`), or the read-only catalog with sign-in-for-pricing prompts (`prices_hidden`).
+- **Signed in, not in the group** — sees an application-pending state. Signing in never skips approval: an authenticated but unapproved buyer cannot transact under either mode.
+- **Signed in and in the group** — gets the full portal: trade catalog, quick order, and the wholesale cart.
+
+**Trade pricing** is unlocked by volume. The seeded model grants a trade price once a line reaches a minimum quantity of the same item (10 or more per item in the sample data). The applicable volume rule lives on a backend [Price List](../../core-concepts/pricing.md#price-lists); the storefront surfaces the trade price the API returns for a qualifying quantity.
+
+## Gating Modes
+
+A channel's `storefront_access` posture is one of three values. The wholesale portal supports the two gated modes; the third describes a fully public channel like DTC.
+
+| Mode | Guest sees catalog | Guest sees prices | Guest can order |
+|---|---|---|---|
+| `login_required` | No — hard `401`, sign-in wall | No | No |
+| `prices_hidden` | Yes — read-only | No — "sign in for pricing" | No — "sign in to order" |
+| `public` | Yes | Yes | Yes (subject to guest checkout) |
+
+**`login_required`** is the strictest posture and the seeded default. The Store API rejects any unauthenticated request to the channel with `401`, so a guest can't read wholesale catalog or pricing at all. The storefront shows the sign-in / apply wall in place of every gated page.
+
+**`prices_hidden`** opens the catalog to guests while keeping pricing private. The channel doesn't reject unauthenticated requests, but the API serializes every money field as `null` for a guest. In the portal, a guest browses the catalog and product pages read-only: each price renders a **"sign in for pricing"** prompt, and add-to-cart becomes **"sign in to order."** Ordering surfaces (cart, quick order) still require sign-in — a guest is redirected to the sign-in flow rather than shown an empty wholesale cart. Approval is unchanged: signing in reveals list prices, and joining the Wholesale group unlocks trade pricing. This mode suits a trade catalog you want discoverable (for SEO or lead generation) without exposing negotiated pricing.
+
+**`public`** is an ungated channel — the posture the DTC store runs on. It's listed here for completeness; a wholesale channel would not normally use it.
+
+Switching a wholesale channel between the two supported modes is a single change to [`storefront_access`](../../core-concepts/channels.md#storefront-access-gating) on the backend — set on the channel, or inherited from the [store's default](../../core-concepts/stores.md#storefront-access-defaults). Nothing in the storefront needs redeploying — the portal reads the channel's posture at request time and adapts. Login and signup always run through the same approval flow regardless of mode.
+
+## Related Documentation
+
+- [Channels](../../core-concepts/channels.md) — The sales channel that backs the wholesale surface, and the general [Storefront Access Gating](../../core-concepts/channels.md#storefront-access-gating) mechanism the portal builds on
+- [Stores](../../core-concepts/stores.md) — Store-level [defaults](../../core-concepts/stores.md#storefront-access-defaults) that channels inherit
+- [Pricing](../../core-concepts/pricing.md) — [Price Lists](../../core-concepts/pricing.md#price-lists) and the [Customer Group Rule](../../core-concepts/pricing.md#customer-group-rule) behind approval and trade pricing
+- [Store SDK: Configuration](../../sdk/configuration.md) — `setChannel` and the channel client option used to bind a surface

package/dist/developer/upgrades/5.5-to-5.6.md

@@ -0,0 +1,177 @@
+---
+title: Upgrading to Spree 5.6
+description: Step-by-step guide to upgrading a Spree 5.5 application to Spree 5.6, including gem updates, migrations, data backfills, and breaking changes to review.
+---
+
+> **INFO:** Before proceeding to upgrade, please ensure you're at [Spree 5.5](5.4-to-5.5.md).
+
+The upgrade is usually completed in four steps:
+
+1. **Update the Ruby gems** which power Spree API
+2. **Run database migrations** — to migrate your existing schema to the new version
+3. **Run data backfills** — to move your existing data into the new schema and power new features
+4. Apply optional configuration and review behavior changes — to take advantage of new features and avoid surprises
+
+## How to upgrade
+
+For applications created via `create-spree-app` command we greatly recommend using the Spree CLI to perform the upgrade. It provides a guided experience with prompts and handles the first three steps for you. If you prefer to run the commands manually or not using docker for local development, you can follow the "Without Spree CLI" path.
+
+
+```bash Spree CLI (Docker)
+spree upgrade
+```
+
+```bash Without Spree CLI
+# cd backend if you're in the monorepo root
+bundle update
+bundle exec rake spree:install:migrations && bin/rails db:migrate
+bundle exec rake spree:upgrade
+```
+
+
+The **Spree CLI** path runs all three commands for you with prompts. Recommended for local development. If you don't have the CLI yet, either install it globally or run it through `npx`:
+
+```bash
+# install once and use `spree …` everywhere
+npm install -g @spree/cli
+
+# or invoke without installing (each command runs through npx)
+npx @spree/cli upgrade
+```
+
+The **Without Spree CLI** path is the bare equivalent. Use this on production: `bundle update` and `db:migrate` are part of your existing deploy pipeline (Heroku release phase, K8s init container, Capistrano hook, Render auto-migrate). Once the 5.6 release is up, run `bundle exec rake spree:upgrade` from a one-off dyno / job container / `kubectl exec` to perform the data backfills.
+
+Skipping versions and re-running are both safe — `bundle exec rake spree:upgrade` figures out what still needs to happen and does nothing on data that's already migrated.
+
+## What the upgrade does
+
+This is reference material — what `bundle exec rake spree:upgrade` (and equivalently `spree upgrade`) actually executes on your data. Skip if you trust the tool; read on if something failed or you're curious. Every step is idempotent, so re-running the full manifest is safe.
+
+### Backfill store ownership on role assignments
+
+Spree 5.6 resolves admin roles per store. The migrations add `store_id` to `spree_role_users`, but existing assignments have a NULL value until backfilled:
+
+
+```bash Spree CLI (Docker)
+spree rake spree:role_users:backfill_store_ids
+```
+
+```bash Without Spree CLI
+bundle exec rake spree:role_users:backfill_store_ids
+```
+
+
+Sets `spree_role_users.store_id` from the store resource so `Spree::Ability` resolves roles by store. Store-scoped assignments only — extensions (e.g. `spree_multi_vendor`) backfill their own resource types. Until this runs, store admins stay authorized via the `spree_admin?` fallback.
+
+### Backfill store ownership on promotions and payment methods
+
+Spree 5.6 moves `Spree::Promotion` and `Spree::PaymentMethod` from multi-store sharing to single-owner `belongs_to :store`. The migrations add a `store_id` column to each; this task populates it:
+
+
+```bash Spree CLI (Docker)
+spree rake spree:upgrade:populate_single_store_associations
+```
+
+```bash Without Spree CLI
+bundle exec rake spree:upgrade:populate_single_store_associations
+```
+
+
+Sets `store_id` on `Spree::Promotion` and `Spree::PaymentMethod` from the legacy `spree_promotions_stores` / `spree_payment_methods_stores` join tables.
+
+> **WARNING:** Until this runs, migrated rows have a NULL `store_id` and are hidden from store-scoped lookups — a payment method with no `store_id` is unavailable at checkout. Run it right after `db:migrate`.
+
+Records shared across several stores keep **one** owner (promotions: the earliest `spree_promotions_stores` row by `created_at`, then lowest `store_id`; payment methods: the lowest `store_id`, since that join has no timestamps) unless [`spree_multi_store`](#multi-store-deployments) is installed. Each shared record is logged so the loss is visible.
+
+### Backfill store ownership on taxons
+
+Categories carry a direct `store_id` in 5.6. The task sets it from each taxon's taxonomy, then resolves taxonomy-less rows through their parent chain:
+
+
+```bash Spree CLI (Docker)
+spree rake spree:taxons:backfill_store_id
+```
+
+```bash Without Spree CLI
+bundle exec rake spree:taxons:backfill_store_id
+```
+
+
+Until this runs, existing taxons keep resolving their store via the taxonomy join (`Taxon.for_store` fallback); taxonomy-less categories (`Spree::Category`) rely on the direct `store_id`, so the backfill is required for them.
+
+### Recompute taxon product counts
+
+
+```bash Spree CLI (Docker)
+spree rake spree:taxons:backfill_products_count
+```
+
+```bash Without Spree CLI
+bundle exec rake spree:taxons:backfill_products_count
+```
+
+
+Recomputes the descendant-inclusive `products_count` counter cache on every taxon, in batches.
+
+### Backfill the store tenant on product tags
+
+Spree 5.6 bounds product tag autocomplete to the owning store. Product taggings now carry a store `tenant` (like order taggings already did); this task sets it on tags created before the upgrade:
+
+
+```bash Spree CLI (Docker)
+spree rake spree:upgrade:backfill_product_tag_tenants
+```
+
+```bash Without Spree CLI
+bundle exec rake spree:upgrade:backfill_product_tag_tenants
+```
+
+
+Sets the `tenant` column on existing `Spree::Product` taggings from each product's `store_id`. New product taggings tenant themselves automatically — only rows created before the upgrade need this. Until it runs, product tags created before the upgrade are hidden from the store's tag-autocomplete vocabulary (they reappear once it completes; storefront and admin tag *display* are unaffected).
+
+## Update the Spree SDK
+
+Spree 5.6 ships alongside `@spree/sdk` 1.2. The backend upgrade never touches your frontend source — bump the SDK in every JavaScript consumer of the Store API and take it through your normal PR/CI cycle:
+
+```bash
+# create-spree-app projects: the Next.js storefront
+cd apps/storefront
+npm install @spree/sdk@^1.2
+```
+
+If you maintain a separate storefront repo or other integrations, repeat there.
+
+| Spree backend | `@spree/sdk` |
+|---|---|
+| 5.4 | 1.0.x |
+| 5.5 | 1.1+ |
+| 5.6 | 1.2+ |
+
+## Behavior changes to review
+
+These don't require any rake task — but storefronts, integrations, and merchant-facing dashboards may need code changes to handle them correctly.
+
+### Promotions and payment methods belong to a single store
+
+`Spree::Promotion` and `Spree::PaymentMethod` are now single-owner (`belongs_to :store`). Create them through the store association so the owner is set:
+
+```ruby
+store.payment_methods.create!(...)
+store.promotions.create!(...)
+```
+
+A record built off the association but not yet saved is invisible to `available_for_store?` until persisted. The `store_ids=` writer that used to fan a record across stores is removed; multi-store sharing moves to the [`spree_multi_store`](#multi-store-deployments) extension. The `spree_promotions_stores` / `spree_payment_methods_stores` join tables are kept as legacy compat surface and dropped in a later release.
+
+### Admin roles resolve per store
+
+With `store_id` on role assignments, an admin's abilities are scoped to the store they're assigned to. Until [the role backfill](#backfill-store-ownership-on-role-assignments) runs, existing store admins remain authorized through the `spree_admin?` fallback, so there is no lockout — but run it so role resolution is correct going forward.
+
+### Product tag autocomplete is store-scoped
+
+The Admin API tag-autocomplete endpoint (`GET /api/v3/admin/tags`) now returns only tags used within the current store for store-owned taggables (products and orders). Customer tags remain global. If an integration relied on this endpoint returning tags across every store, that cross-store vocabulary is no longer exposed. Run [the tag-tenant backfill](#backfill-the-store-tenant-on-product-tags) so pre-upgrade product tags are included.
+
+## Multi-store deployments
+
+Sharing a single promotion, payment method, or product across multiple stores is no longer part of Spree core — 5.6 assigns each of these to one owning store. If you run several stores from one installation and need shared records, install the `spree_multi_store` extension **before** running the backfills; without it, the backfills assign each shared record to a single owner store and the others lose it (every such case is logged).
+
+For single-store deployments this is invisible — the backfills assign every record to your one store, and you can move on.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/docs",
-  "version": "0.1.132",
+  "version": "0.1.134",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",