Cart & Quote Requests

The default storefront is quote-based: shoppers browse the catalog, add items to a cart, and submit a quote request instead of paying. No payment processor is required, which makes this flow a good fit for B2B, wholesale, made-to-order, and "request a price" catalogs. Submitting a quote drops it straight into the admin quote pipeline and (optionally) fires notification emails.

Stripe checkout is available too, but entirely optional and env-gated — see Payments with Stripe. This page covers the cart and the quote path.

The cart context

Cart state lives in a single React context, CartProvider, consumed through the useCart() hook (src/contexts/cartContext.tsx). It exposes:

import { useCart } from "@/contexts/cartContext";

function AddToCartButton({ product }) {
  const { addItemToCart } = useCart();
  return <button onClick={() => addItemToCart(product)}>Add to cart</button>;
}

Cart line identity

Lines are matched by a cart line key, computed by cartLineKey (src/lib/cart.ts), not by the product id alone:

export function cartLineKey(item: { id: string; variantId?: string }): string {
  return item.variantId ? `${item.id}::${item.variantId}` : item.id;
}

A product with no selected variant keeps its plain product id as the key; a line with a variant is keyed productId::variantId. That means two variants of the same product live in the cart as separate lines. This is why removeItemFromCart and updateQuantityInCart take a lineKey rather than a product id. See Inventory & Variants for how variant lines are built (withSelectedVariant).

Guest carts vs. signed-in carts

The cart is dual-backed. Which store is used is decided by Firebase auth state, watched via onAuthStateChanged inside CartProvider.

[{ "id": "sku-123", "productName": "…", "quantity": 2 }]

The cart operations are part of the backend-agnostic commerce service layer (CartService in src/lib/commerce/types.ts). Under the default Firebase backend they talk to Firestore directly from the browser; with a SQL backend they route through the RPC layer instead. See Backends overview for how the adapter is selected.

Cart merge on login

When a guest signs in, their local cart is not thrown away — it is merged into whatever cart the account already has on the backend. This happens in the auth flows in src/lib/firebase/authService.ts (both email-link sign-in and Google sign-in):

mergeCarts is a pure function (it does not persist anything itself — you pass its result to carts.set). Lines are matched by cartLineKey, and when the same line exists in both carts their quantities are summed; lines only in the guest cart are appended:

const index = mergedCart.findIndex(
  (item) => cartLineKey(item) === cartLineKey(localItem)
);
if (index > -1) {
  mergedCart[index].quantity += localItem.quantity; // sum matching lines
} else {
  mergedCart.push(localItem); // otherwise add the new line
}

Submitting a quote request

The cart page (/cart, rendered by src/components/cart/Cart.tsx) is where a shopper turns their cart into a quote request. There is no payment step. Submission goes through one method regardless of backend:

submit(
  userId: string | null,
  quoteData: { items: Quote["items"]; discount?: AppliedDiscount },
  customerInfo: Quote["customer"],
  message: string
): Promise<{ userQuoteId: string; mainQuoteId: string }>

It returns userQuoteId — the human-readable quote number, e.g. Q-20260701-1234 — and mainQuoteId, the backend record id.

Signed-in vs. guest submission

The cart component branches on auth state:

const { userQuoteId } = await commerce.quotes.submit(
  userId!,
  quoteData,
  customerInfoToUse!,
  additionalInfo
);

const { userQuoteId } = await commerce.quotes.submit(
  null,
  quoteData,
  customerInfo,
  additionalInfo
);

After a successful submit the cart component calls saveCart([]) to empty the cart and clears any applied discount, then shows a confirmation toast (and, for signed-in users, redirects to /account).

What gets stored

Under the hood submit writes the quote via saveQuote (src/lib/firebase/dbService.ts). Every quote is created with status Pending and each line gets a computed subtotal (quantity * price, defaulting to 0 so price-less catalog items never produce NaN). The quote is written to the top-level quotes collection; for a signed-in user a mirror copy is also written under customers/{uid}/quotes/{quoteNumber} with a back-reference mainQuoteId, which powers the customer's quote history.

A successful submit also emits a quote.submitted lifecycle event on the commerce event bus, so integrations (analytics, webhooks, sync jobs) can react without editing core files.

Notifications

After the quote is stored, the cart component calls notifyQuoteSubmitted, which POSTs the quote to /api/quotes/notify. This drives the transactional emails — a notification to the team that a new quote request came in, and a confirmation to the customer. Emails are best-effort (the call is fire-and-forget and failures are swallowed) and are only attempted when a customer email is present.

Email delivery is optional and env-gated via Resend. If email is not configured, quotes are still stored and appear in the admin pipeline — only the emails are skipped. See Transactional emails for setup and templates.

The admin pipeline

Every submitted quote lands in the admin quotes dashboard, newest first, at status Pending. From there an admin moves it through the pipeline — Pending → Quoted → Accepted / Declined — and can promote an accepted quote into an order (Processing → Shipped → Delivered / Cancelled). See Admin: Quotes and Admin: Orders.

Related