@vitrine-kit/vitrine 0.4.3 → 0.5.0

package/kit/registry/cart/files/app/api/cart/route.ts

@@ -51,23 +51,53 @@ function parseRemoveItemBody(body: unknown): { lineId: string } | null {
   return { lineId };
 }
 
+function publicError(error: unknown): string {
+  if (!(error instanceof Error)) return 'cart update failed';
+  return error.message.replace(/^\[vitrine\]\s*/, '');
+}
+
 async function ensureCartId(commerce: CommerceBackend): Promise<string> {
   const jar = await cookies();
   const existing = jar.get(COOKIE)?.value;
   if (existing) return existing;
   const cart = await commerce.createCart();
-  jar.set(COOKIE, cart.id, { httpOnly: true, sameSite: 'lax', path: '/' });
+  jar.set(COOKIE, cart.id, {
+    httpOnly: true,
+    sameSite: 'lax',
+    path: '/',
+    secure: process.env.NODE_ENV === 'production',
+  });
   return cart.id;
 }
 
+export async function GET() {
+  const id = (await cookies()).get(COOKIE)?.value;
+  if (!id) {
+    return NextResponse.json({ id: null, lines: [], currency: 'USD', subtotal: 0, total: 0 });
+  }
+  try {
+    const commerce = await getCommerceBackend();
+    const cart = await commerce.getCart(id);
+    return NextResponse.json(cart ?? { id, lines: [], currency: 'USD', subtotal: 0, total: 0 });
+  } catch (error) {
+    return NextResponse.json({ error: publicError(error) }, { status: 500 });
+  }
+}
+
 export async function POST(req: Request) {
   const limited = rateLimited(req);
   if (limited) return limited;
   const parsed = parseAddItemBody(await req.json());
   if (!parsed) return NextResponse.json({ error: 'invalid body' }, { status: 400 });
-  const commerce = await getCommerceBackend();
-  const id = await ensureCartId(commerce);
-  return NextResponse.json(await commerce.addItem(id, parsed.variantId, parsed.quantity));
+  try {
+    const commerce = await getCommerceBackend();
+    const id = await ensureCartId(commerce);
+    return NextResponse.json(await commerce.addItem(id, parsed.variantId, parsed.quantity));
+  } catch (error) {
+    const message = publicError(error);
+    const status = /out of stock|not found/i.test(message) ? 409 : 500;
+    return NextResponse.json({ error: message }, { status });
+  }
 }
 
 export async function PATCH(req: Request) {
@@ -77,8 +107,12 @@ export async function PATCH(req: Request) {
   if (!parsed) return NextResponse.json({ error: 'invalid body' }, { status: 400 });
   const id = (await cookies()).get(COOKIE)?.value;
   if (!id) return NextResponse.json({ error: 'cart not found' }, { status: 400 });
-  const commerce = await getCommerceBackend();
-  return NextResponse.json(await commerce.updateItem(id, parsed.lineId, parsed.quantity));
+  try {
+    const commerce = await getCommerceBackend();
+    return NextResponse.json(await commerce.updateItem(id, parsed.lineId, parsed.quantity));
+  } catch (error) {
+    return NextResponse.json({ error: publicError(error) }, { status: 500 });
+  }
 }
 
 export async function DELETE(req: Request) {
@@ -88,6 +122,10 @@ export async function DELETE(req: Request) {
   if (!parsed) return NextResponse.json({ error: 'invalid body' }, { status: 400 });
   const id = (await cookies()).get(COOKIE)?.value;
   if (!id) return NextResponse.json({ error: 'cart not found' }, { status: 400 });
-  const commerce = await getCommerceBackend();
-  return NextResponse.json(await commerce.removeItem(id, parsed.lineId));
+  try {
+    const commerce = await getCommerceBackend();
+    return NextResponse.json(await commerce.removeItem(id, parsed.lineId));
+  } catch (error) {
+    return NextResponse.json({ error: publicError(error) }, { status: 500 });
+  }
 }

package/kit/registry/cart/files/components/cart/AddToCart.tsx

@@ -4,11 +4,15 @@
 'use client';
 import { useMemo, useState } from 'react';
 import type { Product, Variant } from '@vitrine-kit/contracts';
+import { formatMoney } from '../../lib/cart/data.js';
+import { useChromeLabel } from '@/lib/i18n/useChromeLabel';
 
 export interface AddToCartProps {
   product: Product;
 }
 
+const SIZE_ORDER = ['XXS', 'XS', 'S', 'M', 'L', 'XL', 'XXL', 'XXXL'];
+
 function optionKeys(variants: Variant[]): string[] {
   const keys = new Set<string>();
   for (const v of variants) {
@@ -23,7 +27,18 @@ function valuesFor(variants: Variant[], key: string): string[] {
     const value = v.options?.[key];
     if (value) values.add(value);
   }
-  return [...values];
+  const list = [...values];
+  if (key.toLowerCase() === 'size') {
+    return list.sort((a, b) => {
+      const ia = SIZE_ORDER.indexOf(a.toUpperCase());
+      const ib = SIZE_ORDER.indexOf(b.toUpperCase());
+      if (ia >= 0 && ib >= 0) return ia - ib;
+      if (ia >= 0) return -1;
+      if (ib >= 0) return 1;
+      return a.localeCompare(b);
+    });
+  }
+  return list.sort((a, b) => a.localeCompare(b));
 }
 
 function matchVariant(
@@ -52,6 +67,8 @@ export function AddToCart({ product }: AddToCartProps) {
   const variants = product.variants;
   const keys = useMemo(() => optionKeys(variants), [variants]);
   const [pending, setPending] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const addLabel = useChromeLabel('addToCart');
   const [selected, setSelected] = useState<Record<string, string>>(() => ({
     ...(firstAvailable(variants)?.options ?? {}),
   }));
@@ -62,17 +79,26 @@ export function AddToCart({ product }: AddToCartProps) {
   const active = matched ?? firstAvailable(variants);
   const activeId = active?.id;
   const outOfStock = active != null && active.stock != null && active.stock <= 0;
+  const currency = active?.currency ?? product.priceRange?.currency ?? 'USD';
 
   async function add(): Promise<void> {
     if (!activeId || outOfStock) return;
     setPending(true);
+    setError(null);
     try {
-      await fetch('/api/cart', {
+      const res = await fetch('/api/cart', {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify({ variantId: activeId, quantity: 1 }),
       });
+      if (!res.ok) {
+        const data = (await res.json().catch(() => ({}))) as { error?: string };
+        setError(data.error ?? 'Could not add to cart.');
+        return;
+      }
       location.assign('/cart');
+    } catch {
+      setError('Could not add to cart.');
     } finally {
       setPending(false);
     }
@@ -119,14 +145,23 @@ export function AddToCart({ product }: AddToCartProps) {
         </label>
       ) : null}
 
+      {active?.price != null ? (
+        <p className="text-price text-lg">{formatMoney(active.price, currency)}</p>
+      ) : null}
+
       <button
         type="button"
         onClick={add}
         disabled={pending || !activeId || outOfStock}
         className="vt-add-to-cart rounded-md bg-primary px-gutter py-unit text-primary-fg transition hover:opacity-90 disabled:opacity-50 focus-visible:outline-none focus-visible:ring-2 ring-ring"
       >
-        {pending ? 'Adding…' : outOfStock ? 'Out of stock' : 'Add to cart'}
+        {pending ? 'Adding…' : outOfStock ? 'Out of stock' : addLabel}
       </button>
+      {error ? (
+        <p role="alert" className="vt-add-to-cart-error text-danger">
+          {error}
+        </p>
+      ) : null}
     </div>
   );
 }

package/kit/registry/cart/files/components/cart/CartIndicator.tsx

@@ -1,11 +1,36 @@
-// Header cart link (global.header-actions slot). Presentational.
+// Header cart link (global.header-actions slot). Client component loads the
+// item count from GET /api/cart so the kit typecheck stays free of Next imports.
+'use client';
+import { useEffect, useState } from 'react';
+import { useChromeLabel } from '@/lib/i18n/useChromeLabel';
+
 export function CartIndicator() {
+  const [count, setCount] = useState(0);
+  const label = useChromeLabel('cart');
+
+  useEffect(() => {
+    let cancelled = false;
+    fetch('/api/cart')
+      .then((res) => (res.ok ? res.json() : null))
+      .then((data: { lines?: Array<{ quantity?: number }> } | null) => {
+        if (cancelled || !data?.lines) return;
+        setCount(data.lines.reduce((sum, line) => sum + (line.quantity ?? 0), 0));
+      })
+      .catch(() => {
+        /* cart API missing on catalog-only installs */
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
   return (
     <a
       href="/cart"
       className="vt-cart-indicator text-fg transition hover:text-primary focus-visible:outline-none focus-visible:ring-2 ring-ring"
     >
-      Cart
+      {label}
+      {count > 0 ? ` (${count})` : ''}
     </a>
   );
 }

package/kit/registry/cart/files/components/cart/CartLineItem.tsx

@@ -1,4 +1,6 @@
-// Cart line item — presentational.
+// Cart line item — client controls for quantity and remove (PATCH/DELETE /api/cart).
+'use client';
+import { useState } from 'react';
 import type { CartLine } from '@vitrine-kit/contracts';
 import { formatMoney } from '../../lib/cart/data.js';
 
@@ -8,20 +10,76 @@ export interface CartLineItemProps {
 }
 
 export function CartLineItem({ line, currency }: CartLineItemProps) {
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  async function mutate(method: 'PATCH' | 'DELETE', body: Record<string, unknown>): Promise<void> {
+    setPending(true);
+    setError(null);
+    try {
+      const res = await fetch('/api/cart', {
+        method,
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+      });
+      if (!res.ok) {
+        const data = (await res.json().catch(() => ({}))) as { error?: string };
+        setError(data.error ?? 'Could not update the cart.');
+        return;
+      }
+      location.reload();
+    } catch {
+      setError('Could not update the cart.');
+    } finally {
+      setPending(false);
+    }
+  }
+
   return (
-    <li className="vt-cart-line flex items-center gap-gutter border-b border-border py-unit">
-      {line.image ? (
-        <img src={line.image} alt="" className="h-16 w-16 rounded-md object-cover" />
-      ) : (
-        <div className="h-16 w-16 rounded-md bg-muted" aria-hidden="true" />
-      )}
-      <div className="flex-1">
-        <p className="text-fg">{line.title}</p>
-        <p className="text-muted-fg">
-          {line.quantity} × {formatMoney(line.unitPrice, currency)}
-        </p>
+    <li className="vt-cart-line flex flex-col gap-unit border-b border-border py-unit">
+      <div className="flex items-center gap-gutter">
+        {line.image ? (
+          <img src={line.image} alt="" className="h-16 w-16 rounded-md object-cover" />
+        ) : (
+          <div className="h-16 w-16 rounded-md bg-muted" aria-hidden="true" />
+        )}
+        <div className="flex-1">
+          <p className="text-fg">{line.title}</p>
+          <p className="text-muted-fg">{formatMoney(line.unitPrice, currency)} each</p>
+        </div>
+        <p className="text-price">{formatMoney(line.lineTotal, currency)}</p>
+      </div>
+      <div className="flex flex-wrap items-center gap-gutter">
+        <label className="flex items-center gap-unit text-sm text-fg">
+          <span className="text-muted-fg">Qty</span>
+          <input
+            type="number"
+            min={1}
+            max={999}
+            value={line.quantity}
+            disabled={pending}
+            className="w-16 rounded-md border border-input bg-surface px-unit py-unit text-surface-fg focus-visible:outline-none focus-visible:ring-2 ring-ring disabled:opacity-50"
+            onChange={(e) => {
+              const quantity = Number(e.target.value);
+              if (!Number.isInteger(quantity) || quantity < 1) return;
+              void mutate('PATCH', { lineId: line.id, quantity });
+            }}
+          />
+        </label>
+        <button
+          type="button"
+          disabled={pending}
+          onClick={() => void mutate('DELETE', { lineId: line.id })}
+          className="text-sm text-muted-fg underline underline-offset-2 transition hover:text-fg disabled:opacity-50 focus-visible:outline-none focus-visible:ring-2 ring-ring"
+        >
+          Remove
+        </button>
+        {error ? (
+          <p role="alert" className="text-sm text-danger">
+            {error}
+          </p>
+        ) : null}
       </div>
-      <p className="text-price">{formatMoney(line.lineTotal, currency)}</p>
     </li>
   );
 }

package/kit/registry/cart/files/components/cart/CartView.tsx

@@ -1,6 +1,9 @@
 // Cart contents — presentational. Hosts the cart.items-bottom / cart.below slots.
+'use client';
+
 import type { Cart } from '@vitrine-kit/contracts';
 import { Slot } from '@vitrine-kit/core/react';
+import { useChromeLabel } from '@/lib/i18n/useChromeLabel';
 import { CartLineItem } from './CartLineItem.js';
 import { CartSummary } from './CartSummary.js';
 
@@ -9,23 +12,22 @@ export interface CartViewProps {
 }
 
 export function CartView({ cart }: CartViewProps) {
+  const continueShopping = useChromeLabel('continueShopping');
+  const addToCart = useChromeLabel('addToCart');
+
   if (cart.lines.length === 0) {
     return (
       <div className="vt-cart-empty flex flex-col gap-gutter">
         <p className="text-muted-fg">Your cart is empty.</p>
         <p className="text-sm text-muted-fg">
-          Open a product such as{' '}
-          <a href="/products/classic-tee" className="text-fg underline underline-offset-2">
-            Classic T-Shirt
-          </a>
-          , pick a size, then use <span className="text-fg">Add to cart</span> to try the checkout
-          flow.
+          Browse the catalog, open a product, then use <span className="text-fg">{addToCart}</span>{' '}
+          to start checkout.
         </p>
         <a
           href="/"
           className="w-fit rounded-md border border-border px-gutter py-unit text-fg transition hover:bg-muted focus-visible:outline-none focus-visible:ring-2 ring-ring"
         >
-          Continue shopping
+          {continueShopping}
         </a>
       </div>
     );

package/kit/registry/catalog/feature.json

@@ -2,7 +2,7 @@
   "$schema": "../../schemas/feature.schema.json",
   "name": "catalog",
   "title": "Product catalog",
-  "kitVersion": "0.4.3",
+  "kitVersion": "0.5.0",
   "requiresContracts": ">=1.0.0 <2.0.0",
   "tier": [
     "catalog",

package/kit/registry/catalog/files/lib/catalog/data.ts

@@ -1,7 +1,71 @@
 // Catalog access via the CatalogSource contract. The source (Payload*/Vendure*)
 // is resolved in the page data (template); a ready CatalogSource arrives here —
 // so the feature depends only on the contract and is portable across backends.
-import type { CatalogSource, Category, Product, ProductQuery } from '@vitrine-kit/contracts';
+import type {
+  CatalogSource,
+  Category,
+  Product,
+  ProductQuery,
+  ProductSort,
+} from '@vitrine-kit/contracts';
+
+export function parseProductSort(value: string | undefined | null): ProductSort | undefined {
+  if (value === 'newest' || value === 'price-asc' || value === 'price-desc' || value === 'relevance') {
+    return value;
+  }
+  return undefined;
+}
+
+/** Parse `?size=S&size=L&color=Black` style params into ProductQuery.filters. */
+export function parseProductFilters(
+  params: Record<string, string | string[] | undefined>,
+  facetKeys: string[] = ['size', 'color'],
+): Record<string, string[]> | undefined {
+  const filters: Record<string, string[]> = {};
+  for (const key of facetKeys) {
+    const raw = params[key];
+    if (raw == null) continue;
+    const values = (Array.isArray(raw) ? raw : [raw])
+      .flatMap((v) => String(v).split(','))
+      .map((v) => v.trim())
+      .filter(Boolean);
+    if (values.length) filters[key] = [...new Set(values)];
+  }
+  return Object.keys(filters).length ? filters : undefined;
+}
+
+export function parsePriceBound(value: string | string[] | undefined | null): number | undefined {
+  const raw = Array.isArray(value) ? value[0] : value;
+  if (raw == null || raw === '') return undefined;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0) return undefined;
+  // URL values are major currency units ($); ProductQuery uses minor units.
+  return Math.round(n * 100);
+}
+
+/** Aggregate option values present on the given products (for toolbar facets). */
+export function collectOptionFacets(products: Product[]): Record<string, string[]> {
+  const buckets = new Map<string, Set<string>>();
+  for (const p of products) {
+    for (const v of p.variants) {
+      if (!v.options) continue;
+      for (const [key, val] of Object.entries(v.options)) {
+        if (!val) continue;
+        let set = buckets.get(key);
+        if (!set) {
+          set = new Set();
+          buckets.set(key, set);
+        }
+        set.add(val);
+      }
+    }
+  }
+  const out: Record<string, string[]> = {};
+  for (const [key, set] of [...buckets.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    out[key] = [...set].sort((a, b) => a.localeCompare(b));
+  }
+  return out;
+}
 
 export async function loadProducts(
   source: CatalogSource,
@@ -10,12 +74,16 @@ export async function loadProducts(
   return source.listProducts(query);
 }
 
-export async function loadProduct(source: CatalogSource, slug: string): Promise<Product | null> {
-  return source.getProduct(slug);
+export async function loadProduct(
+  source: CatalogSource,
+  slug: string,
+  locale?: string,
+): Promise<Product | null> {
+  return source.getProduct(slug, locale);
 }
 
-export async function loadCategories(source: CatalogSource): Promise<Category[]> {
-  return source.listCategories();
+export async function loadCategories(source: CatalogSource, locale?: string): Promise<Category[]> {
+  return source.listCategories(locale);
 }
 
 /** Money — minor units (e.g. cents); divide by 100 for 2-decimal currencies. */

package/kit/registry/checkout/docs/checkout.md

@@ -8,10 +8,28 @@ A provider-agnostic checkout scaffold for `simple-store` / `full-store`. Depends
   `POST /api/checkout` and redirects to the provider URL. It knows nothing about the provider.
 - **API (Next glue):** `POST /api/checkout` — `CommerceBackend.startCheckout`
   delegates to the active provider (`payments.resolve` by `integrations.payments`).
+- **Success page:** `app/(frontend)/order/success` — post-payment landing (`order.*` slots).
 - **Shared webhook code:** `lib/checkout/fulfill.ts` → `fulfillOrderFromEvent` —
   idempotent order creation from a normalized event (used by all provider webhook
   routes). The critical logic (dedup by `paymentRef`, order snapshot) lives in
   `@vitrine-kit/core` (`shouldCreateOrder`, `buildOrderFromCart`).
+- **Email:** `lib/checkout/notify.ts` — after fulfill, calls `payload.sendEmail` when the
+  `email` feature + SMTP (or console adapter) is configured; otherwise logs to the server console.
 
 Flow: cart → `Checkout` → `POST /api/checkout` → redirect to the provider →
-provider webhook → `fulfillOrderFromEvent` → order in the admin, cart `converted`.
+provider webhook → `fulfillOrderFromEvent` → order in the admin, cart `converted` →
+confirmation email (or console log).
+
+## Shipping and tax (v1 scope)
+
+This kit uses **hosted checkout** (Stripe Checkout / Paddle / YooKassa). There is no
+in-store multi-step address form.
+
+| Concern | v1 behavior |
+|---|---|
+| **Shipping address** | Collected by the payment provider on their hosted page (when enabled in the PSP dashboard). Not stored on the Payload cart/order beyond what the webhook returns (email). |
+| **Shipping rates** | Configure in the PSP (Stripe Shipping Rates, etc.). The storefront does not compute rates. |
+| **Tax / VAT** | Prefer PSP tax (Stripe Tax, Paddle VAT). Cart/order only expose optional `discountTotal` — no tax engine in `@vitrine-kit/core` yet. |
+| **Digital goods** | Leave shipping disabled in the PSP; customers still get `/order/success` after pay. |
+
+Physical-goods merchants should enable shipping/tax in the chosen provider dashboard before going live.

package/kit/registry/checkout/feature.json

@@ -2,7 +2,7 @@
   "$schema": "../../schemas/feature.schema.json",
   "name": "checkout",
   "title": "Checkout",
-  "kitVersion": "0.4.3",
+  "kitVersion": "0.5.0",
   "requiresContracts": ">=1.0.0 <2.0.0",
   "tier": [
     "simple-store",

package/kit/registry/checkout/files/app/(frontend)/order/success/page.tsx

@@ -0,0 +1,49 @@
+// Post-payment landing page. Stripe/Paddle/YooKassa redirect here after a successful
+// hosted checkout (successPath default: /order/success). Order fulfillment happens
+// asynchronously via the provider webhook — this page is confirmation UX only.
+import type { Metadata } from 'next';
+import { cookies } from 'next/headers';
+import { Slot } from '@vitrine-kit/core/react';
+import { siteName } from '@/lib/site';
+import { t } from '@/lib/i18n/dictionary';
+
+export const metadata: Metadata = {
+  title: 'Order confirmed',
+};
+
+interface PageProps {
+  searchParams: Promise<{ session_id?: string }>;
+}
+
+export default async function OrderSuccessPage({ searchParams }: PageProps) {
+  const params = await searchParams;
+  const sessionId = params.session_id;
+  const locale = (await cookies()).get('vitrine_locale')?.value ?? 'en';
+
+  return (
+    <div className="vt-order-success flex flex-col gap-section">
+      <Slot name="order.top" />
+      <section aria-labelledby="order-success-heading" className="flex flex-col gap-gutter">
+        <h1 id="order-success-heading" className="font-heading text-3xl text-fg">
+          {t('thankYou', locale)}
+        </h1>
+        <p className="max-w-prose text-muted-fg">
+          Your payment was received. {siteName} will email a confirmation when the order is
+          recorded{sessionId ? ' (this can take a few seconds while the payment webhook runs)' : ''}.
+        </p>
+        {sessionId ? (
+          <p className="text-sm text-muted-fg">
+            Reference: <span className="font-mono text-fg">{sessionId}</span>
+          </p>
+        ) : null}
+        <a
+          href="/"
+          className="w-fit rounded-md bg-primary px-gutter py-unit text-primary-fg transition hover:opacity-90 focus-visible:outline-none focus-visible:ring-2 ring-ring"
+        >
+          {t('continueShopping', locale)}
+        </a>
+      </section>
+      <Slot name="order.below" />
+    </div>
+  );
+}

package/kit/registry/checkout/files/app/api/checkout/route.ts

@@ -8,6 +8,11 @@ import { getCommerceBackend } from '@/lib/adapter';
 
 const RATE_LIMIT = { limit: 10, windowMs: 60_000 };
 
+function publicError(error: unknown): string {
+  if (!(error instanceof Error)) return 'Checkout is unavailable — try again later.';
+  return error.message.replace(/^\[vitrine\]\s*/, '');
+}
+
 export async function POST(req: Request) {
   const { allowed, retryAfterMs } = checkRateLimit(`checkout:${clientIpFromHeaders(req.headers)}`, RATE_LIMIT);
   if (!allowed) {
@@ -18,7 +23,13 @@ export async function POST(req: Request) {
   }
   const cartId = (await cookies()).get('vitrine_cart')?.value;
   if (!cartId) return NextResponse.json({ error: 'cart is empty' }, { status: 400 });
-  const commerce = await getCommerceBackend();
-  const { redirectUrl } = await commerce.startCheckout(cartId);
-  return NextResponse.json({ url: redirectUrl });
+  try {
+    const commerce = await getCommerceBackend();
+    const { redirectUrl } = await commerce.startCheckout(cartId);
+    return NextResponse.json({ url: redirectUrl });
+  } catch (error) {
+    const message = publicError(error);
+    const status = /is not set|empty/i.test(message) ? 503 : 500;
+    return NextResponse.json({ error: message }, { status });
+  }
 }

package/kit/registry/checkout/files/components/checkout/CheckoutButton.tsx

@@ -3,12 +3,14 @@
 // redirect URL — the component doesn't know which provider is configured (Stripe/Paddle/YooKassa).
 'use client';
 import { useState } from 'react';
+import { useChromeLabel } from '@/lib/i18n/useChromeLabel';
 
 export function CheckoutButton() {
   const [pending, setPending] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  const checkout = useChromeLabel('checkout');
 
-  async function checkout(): Promise<void> {
+  async function startCheckout(): Promise<void> {
     setPending(true);
     setError(null);
     try {
@@ -30,11 +32,11 @@ export function CheckoutButton() {
     <>
       <button
         type="button"
-        onClick={checkout}
+        onClick={startCheckout}
         disabled={pending}
         className="vt-checkout-button rounded-md bg-primary px-gutter py-unit text-primary-fg transition hover:opacity-90 disabled:opacity-50 focus-visible:outline-none focus-visible:ring-2 ring-ring"
       >
-        {pending ? 'Redirecting to payment…' : 'Checkout'}
+        {pending ? 'Redirecting to payment…' : checkout}
       </button>
       {error ? (
         <p role="alert" className="vt-checkout-error text-danger">

package/kit/registry/checkout/files/lib/checkout/fulfill.ts

@@ -12,6 +12,7 @@ import {
   type NormalizedPaymentEvent,
   type PaymentProviderName,
 } from '@vitrine-kit/core';
+import { notifyOrderConfirmation } from './notify.js';
 
 /** Creates an order from the cart on a payment event and marks the cart converted. */
 export async function fulfillOrderFromEvent(
@@ -50,6 +51,22 @@ export async function fulfillOrderFromEvent(
   };
   const order = buildOrderFromCart(cart, { id: cartId, email: event.email });
 
+  // When the accounts feature is installed, attach the matching customer by checkout email.
+  let customerId: string | undefined;
+  const email = event.email?.trim().toLowerCase();
+  if (email) {
+    const customers = await payload
+      .find({
+        collection: 'customers',
+        where: { email: { equals: email } },
+        limit: 1,
+        overrideAccess: true,
+      })
+      .catch(() => null);
+    const doc = customers?.docs[0];
+    if (doc) customerId = String(doc.id);
+  }
+
   await payload.create({
     collection: 'orders',
     data: {
@@ -62,6 +79,7 @@ export async function fulfillOrderFromEvent(
       createdAt: order.createdAt,
       paymentProvider: providerName,
       paymentRef: event.providerRef,
+      ...(customerId ? { customer: customerId } : {}),
     },
   });
   await payload.update({
@@ -69,4 +87,8 @@ export async function fulfillOrderFromEvent(
     id: cartId,
     data: { status: 'converted', paymentRef: event.providerRef },
   });
+
+  await notifyOrderConfirmation(order).catch((err) => {
+    console.warn('[vitrine] order confirmation notify failed', err);
+  });
 }