# 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 @barter/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.bitfar.co/llms-full.txt

## Start here

- [Build a storefront — the runbook](https://docs.bitfar.co/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

## Catalog

- [Products & variants](https://docs.bitfar.co/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 & related products](https://docs.bitfar.co/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 & membership listings](https://docs.bitfar.co/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, tags, types](https://docs.bitfar.co/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, currencies, locales](https://docs.bitfar.co/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 — lifecycle + line items](https://docs.bitfar.co/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 — tender on carts](https://docs.bitfar.co/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 — shipping options, payment, the Buy click, complete](https://docs.bitfar.co/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 — customer reads + transfers](https://docs.bitfar.co/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 — profile, addresses, documents](https://docs.bitfar.co/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 — passwordless code login + session discipline](https://docs.bitfar.co/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 — the customer portal](https://docs.bitfar.co/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 — pages + blogs](https://docs.bitfar.co/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 — backend-owned navigation](https://docs.bitfar.co/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 — merchant-defined content types](https://docs.bitfar.co/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 — widget, token wizard, photo rewards](https://docs.bitfar.co/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
- [URL redirects — 404-path lookup](https://docs.bitfar.co/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

- [Store integrations config — carriers, COD, tracking, lockers](https://docs.bitfar.co/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 — Consent Mode v2 banner config](https://docs.bitfar.co/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

## UI components

- [Components — `@barter/storefront` UI families](https://docs.bitfar.co/components.md): The component layer of @barter/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 re