> ## Documentation Index > Fetch the complete documentation index at: https://supastack.dev/llms.txt > Use this file to discover all available pages before exploring further. > For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt # Commerce Workspace products and orders on a forward-only lifecycle. ## Beginner walkthrough Prerequisites: Read the two beginner guides below, finish Web local setup, and open this monorepo at its root in your editor. Web settings belong in `apps/web-tanstack/.env.local`; TanStack Start does not read the root `.env`. `/dashboard` in the default fake mode is a no-database demo; `/auth` needs a migrated database. Quick terms: a workspace is one team's separate users, data, and settings. The server is the trusted backend; keep provider keys out of browser and phone code. A migration is a versioned database change that creates or updates tables. An AI model is the engine that answers; the model catalog is the server's list of available model IDs and prices. A provider is an outside service such as an AI, email, or billing service. An entitlement is a grant that lets a workspace use a feature. A webhook is a message one service sends to another service's URL. 1. As a workspace owner or admin, open `/commerce` and use the product form to create a draft with a name, currency, integer minor-unit price, and optional tracked stock (for USD, `1299` means $12.99). 2. Activate it and create a local test order; confirm the server calculates the total and stores the product snapshot. 3. Do not connect a live payment provider or charge a real buyer. If an order cannot advance, check available stock and the documented order state before retrying. For custom code, start with the supplied `prompts/README.md` and copy the closest prompt: `prompts/new-app-screen.md` for an app screen or `prompts/new-landing-page.md` for a public page. For server, database, or provider work, give your coding agent this guide's task and ask it to read `AGENTS.md`, `.ai/PROJECT_CONTEXT.md`, and matching `.ai/` mirrors; inspect the exact source files named here; list files and checks before editing; preserve workspace ownership and server-only secrets; and show you the diff. Tell it the behavior you want, input and output fields, allowed roles, expected success and errors, and the test account, provider, or device. Use sample values; never paste a real secret. [Before you start](https://supastack.dev/docs/tanstack/before-you-start.md) [Terminal basics](https://supastack.dev/docs/tanstack/terminal-basics.md) [Web local setup](https://supastack.dev/docs/tanstack/ship-in-5-minutes.md) [Agent prompts & project memory](https://supastack.dev/docs/tanstack/agents.md) ## Manage products and inventory `/commerce` provides owner/admin management for workspace products. Product states are draft/active/archived; prices use minor currency units and inventory is optionally tracked. Shared persistence lives in `packages/db`. This is a product-building module. It does not include purchasing this kit, source-repository delivery or seller license fulfillment. ## Follow the order lifecycle Orders advance pending → paid → fulfilled, with cancellation/restocking and refund behavior. The server computes totals and stores item product-name/unit-price snapshots so edits to a product do not rewrite historical orders. `commerce.order_*` events support downstream integrations. Connect a real product payment flow deliberately. An admin state transition alone does not verify a payment provider charge or refund. ## Test stock and state transitions Verify insufficient inventory, concurrent orders, client-price tampering, invalid backward transitions, cancellation restocking, refund behavior and cross-workspace access. [Outbound commerce events](https://supastack.dev/docs/tanstack/project-structure.md) [Product grid block](https://supastack.dev/docs/tanstack/project-structure.md) [Records table block](https://supastack.dev/docs/tanstack/project-structure.md) ## Setup and configuration The /commerce surface manages a product catalogue and orders for the active workspace. Products carry a name, slug, integer-cent price, three-letter currency, optional image URL, and optional tracked inventory; orders store line items in commerce_order_item with totals computed on the server. Order status moves forward only — pending → paid → fulfilled, with cancel before payment and refund after. evaluateOrderStatusChange rejects invalid, unchanged, or forbidden transitions, so a cancelled or refunded order can never reopen. ``` /commerce owner/admin console src/commerce.ts money math + lifecycle src/commerce-actions.ts owner/admin mutations commerce_product/order/order_item ``` ## Implementation workflow Only owners and admins write — every action resolves the session and workspace through requireWorkspaceManager. createCommerceOrderAction validates line items (whole quantities of 1–9999, duplicate products merged), restricts lines to active products, recomputes totals server-side, and keeps an order to a single currency. Tracked inventory decrements when an order is created and restocks on cancel; a blank inventory field means untracked. Order creation and every status change emit commerce.order_created and commerce.order_status_changed webhooks plus audit rows. ## Verification and troubleshooting Verify a member below admin cannot create products or move orders, backward and sideways transitions are rejected, and a paid order cannot be cancelled. Check that totals come from the server — never trust a client-supplied amount — and that stock returns after a cancel. ## Next [Marketing pages](https://supastack.dev/docs/tanstack/marketing-site.md)