@base44/app-plugin-commerce 0.1.3 → 0.1.5

package/base44/shared/commerce/totals.ts

@@ -73,15 +73,13 @@ function effectiveTax(product: any, variation?: any): { tax_class: string; tax_s
 function resolveTaxAddress(input: TotalsInput): any {
   const basedOn = getSetting(input.settings, "tax", "tax_based_on", "shipping");
   if (basedOn === "billing") return input.billing ?? input.shipping_address ?? {};
-  if (basedOn === "base") return getSetting(input.settings, "general", "address", {});
   return input.shipping_address ?? input.billing ?? {}; // "shipping" default
 }
 
 /** Run the full totals pipeline. Pure aside from reading its inputs. */
 export function calculateTotals(input: TotalsInput): TotalsResult {
   const settings = input.settings ?? {};
-  const taxesEnabled = !!getSetting(settings, "general", "enable_taxes", true);
-  const pricesIncludeTax = taxesEnabled && !!getSetting(settings, "tax", "prices_include_tax", false);
+  const pricesIncludeTax = !!getSetting(settings, "tax", "prices_include_tax", false);
   const taxRates = input.taxRates ?? [];
   const taxAddress = resolveTaxAddress(input);
 
@@ -89,7 +87,7 @@ export function calculateTotals(input: TotalsInput): TotalsResult {
   const lines = (input.items || []).map((it) => {
     const src = it.variation ?? it.product;
     const { tax_class, tax_status } = effectiveTax(it.product, it.variation);
-    const rates = taxesEnabled && tax_status === "taxable" ? matchTaxRates(taxRates, taxAddress, tax_class) : [];
+    const rates = tax_status === "taxable" ? matchTaxRates(taxRates, taxAddress, tax_class) : [];
     let unitPrice = Number(src.price ?? it.product?.price ?? 0);
     let subtotal = round2(unitPrice * it.quantity);
     if (pricesIncludeTax && rates.length) {
@@ -126,9 +124,8 @@ export function calculateTotals(input: TotalsInput): TotalsResult {
   const itemsSubtotal = round2(lines.reduce((a, l) => a + l.subtotal, 0));
 
   // ── 2. coupons ───────────────────────────────────────────────────────────
-  const couponsEnabled = !!getSetting(settings, "general", "enable_coupons", true);
-  const coupons = couponsEnabled ? input.coupons ?? [] : [];
-  const couponLines = applyCoupons(lines, coupons, settings);
+  const coupons = input.coupons ?? [];
+  const couponLines = applyCoupons(lines, coupons);
   for (const l of lines) l.total = round2(l.subtotal - l.discount);
   const discountTotal = round2(lines.reduce((a, l) => a + l.discount, 0));
   const itemsAfterDiscount = round2(lines.reduce((a, l) => a + l.total, 0));
@@ -191,41 +188,39 @@ export function calculateTotals(input: TotalsInput): TotalsResult {
     agg.set(key, cur);
   };
 
-  if (taxesEnabled) {
-    for (const l of lines) {
-      if (!l.rates.length) continue;
-      const subApplied = applyRates(l.subtotal, l.rates);
-      const totApplied = applyRates(l.total, l.rates);
-      l.subtotal_tax = sumTax(subApplied);
-      l.total_tax = sumTax(totApplied);
-      l.taxes = totApplied.map((t, i) => ({
-        rate_id: t.rate.id ?? "",
-        total: t.amount,
-        subtotal: subApplied[i]?.amount ?? 0,
-      }));
-      for (const t of totApplied) bump(t.rate, t.amount, 0);
-    }
-    for (const fee of feeLines) {
-      if (fee.tax_status !== "taxable") continue;
-      const rates = matchTaxRates(taxRates, taxAddress, fee.tax_class);
-      const applied = applyRates(fee.total, rates);
-      fee.total_tax = sumTax(applied);
-      fee.taxes = applied.map((t) => ({ rate_id: t.rate.id ?? "", total: t.amount }));
-      for (const t of applied) bump(t.rate, t.amount, 0);
-    }
-    if (shippingLines.length) {
-      // shipping_tax_class "inherit" = first taxable line's class (intended behavior)
-      const cfg = getSetting(settings, "tax", "shipping_tax_class", "inherit");
-      const cls = cfg === "inherit"
-        ? (lines.find((l) => l.tax_status === "taxable")?.tax_class ?? "standard")
-        : cfg;
-      const rates = matchTaxRates(taxRates, taxAddress, cls).filter((r) => r.shipping !== false);
-      for (const sl of shippingLines) {
-        const applied = applyRates(sl.total, rates);
-        sl.total_tax = sumTax(applied);
-        sl.taxes = applied.map((t) => ({ rate_id: t.rate.id ?? "", total: t.amount }));
-        for (const t of applied) bump(t.rate, 0, t.amount);
-      }
+  for (const l of lines) {
+    if (!l.rates.length) continue;
+    const subApplied = applyRates(l.subtotal, l.rates);
+    const totApplied = applyRates(l.total, l.rates);
+    l.subtotal_tax = sumTax(subApplied);
+    l.total_tax = sumTax(totApplied);
+    l.taxes = totApplied.map((t, i) => ({
+      rate_id: t.rate.id ?? "",
+      total: t.amount,
+      subtotal: subApplied[i]?.amount ?? 0,
+    }));
+    for (const t of totApplied) bump(t.rate, t.amount, 0);
+  }
+  for (const fee of feeLines) {
+    if (fee.tax_status !== "taxable") continue;
+    const rates = matchTaxRates(taxRates, taxAddress, fee.tax_class);
+    const applied = applyRates(fee.total, rates);
+    fee.total_tax = sumTax(applied);
+    fee.taxes = applied.map((t) => ({ rate_id: t.rate.id ?? "", total: t.amount }));
+    for (const t of applied) bump(t.rate, t.amount, 0);
+  }
+  if (shippingLines.length) {
+    // shipping_tax_class "inherit" = first taxable line's class (intended behavior)
+    const cfg = getSetting(settings, "tax", "shipping_tax_class", "inherit");
+    const cls = cfg === "inherit"
+      ? (lines.find((l) => l.tax_status === "taxable")?.tax_class ?? "standard")
+      : cfg;
+    const rates = matchTaxRates(taxRates, taxAddress, cls).filter((r) => r.shipping !== false);
+    for (const sl of shippingLines) {
+      const applied = applyRates(sl.total, rates);
+      sl.total_tax = sumTax(applied);
+      sl.taxes = applied.map((t) => ({ rate_id: t.rate.id ?? "", total: t.amount }));
+      for (const t of applied) bump(t.rate, 0, t.amount);
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/app-plugin-commerce",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Base44 Commerce plugin — entities, backend functions, shared commerce engine, admin UI and the commerce skill, shipped as copyable source",
   "keywords": [
     "base44",

package/scripts/install.js

@@ -26,8 +26,8 @@
  *
  * This is only the static part of the install. The remaining steps live in
  * ../skills/commerce/installation-guidelines.md (deps, deploy, seeding) and
- * ../skills/commerce/post-installation.md (mounting the /admin route, admin
- * role, AGENTS.md registration); day-2 guidance starts at
+ * ../skills/commerce/post-installation.md (mounting the /store-admin route, admin
+ * role, seeding, the storefront quick start); day-2 guidance starts at
  * ../skills/commerce/SKILL.md. The skill folder carries all of this
  * documentation into the app.
  *
@@ -93,6 +93,22 @@
   // longer ships is listed here and removed on install.
   const RETIRED = [
     ["skills", "commerce", "references", "stripe-payments.md"], // → references/online-payments.md
+    // Attributes and their values are edited in the Attributes section of the
+    // Price & Inventory tab, tags in the product sidebar; the product type and the
+    // Advanced tab are gone entirely.
+    ["src", "commerce", "admin", "pages", "products", "Attributes.jsx"],
+    ["src", "commerce", "admin", "pages", "products", "AttributeTerms.jsx"],
+    ["src", "commerce", "admin", "pages", "products", "Tags.jsx"],
+    ["src", "commerce", "admin", "pages", "products", "components", "tabs", "ExternalTab.jsx"],
+    ["src", "commerce", "admin", "pages", "products", "components", "tabs", "AdvancedTab.jsx"],
+    // General + Inventory + Variations merged into PriceInventoryTab.jsx.
+    ["src", "commerce", "admin", "pages", "products", "components", "tabs", "GeneralTab.jsx"],
+    ["src", "commerce", "admin", "pages", "products", "components", "tabs", "InventoryTab.jsx"],
+    ["src", "commerce", "admin", "pages", "products", "components", "tabs", "VariationsTab.jsx"],
+    // Attributes moved into Price & Inventory; weight/dimensions/shipping class
+    // are per variant, so the product-level Shipping tab has nothing left.
+    ["src", "commerce", "admin", "pages", "products", "components", "tabs", "AttributesTab.jsx"],
+    ["src", "commerce", "admin", "pages", "products", "components", "tabs", "ShippingTab.jsx"],
   ];
   let retiredRemoved = 0;
   for (const parts of RETIRED) {
@@ -147,11 +163,11 @@
     "  1. No deps to add: sonner, recharts and react-markdown ship with the default\n" +
     "     Base44 template — check package.json and npm i only what is truly missing;\n" +
     "     do not re-install packages already listed as dependencies\n" +
-    '  2. Mount the admin router: <Route path="/admin/*" element={<AdminApp />} />\n' +
+    '  2. Mount the admin router: <Route path="/store-admin/*" element={<AdminApp />} />\n' +
     "     and implement the payment return page /order-received (post-installation.md)\n" +
-    "  3. Grant your user the admin role, then settle the store's data — generate a catalog,\n" +
-    "     seed the demo data, or initialize defaults from /admin (post-installation.md §2)\n" +
-    "  4. Register the template + skill in AGENTS.md (see skills/commerce/post-installation.md)\n" +
-    "  5. CLI installs only: npx base44 agents push (the hosted runtime syncs agents on write)"
+    "  3. Grant your user the admin role, then seed the store's data — one commerce/seed-store\n" +
+    "     call (store_name required) takes the whole catalog via products, or the demo data\n" +
+    "     via with_sample_data, or defaults only (post-installation.md §2)\n" +
+    "  4. CLI installs only: npx base44 agents push (the hosted runtime syncs agents on write)"
   );
 })();

package/skills/commerce/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: commerce
-description: Base44 Commerce template — 24 commerce.* entities, 16 commerce/* backend functions (storefront + admin APIs + online payments), the shared commerce engine under base44/shared/commerce/, the store admin UI mounted at /admin, and the commerce/StoreAdmin agent (admin copilot). Read before working on store features — the admin UI, storefront building, Stripe wiring, scheduled maintenance, emails, webhooks, downloads, or scaling limits.
+description: Base44 Commerce template — 24 commerce.* entities, 16 commerce/* backend functions (storefront + admin APIs + online payments), the shared commerce engine under base44/shared/commerce/, the Store Management UI mounted at /store-admin, and the commerce/StoreAdmin agent (admin copilot). Read before working on store features — the admin UI, storefront building, Stripe wiring, scheduled maintenance, emails, webhooks, downloads, or scaling limits.
 ---
 
 # Commerce
@@ -13,30 +13,30 @@ Operational guidance for extending, operating and building on the Base44 Commerc
 
 ## IMPORTANT — first-time installation
 
-If the template was just installed (or you are installing it right now), read [`skills/commerce/post-installation.md`](./post-installation.md) **before anything else**: embedding the admin pages, the three-layer admin-role enforcement (do not weaken), **asking the user how the store's data should be created** (generate a real catalog / generic demo data / nothing — §2), and registering the template + skill in the app's `AGENTS.md`. The full install-from-scratch steps are in [`skills/commerce/installation-guidelines.md`](./installation-guidelines.md).
+If the template was just installed (or you are installing it right now), read [`skills/commerce/post-installation.md`](./post-installation.md) **before anything else**: embedding the admin pages, the three-layer admin-role enforcement (do not weaken), seeding the store's data — **one `commerce/seed-store` call takes the whole catalog** (products with attributes; variants, categories and taxonomy created internally — §2) — and the **storefront quick start** (§3): logic-only chunks for product list → product page → cart → checkout that make reading the full API docs unnecessary for the happy path. The full install-from-scratch steps are in [`skills/commerce/installation-guidelines.md`](./installation-guidelines.md).
 
 ## Working on the UI
 
 - **Admin UI** (`src/commerce/admin/`) — a complete store back office ships with the template, and it is **yours to change**: restyle it, add or remove pages, rework flows, extend it however the app needs. To understand the backend it talks to, read [`skills/commerce/docs/api-admin.md`](./docs/api-admin.md) — every admin function/action plus the direct-entity-CRUD contract. The only invariant is the admin-role gating (see above).
-- **Storefront** — **no visitor UI ships**; the storefront *API* is complete (token-based cart), plus framework-free helpers in [`src/commerce/utils/`](../../src/commerce/utils/) (`variants.js`, `shipping-promos.js` — import from `@/commerce/utils`). Build against [`skills/commerce/docs/api-storefront.md`](./docs/api-storefront.md). Navigation comes from three actions — `list-categories` (tree), `list-tags` (flat, with counts) and `list-attributes` (filter UIs). What to render in the grid vs. the product page — and which fields only one of the two calls returns — is [`references/product-render.md`](./references/product-render.md); **tags are the most-skipped part of it and belong in both views**.
+- **Storefront** — **no visitor UI ships**; the storefront *API* is complete (token-based cart), plus framework-free helpers in [`src/commerce/utils/`](../../src/commerce/utils/) (`variants.js`, `shipping-promos.js` — import from `@/commerce/utils`). Start from the logic-only quick start in [`post-installation.md` §3](./post-installation.md#3-storefront-quick-start--logic-only) — it covers the whole buy path; go to [`skills/commerce/docs/api-storefront.md`](./docs/api-storefront.md) for anything beyond it. Navigation comes from three actions — `list-categories` (tree), `list-tags` (flat, with counts) and `list-attributes` (filter UIs). What to render in the grid vs. the product page — and which fields only one of the two calls returns — is [`references/product-render.md`](./references/product-render.md); **tags are the most-skipped part of it and belong in both views**.
 
 ### If you build a storefront, these four are not optional
 
 Agents keep shipping storefronts that miss these, and each one breaks buying outright. Do them; the details are in [`docs/api-storefront.md`](./docs/api-storefront.md) and [`references/storefront-product-page.md`](./references/storefront-product-page.md).
 
-1. **Variant products need one selector per attribute — and the selection must resolve to a variation.** `get-product` gives `product.attributes` (the axes: entries with `variation: true`) and `variations` (the combinations). Render a control per axis, never a list of combinations, then send the resolved `variation_id`:
+1. **Products with variants need one selector per attribute — and the selection must resolve to a variation.** `get-product` gives `product.attributes` (every entry is an axis — there is no product type) and `variations` (the combinations). Render a control per axis, never a list of combinations, then send the resolved `variation_id`:
    ```js
    import { resolveSelection, defaultSelection, selectOption } from "@/commerce/utils";
    const view = resolveSelection(product, variations, selection);   // axes, availability, price, addToCart
    await inv("commerce/storefront-cart", { action: "add-item", cart_token, ...view.addToCart, quantity });
    ```
-   `add-item` **rejects a variable product without `variation_id`** (`400 variation_required`), so a page that ignores this cannot sell anything.
+   `add-item` **rejects a product with attributes unless it gets a `variation_id`** (`400 variation_required`), so a page that ignores this cannot sell anything.
 
 2. **Checkout must present shipping options and send a choice.** After `set-shipping-address`, read `shipping_status` on the cart: `auto_selected` (one option, already applied) · `chosen` · `choice_required` → **you must show `available_shipping_methods` and call `choose-shipping-method`** · `none_available` → say so. `place-order` refuses with `400 shipping_method_required` until then — that is not a bug to work around.
 
 3. **Take card payments, and build `/order-received`.** (Ask the user to connect the provider *after* the store is set up — it's their step in the dashboard, and a catalog plus a shipping method is what makes a test payment provable.) Choosing the online gateway returns `payment.checkout_url` — redirect there. Every payment link comes back to `/order-received`, which **you must implement**: call `commerce/payments` `complete-return` with the query params and render its `state`. Without that page a customer pays into a 404 and the order is never marked paid.
 
-4. **Never advertise what isn't configured.** "Free shipping over €150" must come from a real `free_shipping` zone method — `shipping-promos.js` reads it; no rule means no banner.
+4. **Never advertise what isn't configured.** "Free shipping over €150" must come from a real `free_shipping` zone method. Zones are admin-only data, so a storefront cannot read them: the live answer is the cart's `available_shipping_methods` after `set-shipping-address`, and `shipping-promos.js` normalizes the rules wherever the records *are* in hand. No rule means no banner.
 
 All functions return the envelope `{ success, data }` (or `{ success, error, code }`); with the SDK the body is on `res.data`:
 
@@ -51,8 +51,10 @@ Open the matching file under `skills/commerce/references/` only when a task touc
 
 | Topic | Read when the task involves | Reference |
 |---|---|---|
-| Product rendering (list + page) | what to show in a product grid vs. the product page, field availability across `list-products`/`get-product`, **tags in both views**, variable pricing on cards, adding a page-only field to the listing call | [`references/product-render.md`](./references/product-render.md) |
+| Product rendering (list + page) | what to show in a product grid vs. the product page, field availability across `list-products`/`get-product`, **tags in both views**, variant pricing on cards, adding a page-only field to the listing call | [`references/product-render.md`](./references/product-render.md) |
 | Variant selection | attribute-level selectors, resolving a selection to a variation, availability states, incomplete-selection pricing, add-to-cart contract | [`references/storefront-product-page.md`](./references/storefront-product-page.md) |
+| Reviews | stars on cards and the product page, the review list + submit form (backend ships complete), moderation statuses, verified-only and rating-required behaviors | [`references/reviews.md`](./references/reviews.md) |
+| Admin product form | changing the product editor — its tabs are **Price & Inventory** (tax, then the attributes, then a row per variant, or a single *Base price* row when there are none), **Modifiers** (`meta_data`), **Downloads**, **Linked products**. Variants reconcile from the attribute values automatically: no generate step, no per-variant delete. Weight, dimensions and shipping class are per variant. | [`references/admin-product-form.md`](./references/admin-product-form.md) |
 | Online payments | **any storefront or checkout work** — card payments ship implemented (hosted page, payment links, signed webhook, refunds) behind a provider-neutral utility wired to Stripe; connect a provider to go live, or implement one adapter to use another | [`references/online-payments.md`](./references/online-payments.md) |
 | Scheduled work | recurring maintenance — stock-hold release, abandoned-cart cleanup, webhook-log pruning, counter-drift repair | [`references/scheduled-work.md`](./references/scheduled-work.md) |
 | Emails | transactional order emails, per-type overrides, deliverability, the email log | [`references/emails.md`](./references/emails.md) |

package/skills/commerce/docs/api-admin.md

@@ -14,15 +14,15 @@ Two access styles. **Reads are direct** entity SDK calls; **mutations with side
 | commerce.Coupon | direct | **`commerce/admin-coupons`** | code normalization/uniqueness, webhooks |
 | commerce.Customer | direct | **`commerce/admin-customers`** | email uniqueness, invite/link, stats |
 | commerce.ProductReview | direct | **`commerce/admin-reviews`** | rating recalculation |
-| commerce.ProductCategory, commerce.ProductTag | direct | **direct CRUD**, or `commerce/admin-products` `save-term`/`delete-term`/`list-terms` (the API/agent path) | slug uniqueness per taxonomy |
-| commerce.ProductAttribute, commerce.ProductAttributeTerm | direct | **direct CRUD**, or `commerce/admin-products` `save-term`/`delete-term`/`list-terms` (the API/agent path) | slug uniqueness; attribute delete cascades its terms |
+| commerce.ProductCategory, commerce.ProductTag | direct | **direct CRUD**, or `commerce/admin-products` `save-term`/`delete-term`/`list-terms` (the API/agent path) | category slug uniqueness; tag get-or-create by name |
+| commerce.ProductAttribute, commerce.ProductAttributeTerm | direct | **direct CRUD**, or `commerce/admin-products` `save-term`/`delete-term`/`list-terms` (the API/agent path) | attribute `code` uniqueness; value rename rewrites products; attribute delete cascades its values |
 | commerce.ShippingClass | direct | **direct CRUD** | plain config; RLS enforces admin-only |
 | commerce.TaxClass, commerce.TaxRate, commerce.ShippingZone, commerce.ShippingZoneMethod, commerce.PaymentGateway | direct | **direct CRUD** | config; consumed by the pricing engine at read time |
 | commerce.StoreSettings | direct | **direct CRUD** (one record per `group_id`) | grouped config |
 | commerce.Webhook | direct | **direct CRUD** (+ `commerce/admin-webhooks` for test/redeliver) | definition is data; dispatch is engine |
 | commerce.WebhookDelivery, commerce.EmailLog | direct (read-only logs) | written by the engine | audit logs |
 
-All entities carry admin-only RLS on the operations they restrict (catalog entities are public-read, admin-write; transactional entities are admin-only on all ops). A direct write from a non-admin is rejected by the backend regardless of the UI.
+**Every entity is admin-only on read *and* write** — including the catalog. Storefront access goes exclusively through the `commerce/storefront-*` functions, which run with the service role and project only what is safe; a direct entity read or write from a non-admin is rejected by the backend regardless of the UI. See [`references/guest-access-security.md`](../references/guest-access-security.md).
 
 ## Invocation & envelope
 
@@ -45,24 +45,26 @@ Success: `{ success: true, data }`. Failure: `{ success: false, error, code }` w
 Actions: `save` · `delete` · `batch` · `duplicate` · `set-stock` · `search` · `save-term` · `delete-term` · `list-terms`
 
 - **`save`** — `{ product, variations? }`. Upserts the product (create if no `id`); when `variations` is provided, diffs them (create/update/delete-missing).
-  > **Creating a variable product takes all four of these**, and the last two must be in *this* call: `type: "variable"`; the attribute listed **on the product** as `attributes: [{ attribute_id, name, position, visible: true, variation: true, options: [...] }]`; a `variations` array with one entry per stocked combination (each `{ attributes: [{ attribute_id, name, option }], sku, regular_price, manage_stock: "yes", stock_quantity, status: "publish" }`); and `default_attributes` for the pre-selected combination. A `commerce.ProductAttribute` record on its own changes nothing — the product stays simple and cannot be added to a cart as a variant (`400 variation_required`). Set the parent's `regular_price` to the lowest variation price so catalog cards and price filters work. Enforces SKU + slug uniqueness across products *and* variations (auto-suffixes slug on collision; `duplicate_sku` on SKU clash). Derives `price`/`on_sale` from the sale window and `stock_status` when stock is managed; updates category/tag `count`; rolls parent stock up for variable products; fires `product.created`/`product.updated`. → `{ product, variations }`.
+  > **Selling variants takes both of these in *this* call**: the attribute listed **on the product** as `attributes: [{ attribute_id, name, position, options: [...] }]`, plus a `variations` array with one entry per stocked combination (each `{ attributes: [{ attribute_id, name, option }], sku, regular_price, manage_stock: "yes", stock_quantity, status: "publish" }`) and `default_attributes` for the pre-selected combination. There is **no `type` field**: carrying attributes is what makes a product sell variants, so a `commerce.ProductAttribute` record on its own changes nothing — and a product listing an attribute with no variations cannot be added to a cart at all (`400 variation_required`). Descriptive properties belong in `meta_data`, not `attributes`. **Don't set the parent's price** — `regular_price`, `price` and `on_sale` are derived from the cheapest publishable variant on every save, which is what makes catalog cards, price sorting and price filters agree. Enforces SKU + slug uniqueness across products *and* variations (auto-suffixes slug on collision; `duplicate_sku` on SKU clash). Derives `price`/`on_sale` from the sale window and `stock_status` when stock is managed; updates category/tag `count`; rolls parent stock **and price** up when the product has attributes; fires `product.created`/`product.updated`. → `{ product, variations }`.
 - **`delete`** — `{ id }`. Cascades variations, decrements counts, fires `product.deleted`.
 - **`batch`** — `{ create?: [], update?: [], delete?: [] }` (≤100 total) → per-item results.
 - **`duplicate`** — `{ id }` → new draft copy (name "(Copy)", suffixed SKU, reset sales/ratings) incl. variations.
 - **`set-stock`** — `{ id, variation_id?, quantity }`. Sets quantity, re-derives status, sends low/out-of-stock admin emails on threshold crossings.
-- **`search`** — `{ q?, category_id?, type?, stock_status?, status?, sort?, limit?, skip? }` → `{ rows, has_next }`. `category_id` includes descendant categories.
+- **`search`** — `{ q?, category_id?, stock_status?, status?, sort?, limit?, skip? }` → `{ rows, has_next }`. `category_id` includes descendant categories.
 - **`save-term`** — `{ taxonomy, term }` → the term. Upserts one taxonomy record. `taxonomy` is `"category"` | `"tag"` | `"attribute"` | `"attribute-term"`, and `term` takes the fields for that one:
 
   | taxonomy | entity | `term` fields |
   |---|---|---|
   | `category` | commerce.ProductCategory | `id?, name, slug?, description?, parent_id?, image?, menu_order?` |
-  | `tag` | commerce.ProductTag | `id?, name, slug?, description?` |
-  | `attribute` | commerce.ProductAttribute | `id?, name, slug?, type?, order_by?, has_archives?` |
-  | `attribute-term` | commerce.ProductAttributeTerm | `id?, attribute_id` (**required**, must exist)`, name, slug?, description?, menu_order?` |
+  | `tag` | commerce.ProductTag | `id?, name` |
+  | `attribute` | commerce.ProductAttribute | `id?, name, code?, order?` |
+  | `attribute-term` | commerce.ProductAttributeTerm | `id?, attribute_id` (**required**, must exist)`, name, order?` |
 
-  Slug is derived from the name and made unique within that entity — for an attribute term, unique **within its attribute**. A category's `parent_id` pointing at itself is coerced to `""` (`categoryWithDescendants` would loop). This is how a non-UI caller (notably the StoreAdmin agent) creates the records that `category_ids`/`tag_ids`/`attributes[].attribute_id` reference — assigning an id is useless if the record can't be created. **A variable product needs its `commerce.ProductAttribute` and terms to exist first**, so create those, then `save` the product with `attributes[]`/`variations[]`.
-- **`delete-term`** — `{ taxonomy, id, detach? }` → `{ deleted, detached, terms_deleted }`. Deleting an **attribute** always deletes its terms (a term outliving its attribute is unreachable); `detach: true` additionally strips the attribute from every product's `attributes[]`. For a category or tag, products keep the id by default (the admin UI behaves the same, and the storefront skips ids that no longer resolve); `detach: true` strips it from every product first.
-- **`list-terms`** — `{ taxonomy, q?, attribute_id?, limit?, skip? }` → `{ rows, has_next }`. Categories and attribute terms sort by `menu_order`, tags and attributes by `name`; `attribute_id` filters attribute terms to one attribute. Use it to reuse an existing record instead of creating a duplicate.
+  Only a category has a slug, derived from its name and made unique; its `parent_id` pointing at itself is coerced to `""` (`categoryWithDescendants` would loop). An attribute's **`code`** is derived from the name and made unique — it is the key a storefront filter URL should carry. Creating a **tag** is get-or-create: a name that already exists case-insensitively returns the existing record instead of splitting the tag in two. Renaming an **attribute value** rewrites `attributes[].options` and `default_attributes` on every product using it, and the matching `option` on their variations — products store a value by name, so the rename would otherwise orphan them.
+
+  This is how a non-UI caller (notably the StoreAdmin agent) creates the records that `category_ids`/`tag_ids`/`attributes[].attribute_id` reference — assigning an id is useless if the record can't be created. **A product's `commerce.ProductAttribute` and its values must exist first**, so create those, then `save` the product with `attributes[]`/`variations[]`. (At install time, `commerce/seed-store` can do all of this in one call — it takes whole products by display name and get-or-creates the taxonomy internally; see below.)
+- **`delete-term`** — `{ taxonomy, id, detach? }` → `{ deleted, detached, terms_deleted }`. Deleting an **attribute** always deletes its terms (a term outliving its attribute is unreachable); `detach: true` additionally strips the attribute from every product's `attributes[]`. For a category or tag, products keep the id by default (the storefront skips ids that no longer resolve); `detach: true` strips it from every product first. **For an attribute *value* `detach` is a no-op** — deleting a value leaves its name in every product's `attributes[].options` and leaves the variations that use it in place, so remove the value from the products first (or expect variants the storefront can no longer resolve).
+- **`list-terms`** — `{ taxonomy, q?, attribute_id?, limit?, skip? }` → `{ rows, has_next }`. Categories sort by `menu_order`, attributes and attribute values by `order`, tags by `name`; `attribute_id` filters values to one attribute. Use it to reuse an existing record instead of creating a duplicate.
 
 ## commerce/admin-orders
 
@@ -149,7 +151,7 @@ All actions scan orders on demand (counted = `date_paid` set, or status `process
 | `top-sellers` | `{ date_min?, date_max?, limit? }` | `{ rows: [{ product_id, name, sku, quantity, net_revenue }] }` |
 | `stock` | — | `{ low_stock: [...], out_of_stock: [...] }` |
 | `orders-totals` | — | `{ [status]: count }` |
-| `products-totals` | — | `{ total, by: { [type]: count } }` |
+| `products-totals` | — | `{ total, by: { [status]: count } }` |
 | `customers-totals` | — | `{ total, guests, registered, paying }` |
 | `coupons-totals` | — | `{ total, by: { [discount_type]: count } }` |
 | `reviews-totals` | — | `{ total, by: { [status]: count } }` |
@@ -160,7 +162,7 @@ All actions scan orders on demand (counted = `date_paid` set, or status `process
 
 Actions: `status` · `payment-connector-status` · `admin-email-recipients` · `recount-terms` · `recount-coupon-usage` · `recalculate-customer-stats-all` · `prune-webhook-deliveries` · `clear-abandoned-carts` · `regenerate-download-permissions`
 
-- **`status`** — `{ template_version, seeded, settings_groups, counts: { <Entity>: n | "1000+" }, checks: [...] }` — mini system-status; also the seeded/health check for install verification.
+- **`status`** — `{ template_version, seeded, settings_groups, counts: { "commerce.Product": n | "1000+", ... }, checks: { has_payment_gateways, has_default_zone } }` — `counts` is keyed by the **namespaced** entity name, and `checks` is an object, not an array. — mini system-status; also the seeded/health check for install verification.
 - **`payment-connector-status`** — no payload → `{ provider, provider_label, gateway_slug, connected, error?, connector }`. Whether an online payment provider is usable **right now**, answered by the payment utility for whichever provider is wired — so UI derives payment readiness instead of hardcoding a "not set up" notice, and shows "No payment provider connected" rather than a brand. Connectors are service-role only, hence the round trip; any failure reports `connected: false`. A provider connected **after** the function's last deploy reads as `connected: false` until the functions are redeployed — env vars are injected at deploy time ([`references/online-payments.md`](../references/online-payments.md) §2). (`connector` repeats `provider` for callers written against the older shape.)
 - **`admin-email-recipients`** — no payload → `{ recipients: string[], source: "settings" | "admin_users", admin_users: string[] }`. Where admin notifications go **right now**: `recipients` is the configured `emails.admin_recipients`, or the app's admin users when that is empty (the runtime fallback), with `source` saying which. `admin_users` is returned either way, so Settings → Emails can show the fallback as the field's placeholder even while explicit recipients are set. A client can't resolve it itself — listing users needs service role.
 - **`recount-terms`** — repairs category/tag/term `count`.
@@ -183,4 +185,8 @@ Actions: `status` · `create-link` · `complete-return` · `verify` — the admi
 
 ## commerce/seed-store
 
-Not action-routed. Body `{ with_sample_data?: boolean, store_name?: string }`. **`store_name` is required** when the `general` group doesn't exist yet (**400** `store_name_required` otherwise) — pass the app's name **as the platform shows it** — ask the user or read it from the dashboard. `base44/config.jsonc` → `name` is *not* authoritative: it can still say `New App` for an app the platform calls `Canvas`. A backend function can't read either, its environment being only `BASE44_APP_ID`. It becomes the store name *and*, by inheritance, the "from" name on every transactional email; a nameless store renders subjects like `[]: New order #1002`, which is why seeding refuses one. Requires admin. Runs a **canary schema check** first — on any incompatibility returns **422** `{ success:false, code:"schema_incompatible", errors:[{ entity, error }] }` and writes nothing. Otherwise seeds defaults idempotently and (if `with_sample_data` and the store has no products) a sample catalog. On an already-seeded store a passed `store_name` fills a **blank** name and never overwrites one the merchant chose. → `{ seeded: { settings_groups, gateways, tax_classes, zones, zone_methods }, sample_data: {...counts} | false, store_name: { value, action: "created" | "filled" | "unchanged" | "kept_existing" } }`.
+Not action-routed. Body `{ store_name?, with_sample_data?, products?, coupons?, tax_rates? }`. **`store_name` is required** when the `emails` group doesn't exist yet (**400** `store_name_required` otherwise) — pass the app's name **as the platform shows it** — ask the user or read it from the dashboard. `base44/config.jsonc` → `name` is *not* authoritative: it can still say `New App` for an app the platform calls `Canvas`. A backend function can't read either, its environment being only `BASE44_APP_ID`. It lands in `emails.store_name` — one setting serving as both the store name in email subjects and the sender name on every transactional email; a nameless store renders subjects like `[]: New order #1002`, which is why seeding refuses one. Requires admin. Runs a **canary schema check** first — on any incompatibility returns **422** `{ success:false, code:"schema_incompatible", errors:[{ entity, error }] }` and writes nothing. Otherwise seeds defaults idempotently, then the catalog. On an already-seeded store a passed `store_name` fills a **blank** name and never overwrites one the merchant chose.
+
+**`products`** is the one-call catalog bootstrap — the worked example and full semantics are in [`../post-installation.md` §2.1](../post-installation.md#21-the-products-payload). Each entry references categories/tags/attributes by **display name** (taxonomy is get-or-created: slugs/codes derived, existing records matched case-insensitively and reused, with the stored casing canonicalized into the product). `attributes: [{ name, options }]` (or `{ <name>: [options] }`) declares the variant axes; `variations: [{ options: { <name>: <option> }, ...overrides }]` lists the stocked combinations — omit it to auto-generate **all** combinations, each inheriting the product-level price/sale fields. A variation with its own `stock_quantity` gets `manage_stock: "yes"`; without one it draws on the parent's pooled stock (`"parent"`). Variation SKUs are synthesized from the parent SKU when absent. Parent `price`/`regular_price`/`on_sale` are rolled up from the cheapest publishable variant, `stock_status` derived, category/tag counts maintained — same helpers as `admin-products` `save`, but **no `product.created` webhooks are dispatched** (bootstrap precedes webhook subscribers; use `admin-products` for webhook-visible creates). Payload problems fail before any write as **400** `invalid_payload` with `errors: [{ path, error }]`; an explicit variation SKU already in use is **409** `duplicate_sku`; a mid-write failure rolls back everything the call created (**500** `catalog_seed_failed`) without touching reused taxonomy. **Re-runs converge**: a product whose `sku` (or, without one, derived slug) already exists is skipped and reported, so retries never duplicate. Limits: ≤100 products, ≤50 variations per product, ≤500 variations per call, ≤50 coupons/tax rates. `coupons`/`tax_rates` are thin passthroughs (coupon `code` lowercased; both skip-if-exists). `with_sample_data: true` seeds the template's demo catalog instead (only when the store has zero products) and cannot be combined with the catalog keys.
+
+→ `{ seeded: { settings_groups, gateways, tax_classes, zones, zone_methods }, sample_data: {...} | false, catalog: { categories|tags|attributes|terms: { created, reused }, products_created, products_skipped, variations_created, coupons, tax_rates, products: [{ name, id, slug, sku, variation_count } | { name, skipped: true, reason: "sku_exists"|"slug_exists", existing_id }] } | null, store_name: { value, action: "created" | "filled" | "unchanged" | "kept_existing" } }`.

package/skills/commerce/docs/api-storefront.md

@@ -8,7 +8,7 @@ Read this list before writing any of it. Each item is a hard requirement enforce
 
 | # | Requirement | Enforced by |
 |---|---|---|
-| 1 | **Variable products: one selector per attribute**, resolved to a `variation_id` before adding to the cart — never a flat list of combinations | `add-item` → `400 variation_required` ([product page](#get-product)) |
+| 1 | **Products with variants: one selector per attribute**, resolved to a `variation_id` before adding to the cart — never a flat list of combinations | `add-item` → `400 variation_required` ([product page](#get-product)) |
 | 2 | **Present shipping options and send a choice** — drive it off the cart's `shipping_status`; a single option is auto-applied, several mean you must ask | `place-order` → `400 shipping_method_required` ([shipping](#shipping-is-not-optional--read-this-before-building-checkout)) |
 | 3 | **Redirect to `payment.checkout_url`** when the customer pays by card | the order stays `pending` otherwise |
 | 4 | **Implement the return page** (`/order-received`, or your own route set in Settings → General → *Payment return path*) and call `commerce/payments` `complete-return` there | without it a paid order is never confirmed, and a wrong path is a 404 |
@@ -22,8 +22,8 @@ The backend is considerably richer than a minimal "grid → cart → pay" shop.
 
 | Capability | Already supported | Where |
 |---|---|---|
-| **Product discovery** | full-text `search`, filter by category (incl. descendants), tag, attribute+term, price range, `featured`, `on_sale`, `in_stock_only`; sort by menu order / price / newest / **popularity** / **rating**; paging | [`list-products`](#list-products) |
-| **Rich product pages** | galleries, variable products with per-variation price/stock/image, categories, tags, **upsells**, **cross-sells**, grouped-product children | [`get-product`](#get-product) |
+| **Product discovery** | full-text `search`, filter by category (incl. descendants), tag, attribute+term, price range, `featured`, `on_sale`, `in_stock_only`; sort by name / price / **newest** (the default) / **popularity** / **rating**; paging | [`list-products`](#list-products) |
+| **Rich product pages** | galleries, per-variant price/stock/image, categories, tags, **upsells**, **cross-sells** | [`get-product`](#get-product) |
 | **Taxonomy navigation** | category tree, **tag list with counts**, attributes + terms for filter UIs | [`list-categories`](#list-categories), [`list-tags`](#list-tags), [`list-attributes`](#list-attributes) |
 | **Customer reviews** | paginated reviews per product with **average rating + rating count**, `verified` owner flag, and **review submission by signed-in customers**; plus "my reviews" | [`get-product`](#get-product), [`submit-review`](#submit-review), [`my-reviews`](#commercestorefront-account) |
 | **Cart** | guest carts via `cart_token`, add/update/remove, quantity merging, `sold_individually` caps, live re-pricing, stock revalidation | [`commerce/storefront-cart`](#commercestorefront-cart) |
@@ -62,10 +62,13 @@ Bootstrap data for a storefront. No payload.
 **Response:**
 ```json
 {
-  "settings": { "currency": "USD", "currency_position": "left", "thousand_sep": ",", "decimal_sep": ".",
-                "num_decimals": 2, "weight_unit": "kg", "dimension_unit": "cm",
-                "prices_include_tax": false, "enable_reviews": true, "review_rating_required": true },
-  "payment_gateways": [ { "slug": "cod", "title": "Cash on delivery", "description": "..." } ],
+  "settings": { "store_name": "Acme", "currency": "USD", "currency_position": "left",
+                "thousand_sep": ",", "decimal_sep": ".", "num_decimals": 2,
+                "weight_unit": "kg", "dimension_unit": "cm",
+                "prices_include_tax": false, "display_prices_shop": "excl", "display_prices_cart": "excl",
+                "enable_reviews": true, "review_rating_required": true, "hide_out_of_stock": false },
+  "payment_gateways": [ { "slug": "offline", "title": "Offline payment", "description": "...", "online": false },
+                        { "slug": "stripe", "title": "Credit card", "description": "...", "online": true } ],
   "countries": [ { "code": "US", "name": "United States", "states": [ { "code": "CA", "name": "California" } ] } ],
   "currencies": [ { "code": "USD", "name": "US Dollar", "symbol": "$", "decimals": 2 } ]
 }
@@ -73,13 +76,13 @@ Bootstrap data for a storefront. No payload.
 `settings` is a safe projection — only display/behavior keys, never admin config.
 
 ### `list-products`
-**Payload** (all optional): `search`, `category_id` (includes descendants), `tag_id`, `attribute_id` + `attribute_term`, `min_price`, `max_price`, `featured` (bool), `on_sale` (bool), `in_stock_only` (bool), `sort` (`menu_order`|`price`|`-price`|`-created_date`|`popularity`|`rating`, default `menu_order`), `page` (default 1), `per_page` (default 12, max 100).
+**Payload** (all optional): `search`, `category_id` (includes descendants), `tag_id`, `attribute_id` + `attribute_term`, `min_price`, `max_price`, `featured` (bool), `on_sale` (bool), `in_stock_only` (bool), `sort` (`-created_date`|`name`|`price`|`-price`|`popularity`|`rating`, default `-created_date`), `page` (default 1), `per_page` (default 12, max 100).
 
 Only `status: "publish"` products are returned. Visibility: passing `search` uses **search context** (hides `catalog_visibility: hidden|catalog`); no `search` uses **browse context** (hides `hidden|search`). `inventory.hide_out_of_stock` (or `in_stock_only`) drops out-of-stock products.
 
 **Response:** `{ "products": [Product...], "page": 1, "per_page": 12, "has_next": true }`
 
-Each row is the product record (minus paywalled fields) **plus a resolved `tags` array** (`[{ id, name, slug }]`), so cards can show tags without a second call. `categories` are **not** resolved on rows — `category_ids` only.
+Each row is the product record (minus paywalled fields) **plus a resolved `tags` array** (`[{ id, name }]`), so cards can show tags without a second call. `categories` are **not** resolved on rows — `category_ids` only.
 
 > **What to render, and what a row can't show:** [`../references/product-render.md`](../references/product-render.md) — field-availability table for list vs. product page, tags in both views, variable-product pricing on cards, and how to add a `get-product`-only field to the listing call instead of fetching per card.
 
@@ -92,7 +95,7 @@ Each row is the product record (minus paywalled fields) **plus a resolved `tags`
 ```json
 {
   "product": { Product },
-  "variations": [ ProductVariation... ],          // publishable only; [] for non-variable
+  "variations": [ ProductVariation... ],          // publishable only; [] when the product has no attributes
   "categories": [ ProductCategory... ],
   "tags": [ ProductTag... ],
   "reviews": { "items": [ { "id", "reviewer", "review", "rating", "verified", "created_date" } ],
@@ -100,12 +103,11 @@ Each row is the product record (minus paywalled fields) **plus a resolved `tags`
                "average_rating": 4.5, "rating_count": 12 },
   "upsells":  [ { "id", "name", "slug", "price", "on_sale", "image", "stock_status" } ],
   "cross_sells": [ ...summaries ],
-  "grouped_products": [ ...summaries ]
 }
 ```
 **Errors:** `404 not_found` (missing / not published / hidden).
 
-> **Rendering this response as a product page — the rule, not just a link.** `variations[]` is **not** a list of choices to show. Build **one control per `product.attributes[]` entry with `variation: true`** (Size, Color, …), and resolve the combination to a variation client-side; `add-item` needs that `variation_id`. Variable-product prices come from `variations[]`, never from `product.price` (the backend rolls stock up to the parent, not price). The shipped helper does all of it:
+> **Rendering this response as a product page — the rule, not just a link.** `variations[]` is **not** a list of choices to show. Build **one control per `product.attributes[]` entry** (Size, Color, …) — every attribute is an axis — and resolve the combination to a variation client-side; `add-item` needs that `variation_id`. Variant prices come from `variations[]`, never from `product.price` (the backend rolls stock up to the parent, not price). The shipped helper does all of it:
 > ```js
 > import { resolveSelection, defaultSelection, selectOption } from "@/commerce/utils";
 > const [selection, setSelection] = useState(() => defaultSelection(product, variations));
@@ -125,21 +127,21 @@ No payload. Returns a nested tree: `{ "categories": [ { ...category, "children":
 ### `list-tags`
 **Payload** (optional): `{ with_products_only?: boolean }` (default `true`).
 
-Returns `{ "tags": [ { id, name, slug, description, count } ] }` sorted by name. By default it omits tags no published product carries, so a tag nav never links to an empty listing; pass `with_products_only: false` for the full set (e.g. an admin-facing picker).
+Returns `{ "tags": [ { id, name, count } ] }` sorted by name. By default it omits tags no published product carries, so a tag nav never links to an empty listing; pass `with_products_only: false` for the full set (e.g. an admin-facing picker).
 
 `count` is tallied from the products this API would actually list — published, browse-visible, and honoring `inventory.hide_out_of_stock` — **not** from `ProductTag.count`, which also counts drafts and hidden products and drifts until `commerce/admin-tools` `recount-terms` runs. So `Gift (12)` and the tag's listing agree.
 
 This is the **only** way a storefront can enumerate tags — `commerce.ProductTag` is admin-only RLS — and it's what makes `list-products` `tag_id` usable, since that filter needs an id. Tags are a flat, cross-cutting axis ("gift", "summer", "vegan"); categories are the hierarchical spine. Show both: see [*Tags*](../references/product-render.md#2-tags--render-them-in-both-views) for where they belong in each view.
 
 ### `list-attributes`
-No payload. Returns `{ "attributes": [ { ...attribute, "terms": [ ...terms ] } ] }` — for building filter UIs.
+No payload. Returns `{ "attributes": [ { ...attribute, "terms": [ ...values ] } ] }` — the whole attribute record (`id, name, code, order`) plus its values (`id, attribute_id, name, order, count`), attributes sorted by `order` and each attribute's values by their own `order` — for building filter UIs. Filter with `list-products` `attribute_id` (the id, or the attribute **name**) + `attribute_term` (the value name); `code` is the stable key to put in a URL.
 
 ### `submit-review` — **auth**
 **Payload:** `{ product_id, reviewer?, review, rating }`.
 
 **Requires a signed-in customer.** The reviewer's email is taken from the session, never from the payload — a `reviewer_email` field is ignored. `reviewer` is the display name only, and defaults to the account's `full_name`. Build the review form behind a login prompt: anonymous callers get `401 login_required`.
 
-Requires `products.enable_reviews` and the product's `reviews_allowed`. Rating required when `review_rating_required`. If `only_verified_reviews`, the signed-in customer must have a `processing`/`completed` order containing the product. `verified` is derived from their own order history. Status is `hold` unless `auto_approve_reviews`.
+Requires `products.enable_reviews` — reviews are a store-wide switch, not per product. Rating required when `review_rating_required`. If `only_verified_reviews`, the signed-in customer must have a `processing`/`completed` order containing the product. `verified` is derived from their own order history. Status is `hold` unless `auto_approve_reviews`.
 
 **Response:** `{ "review_id", "status": "hold"|"approved", "verified": true }`
 **Errors:** `401 login_required`, `403 reviews_disabled|verified_only|forbidden`, `404 not_found`, `400 review_incomplete|rating_required|invalid_rating`.
@@ -184,10 +186,10 @@ Stored coupons that stop validating are **auto-removed** and reported in `coupon
 | `create` | `{ items?: [{product_id, variation_id?, quantity, attributes?}] }` | Mints and returns a new `cart_token`. Initial items go through add validation. |
 | `get` | `{ cart_token }` | Priced view (also re-prices + merges). |
 | `totals` | `{ cart_token }` | Alias of `get`. |
-| `add-item` | `{ cart_token, product_id, variation_id?, quantity?, attributes? }` | Variable product requires `variation_id` (`400 variation_required`); `sold_individually` caps qty at 1; merges same product+variation. `400 <stock code>`, `404 product_not_found|variation_not_found`. |
+| `add-item` | `{ cart_token, product_id, variation_id?, quantity?, attributes? }` | A product carrying attributes requires `variation_id` (`400 variation_required`); `sold_individually` caps qty at 1; merges same product+variation. `400 <stock code>`, `404 product_not_found|variation_not_found`. |
 | `update-item` | `{ cart_token, item_key, quantity }` | qty ≤ 0 removes the line. `404 item_not_found`, `400 <stock code>`. |
 | `remove-item` | `{ cart_token, item_key }` | |
-| `apply-coupon` | `{ cart_token, code }` | Full validation. `400 coupons_disabled|code_required|already_applied|<coupon code>`. |
+| `apply-coupon` | `{ cart_token, code }` | Full validation. `400 code_required|already_applied|<coupon code>`. |
 | `remove-coupon` | `{ cart_token, code }` | |
 | `set-shipping-address` | `{ cart_token, address: {country, state?, postcode?, city?} }` | `400 country_required`. Returns the matched zone's `available_shipping_methods` and a `shipping_status`. |
 | `choose-shipping-method` | `{ cart_token, method_id }` | `method_id` = a `commerce.ShippingZoneMethod` id from `available_shipping_methods`. `400 invalid_shipping_method` (the error body carries `available_shipping_methods`). |
@@ -219,15 +221,15 @@ Rules the cart enforces on every price, so you get them for free:
 
 Copy like *"Free shipping on orders over €150"* is a **claim about store configuration**, and the checkout will only honour what's actually configured. Don't write such a line into a storefront unless a matching rule exists — either configure it (with the operator's agreement) or leave the copy out.
 
-`commerce.ShippingZone` and `commerce.ShippingZoneMethod` are **public-read**, so the real rule is available to the storefront, and [`src/commerce/utils/shipping-promos.js`](../../../src/commerce/utils/shipping-promos.js) reads it:
+**Zones are admin-only data.** `commerce.ShippingZone` and `commerce.ShippingZoneMethod` are `read: {role: "admin"}` like every entity, so a visitor cannot list them — do not try. Two honest sources:
+
+1. **The cart itself**, which is the live answer for a real address: after `set-shipping-address`, `available_shipping_methods` already reflects every rule the checkout will honour, free shipping included. Prefer this.
+2. **A projection you add**, if you want a threshold banner *before* an address exists: widen `get-store-info` (or add an action) to return the `free_shipping` rules, then normalize them with [`src/commerce/utils/shipping-promos.js`](../../../src/commerce/utils/shipping-promos.js):
 
 ```js
 import { freeShippingRules, freeShippingThreshold, freeShippingProgress } from "@/commerce/utils";
 
-const [zones, methods] = await Promise.all([
-  base44.entities["commerce.ShippingZone"].list("order", 100),
-  base44.entities["commerce.ShippingZoneMethod"].list(undefined, 200),
-]);
+// zones/methods come from your own storefront action — NOT from a client entity read
 const threshold = freeShippingThreshold(freeShippingRules(zones, methods));
 // null → the store has no free-shipping rule: show no banner, no progress bar.
 const progress = freeShippingProgress(threshold, cart.totals.subtotal);  // { threshold, qualifies, remaining }
@@ -242,7 +244,7 @@ A free-shipping rule is a `free_shipping` zone method whose `settings.requires`
 ### `place-order`
 Converts a cart into an order. **Payload:**
 ```json
-{ "cart_token": "uuid", "payment_method": "cod",
+{ "cart_token": "uuid", "payment_method": "offline",
   "billing":  { "first_name", "last_name", "address_1", "address_2?", "city", "state?", "postcode?", "country", "email", "phone?" },
   "shipping": { ...address without email },
   "chosen_shipping_method?": "<zoneMethodId>",
@@ -269,9 +271,9 @@ Converts a cart into an order. **Payload:**
 
   The order is priced with the resolved method, so its `shipping_total` always matches what the customer was shown.
 
-> **Payment.** `payment_method` is a `commerce.PaymentGateway` slug from `get-store-info`. Card payments are **implemented**: choosing the online gateway leaves the order `pending` and returns `payment: { status: "requires_payment", checkout_url, session_id }` — send the customer to `checkout_url` (the provider's hosted page), then confirm on their return with `commerce/payments` `verify`. Never treat a return URL as proof of payment. The manual gateways (`cod`, `bacs`, `cheque`) settle outside the store and return `payment_instructions` instead. An online gateway is only listed while a payment provider is connected, so anything `get-store-info` offers is payable. Optional `success_url` / `cancel_url` / `return_url` in the payload override the default return URLs. See [`../references/online-payments.md`](../references/online-payments.md).
+> **Payment.** `payment_method` is a `commerce.PaymentGateway` slug from `get-store-info`. Card payments are **implemented**: choosing the online gateway leaves the order `pending` and returns `payment: { status: "requires_payment", checkout_url, session_id }` — send the customer to `checkout_url` (the provider's hosted page), then confirm on their return with `commerce/payments` `verify`. Never treat a return URL as proof of payment. The `offline` gateway settles outside the store and returns `payment_instructions` instead. An online gateway is only listed while a payment provider is connected, so anything `get-store-info` offers is payable. Optional `success_url` / `cancel_url` / `return_url` in the payload override the default return URLs. See [`../references/online-payments.md`](../references/online-payments.md).
 
-**Steps:** releases expired holds → revalidates stock & coupons → computes authoritative totals → finds-or-creates the Customer by billing email → creates a `pending` order (with `order_key`, `hold_expires_at`) → reduces stock, fires `new_order` email + `order.created` webhook → marks cart `converted` → routes by gateway: **cod → processing**, **bacs/cheque → on-hold** (with `payment_instructions`), **stripe → stays pending** with a `not_implemented` placeholder, **custom → pending_external**.
+**Steps:** releases expired holds → revalidates stock & coupons → computes authoritative totals → finds-or-creates the Customer by billing email → creates a `pending` order (with `order_key`, `hold_expires_at`) → reduces stock, fires `new_order` email + `order.created` webhook → marks cart `converted` → routes by gateway: **offline → on-hold** (with `payment_instructions`), **stripe → stays pending** until the hosted page is paid, **custom → pending_external**.
 
 > **Saved profiles are only written by their owner.** The order always stores the `billing`/`shipping` it was placed with. The **`commerce.Customer`** record behind it — the one a storefront prefills from — is refreshed only when the caller is signed in *as* the billing email. A guest checkout quoting an existing customer's address still attaches the order to them (so it shows up in their `my-orders`), but cannot change their saved name or addresses. Don't build an "edit my details at checkout" flow for guests; use `update-my-addresses` behind a login instead.
 
@@ -279,10 +281,12 @@ Converts a cart into an order. **Payload:**
 ```json
 {
   "order_id": "...", "order_number": 1001, "order_key": "order_...",
-  "status": "processing", "currency": "USD",
-  "payment_method": "cod", "payment_method_title": "Cash on delivery",
-  "payment_instructions": { "type": "cod", "description": "...", "account_details?": [...] },
-  "payment": null,                       // or { "status": "not_implemented" | "pending_external", "note": "..." } for stripe/custom
+  "status": "on-hold", "currency": "USD",
+  "payment_method": "offline", "payment_method_title": "Offline payment",
+  "payment_instructions": { "type": "offline", "description": "...", "account_details": [...] },
+  "payment": null,                       // offline. For the online gateway:
+                                         //   { "status": "requires_payment", "provider", "checkout_url", "session_id" }
+                                         // For a custom gateway: { "status": "pending_external" }
   "notices": [],                         // e.g. ["account_creation_requires_login"]
   "totals": { "subtotal", "discount_total", "shipping_total", "shipping_tax", "cart_tax", "total_tax", "total" },
   "order": { ...customer-safe order (internal flags/ip stripped) }
@@ -350,9 +354,9 @@ let cart = await inv("commerce/storefront-cart", { action: "create",
   items: [{ product_id: products[0].id, quantity: 1 }] });
 const token = cart.cart_token;
 
-// 3. (variable product) fetch options, then add the chosen variation
+// 3. (product with variants) fetch options, then add the chosen variation
 const detail = await inv("commerce/storefront-catalog", { action: "get-product", id: products[0].id });
-if (detail.product.type === "variable") {
+if ((detail.product.attributes ?? []).length) {
   cart = await inv("commerce/storefront-cart", { action: "add-item",
     cart_token: token, product_id: detail.product.id, variation_id: detail.variations[0].id });
 }
@@ -372,9 +376,9 @@ if (cart.shipping_status === "choice_required") {
   throw new Error("We don't ship to this address");
 }
 
-// 6. Place the order (COD → processing immediately)
+// 6. Place the order (offline → on-hold; no money has arrived yet)
 const order = await inv("commerce/storefront-checkout", { action: "place-order",
-  cart_token: token, payment_method: "cod",
+  cart_token: token, payment_method: "offline",
   billing: { first_name: "Ada", last_name: "Lovelace", address_1: "1 St",
              city: "Los Angeles", state: "CA", postcode: "90210", country: "US", email: "ada@example.com" } });
 
@@ -398,8 +402,8 @@ await inv("commerce/storefront-account", { action: "update-my-addresses",
              state: "CA", postcode: "90210", country: "US", email: "ada@example.com" } });
 
 const order = await inv("commerce/storefront-checkout", { action: "place-order",
-  cart_token: cart.cart_token, payment_method: "bacs", billing: { /* ... */ } });
-// bacs → on-hold; show order.payment_instructions.account_details
+  cart_token: cart.cart_token, payment_method: "offline", billing: { /* ... */ } });
+// offline → on-hold; show order.payment_instructions.account_details
 
 // Order history, downloads, reviews (all auth, no order_key needed)
 const { orders } = await inv("commerce/storefront-account", { action: "my-orders", per_page: 10 });