Commerce

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/.env.local; Next.js 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
• Terminal basics
• Web local setup
• Agent prompts & project memory

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
• Product grid block
• Records table block

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.