# Cartbase Storefront Docs

> Complete reference for building a storefront on the Cartbase commerce
> platform: every store API endpoint (request/response shapes, auth,
> errors, working curls), the @cartbase/storefront SDK + UI components,
> and the admin settings that change each behavior. Written for agents:
> a storefront must be buildable from these files alone.

Every page is also served as raw Markdown — append `.md` to its URL.
The full corpus in one file: https://docs.cartbase.ai/llms-full.txt

## Start here

- [Build a storefront](https://docs.cartbase.ai/build-a-storefront.md): This runbook takes you from a blank Next.js app to a completed checkout against your Cartbase store. It is written to be followed by a developer or handed to a coding agent as-is. Each step names the domain doc that carries the full contrac
- [Deploy](https://docs.cartbase.ai/deploy.md): Cartbase builds and hosts your storefront. You send the app's source files — one snapshot of the whole project — and Cartbase turns it into a running site: first on a permanent preview URL, then, when you press Publish (or call the publish

## Catalog

- [Products](https://docs.cartbase.ai/products.md): The catalog read surface. The product object documented here is THE canonical shape every discovery endpoint reuses (search results, collection membership pages, related products) — build one product-card renderer against it. Money is EUR d
- [Search](https://docs.cartbase.ai/search.md): Configurable storefront search (search-discovery card) plus the PDP's related-products rail. Results are the SAME canonical product objects the products listing serves (see products.md) — reuse your product-card renderer as-is. Money is EUR
- [Collections](https://docs.cartbase.ai/collections.md): Curated product groupings (manual or smart). The membership listing — /collections/:id/products — is the collection page's data source: it reads the membership JOIN (multi-collection products appear in every collection they belong to), hono
- [Categories](https://docs.cartbase.ai/categories.md): Taxonomy reads for navigation trees and filter UIs. Categories are hierarchical (parentcategoryid) with optional ancestor/descendant tree embedding; tags and types are flat value lists whose ids feed the tagid / typeid filters on product li
- [Regions](https://docs.cartbase.ai/regions.md): Catalog-context primitives a storefront resolves at boot: regions feed the pricing context (regionid → region currency), currencies tell you what the store has enabled, locales drive the language switcher and the client's x-locale header. A

## Buying

- [Carts](https://docs.cartbase.ai/carts.md): The cart is the storefront's working document: created anonymously, mutated through line-item and update calls, completed into an order (see checkout.md for the Buy-click sequence and gift-cards.md for gift-card tender). Every mutation retu
- [Gift cards](https://docs.cartbase.ai/gift-cards.md): Gift-card redemption is a payment tender (ppgiftcard), never a discount: cart totals and VAT compute first and never move; applied cards cover part (or all) of cart.total and the remainder provider (Stripe/COD/manual) charges only what is l
- [Checkout](https://docs.cartbase.ai/checkout.md): This page is the full checkout knowledge transfer: every listing, the orchestrated Buy-click sequence, the amount-sync matrix, dead-PI recovery, and the completion contract. Amounts are EUR decimal major units and the server totals engine i
- [Orders](https://docs.cartbase.ai/orders.md): The authenticated customer's order surface: list, detail (items + fulfillments with tracking + addresses) and order transfers. There is no anonymous order read — every endpoint on this page requires a customer session (authorization: Bearer

## Customers

- [Customers](https://docs.cartbase.ai/customers.md): The signed-in customer surface. Every endpoint here requires a customer session: authorization: Bearer <supabase jwt> (minted by the passwordless flow — see auth.md — or a client-side supabase password sign-in) plus the x-client-id tenant h
- [Auth](https://docs.cartbase.ai/auth.md): Passwordless email-code login (customer-accounts card, Shopify Customer Account API direction). Two calls: request emails a 6-digit code, verify exchanges it for a session. Password login (supabase.auth.signInWithPassword client-side) stays
- [Subscriptions](https://docs.cartbase.ai/subscriptions.md): The "My subscriptions" surface (subscriptions-portal card): list, detail, schedule control, contract edits, cancel/reactivate and payment-method recovery. Every endpoint requires a customer session (authorization: Bearer <supabase jwt> — se

## Content

- [Content](https://docs.cartbase.ai/content.md): Shopify Storefront Page / Article shapes verbatim so storefront code ports 1:1. PUBLISHED only — drafts and deleted rows 404 (lib status filter AND the anon RLS policy). Stored HTML is server-sanitized on write — safe to render raw (dangero
- [Menus](https://docs.cartbase.ai/menus.md): Shopify Storefront Menu shape verbatim (content-navigation card). Items store a typed resource reference; url is computed at read time from the live handle (src/lib/content/paths.ts) — a product/page handle rename never breaks a menu. Items
- [Metaobjects](https://docs.cartbase.ai/metaobjects.md): Merchant-defined structured content (size charts, brand profiles, FAQ blocks) served by TYPE + HANDLE (metaobjects card). ACTIVE entries only — drafts 404 (lib filter AND anon RLS, defense in depth).
- [Reviews](https://docs.cartbase.ai/reviews.md): Verified-purchase reviews. Reviews exist only via a single-use, order-scoped, expiring token minted by the request scanner and mailed as <reviewlinkbase>/<token> — the token IS the auth for every write; no login. All public reads serve stat
- [Redirects](https://docs.cartbase.ai/redirects.md): Exact-match redirect lookup (seo-listings card 21). Hot-path rule: call this ONLY from the storefront's not-found handler — never on regular page loads (index-covered exact match on (clientid, frompath)). When topath is non-null, issue a 30

## Store config

- [Integrations](https://docs.cartbase.ai/integrations.md): Store-public integration configuration for render/checkout time (couriers-port + tracking-integrations cards). The payload is composed from an ordered block registry — each block owns distinct top-level keys (carriers, cod, tracking today;
- [Consent](https://docs.cartbase.ai/consent.md): The store's CMP configuration for the built-in Consent Mode v2 banner (consent-management card). Defaults are always applied server-side, so the payload is complete and renderable even for an unconfigured store (compliant built-in modal, BG
- [Variables](https://docs.cartbase.ai/variables.md): Every value a store can put into a notification, a document or a page, as a named token. Write {{ order.total }} and the store fills in the amount, in its own currency, formatted the way the rest of the platform formats money. There are 122
- [Platform fingerprints](https://docs.cartbase.ai/platform.md): Every Cartbase-powered storefront emits a small, deliberate set of signals so platform-detection tools (Wappalyzer, BuiltWith) classify the site as Ecommerce — the same mechanism Shopify uses (window.Shopify, X-ShopId, shopifys). Full spec:

## UI components

- [Components](https://docs.cartbase.ai/components.md): The component layer of @cartbase/storefront: what each family ships, the SDK calls it requires, the admin settings that change its behavior, and its mount rules. Every family is production-proven — ported from live commerce storefronts and