@base44/app-plugin-commerce 0.1.3 → 0.1.5

package/skills/commerce/references/online-payments.md

@@ -4,7 +4,7 @@
 
 - `base44/shared/commerce/payments.ts` — the **provider-neutral payment utility** every caller uses, plus the one-line `ACTIVE_PROVIDER` binding.
 - `base44/shared/commerce/stripe.ts` — the Stripe adapter (the only file that speaks Stripe).
-- `base44/functions/commerce/payments/` — `status` · `create-link` · `verify`.
+- `base44/functions/commerce/payments/` — `status` · `create-link` · `complete-return` · `verify`.
 - `base44/functions/commerce/payment-webhook/` — the provider's signed callback.
 - `commerce/storefront-checkout` `place-order` returns a `checkout_url`; `commerce/admin-refunds` refunds through the provider; the admin order page has a **Payment** panel.
 
@@ -12,7 +12,7 @@
 
 ## 1. What to do when building a store (strong recommendation, not a rule)
 
-A store that can't take a card is usually not what the user wants: the gateways that work with no provider at all (`cod`, `bacs`, `cheque`) are **manual** — the customer leaves without paying and someone reconciles by hand. So **recommend online payment clearly** — but **at the right moment, which is not first.**
+A store that can't take a card is usually not what the user wants: the gateway that works with no provider at all (`offline`) is **manual** — the customer leaves without paying and someone reconciles by hand. So **recommend online payment clearly** — but **at the right moment, which is not first.**
 
 **Sequence it after the store exists.** Connecting a provider is a step only the *user* can take, in the platform dashboard: asking for it up front stops your work dead on someone else's action, and even once done there is nothing to verify against — no product to buy, no shipping method, no order. Set the store up first (settings → catalog → shipping), *then* raise payments, as the last thing before the store is usable or before you build checkout. The card gateway ships enabled and stays hidden from customers until a provider is connected, so nothing is broken while you wait, and nothing is lost by doing it late.
 
@@ -60,11 +60,11 @@ Card data never touches this app — the customer pays on the provider's page.
 
 1. `success_url` / `cancel_url` — a full page URL per outcome;
 2. `return_url` — **your return page**, used for both outcomes (`payment=success|cancel` distinguishes them). A bare origin (`https://shop`, no path) is instead treated as a base, since there's no page in it;
-3. the store's **Storefront URL** + **Payment return path** (both in general settings: `store_url`, `order_received_path`), or the origin the request came from + that path.
+3. the origin the request came from (the storefront that called this) + the store's **Payment return path** (`settings.general.order_received_path`).
 
 Every result carries `order_id`, `order_key` and `payment`, **including URLs you supplied** — a `success_url` without them can't verify anything. Existing query parameters survive. With nothing to build from, the call fails `400 return_url_required` rather than letting the provider answer "Not a valid URL".
 
-**Set the return path to whatever route you built.** It defaults to `/order-received`, and a wrong value sends paying customers to a 404 — including the confusing `/<your-page>/<your-page>` you get if you treat `return_url` as a base and your page path as a suffix. The admin's payment links deliberately pass no URL at all: the route belongs to the storefront, so they use the store's configured path.
+**Set the return path to whatever route you built.** It defaults to `/order-received`, and a wrong value sends paying customers to a 404 — including the confusing `/<your-page>/<your-page>` you get if you treat `return_url` as a base and your page path as a suffix. The admin's payment links deliberately pass no URL at all: the route belongs to the storefront, so they resolve to the app's own origin plus the store's configured path.
 
 ### MANDATORY: the payment return page (`/order-received`)
 
@@ -101,7 +101,7 @@ Rules for whatever you build:
 - **Handle all three states**, not just the happy one — `unpaid` is common (bank delays, closed tabs) and needs a *Check again* plus *Pay now*, not an error.
 - **Don't gate it behind login.** Guests pay too; `order_key` in the link is the credential.
 
-**Storefront wiring** (the only integration work):**Storefront wiring** (the only integration work):
+**Storefront wiring** (the only integration work):
 
 ```js
 const res = await inv("commerce/storefront-checkout", {
@@ -128,7 +128,7 @@ The order page's **Payment** panel shows the method, total, paid state and payme
 - **Create payment link** — the provider-hosted page for exactly that order's total; copy it to the customer.
 - **Check payment** — re-asks the provider and moves the order on if the money arrived.
 
-**The order's current payment method doesn't matter.** Asking for a link *is* the decision to collect online, and an admin-created order starts with no method at all, so `create-link` accepts any unpaid order and switches it onto the online gateway, recording the change in the order log (`Payment method set to Credit card (was Cash on delivery)…`). That switch matters beyond tidiness: refunds key off `payment_method`, so an order paid by card must say so or it can't be refunded through the provider. The panel warns before it happens.
+**The order's current payment method doesn't matter.** Asking for a link *is* the decision to collect online, and an admin-created order starts with no method at all, so `create-link` accepts any unpaid order and switches it onto the online gateway, recording the change in the order log (`Payment method set to Credit card (was Offline payment)…`). That switch matters beyond tidiness: refunds key off `payment_method`, so an order paid by card must say so or it can't be refunded through the provider. The panel warns before it happens.
 
 The one refusal is a store that has **turned online payment off** — `400 online_payments_disabled` — because that's the operator declining it, not a missing setup.
 
@@ -186,9 +186,9 @@ Rules for any checkout UI you build:
 - **Fetch, don't assume.** `commerce/storefront-catalog` → `get-store-info` returns `payment_gateways`, filtered to `enabled: true`, sorted by the admin's `order`, and with any online gateway **dropped while no provider is connected** — so what you render is always payable. Each entry is `{ slug, title, description, online }`.
 - **Use the admin's copy.** Show `title`/`description` as the customer-facing labels instead of your own strings, and key your logic off `slug` (`online: true` marks the one that redirects to a hosted page).
 - **Render the zero-state honestly.** An empty `payment_gateways` means checkout cannot complete; say so rather than showing a dead button.
-- **Let the server arbitrate.** Gateway `settings` are intentionally *not* exposed to the storefront, so the client cannot evaluate rules like `cod`'s `enable_for_methods` / `enable_for_virtual`. Send the chosen `slug` and treat `400 invalid_payment_method` from `place-order` as the authoritative answer.
+- **Let the server arbitrate.** Gateway `settings` are intentionally *not* exposed to the storefront, so the client cannot evaluate a gateway's own rules. Send the chosen `slug` and treat `400 invalid_payment_method` from `place-order` as the authoritative answer.
 - **Re-fetch rather than cache hard.** An admin can enable, disable or reorder gateways at any time; a long-lived cached list is how a storefront drifts out of sync with the store.
-- **Show `payment_instructions` from the response** for manual flows (`bacs`/`cheque`/`cod`) rather than hardcoding bank details in the UI.
+- **Show `payment_instructions` from the response** for the `offline` flow rather than hardcoding bank details in the UI.
 
 ## 8. Never hardcode payment availability
 

package/skills/commerce/references/product-render.md

@@ -5,7 +5,7 @@ What to show for a product, and **which view can show it**. Both storefront surf
 | View | Call | Returns |
 |---|---|---|
 | Listing / grid / search results / tag & category pages | `commerce/storefront-catalog` `list-products` | `{ products: [row...], page, per_page, has_next }` |
-| Product page | `commerce/storefront-catalog` `get-product` | `{ product, variations, categories, tags, reviews, upsells, cross_sells, grouped_products }` |
+| Product page | `commerce/storefront-catalog` `get-product` | `{ product, variations, categories, tags, reviews, upsells, cross_sells }` |
 
 Request/response shapes: [`../docs/api-storefront.md`](../docs/api-storefront.md). Variant selection mechanics (axes, resolving a selection to a variation, unavailable combinations): [`storefront-product-page.md`](./storefront-product-page.md).
 
@@ -19,48 +19,50 @@ A listing **row** is the product record itself (minus paywalled fields), plus re
 
 | Data | `list-products` row | `get-product` | Notes |
 |---|---|---|---|
-| `id`, `name`, `slug`, `type`, `status` | ✅ | ✅ | |
-| `price`, `regular_price`, `sale_price`, `on_sale` | ✅ | ✅ | For `variable`, the parent `price` is a starting point, not the truth — see §3 |
+| `id`, `name`, `slug`, `status` | ✅ | ✅ | There is no `type` field — a product sells variants when `attributes[]` is non-empty |
+| `price`, `regular_price`, `sale_price`, `on_sale` | ✅ | ✅ | With variants the parent `price` is a starting point, not the truth — see §3 |
 | `images[]`, `featured`, `short_description`, `description` | ✅ | ✅ | Cards normally use `images[0]` + `short_description`. `images` can be **empty** — render a placeholder, don't leave a broken `img` (on the product page `resolveSelection`'s `display.image` is `null` in that same case) |
 | `sku`, `stock_status`, `stock_quantity`, `manage_stock`, `backorders` | ✅ | ✅ | |
 | `average_rating`, `rating_count`, `total_sales` | ✅ | ✅ | Enough for stars on a card; the reviews themselves are not in a row |
-| `downloadable`, `virtual`, `weight`, `dimensions`, `attributes[]`, `meta_data` | ✅ | ✅ | `attributes[]` is the raw axes/spec array |
-| **`tags`** (resolved `{id, name, slug}`) | ✅ | ✅ | `get-product` returns the full tag records; rows carry the short form |
+| `downloadable`, `virtual`, `weight`, `dimensions`, `attributes[]`, `meta_data` | ✅ | ✅ | `attributes[]` is the variant axes; `meta_data` is the descriptive properties the admin calls **modifiers** |
+| **`tags`** (resolved `{id, name}`) | ✅ | ✅ | `get-product` returns the full tag records; rows carry the short form |
 | `tag_ids`, `category_ids` | ✅ | ✅ | Raw ids |
 | **`categories`** (resolved) | ❌ *ids only* | ✅ | See §5 to add |
-| **`variations[]`** (per-variation price/stock/image/attributes) | ❌ | ✅ | The reason a variable product can't be fully priced from a row |
+| **`variations[]`** (per-variant price/stock/image/attributes) | ❌ | ✅ | The reason a product with variants can't be fully priced from a row |
 | **`reviews`** (paged items + `average_rating`/`rating_count`) | ❌ | ✅ | Row still has the aggregate numbers |
 | **`upsells`, `cross_sells`** (summaries) | ❌ | ✅ | `{id, name, slug, price, on_sale, image}` |
-| **`grouped_products`** (children of a grouped product) | ❌ | ✅ | |
-| `downloads[]`, `download_limit`, `download_expiry`, `purchase_note` | ❌ | ❌ | **Never** exposed publicly — paywalled/post-purchase. Gated by `commerce/storefront-account` `get-download` |
+| `downloads[]`, `download_limit`, `download_expiry` | ❌ | ❌ | **Never** exposed publicly — paywalled. Gated by `commerce/storefront-account` `get-download` |
 
 ## 2. Tags — render them in **both** views
 
 Tags are a flat, cross-cutting axis ("gift", "summer", "vegan"); categories are the hierarchical spine. Generated storefronts routinely omit tags entirely. Don't.
 
-- **Listing rows carry resolved `tags`** (`{id, name, slug}`), so a card can render them with no extra call. One or two chips per card is useful ("New", "Bundle"); more is noise. Hide the block when the array is empty — never a dangling "Tags:" label.
-- **On the product page**, render `product.tags` (the top-level `tags` array, with `description` and `count` available) as chips near the metadata, visually lighter than the category breadcrumb.
-- **Every chip links to a filtered listing** — `list-products` with `tag_id` — never a dead label. Keep the tag in the URL (`/shop?tag=<slug>` or `/tag/<slug>`) so the page is shareable and survives reload; resolve slug → id with `list-tags`.
+- **Listing rows carry resolved `tags`** (`{id, name}`), so a card can render them with no extra call. One or two chips per card is useful ("New", "Bundle"); more is noise. Hide the block when the array is empty — never a dangling "Tags:" label.
+- **On the product page**, render `product.tags` (the top-level `tags` array) as chips near the metadata, visually lighter than the category breadcrumb.
+- **Every chip links to a filtered listing** — `list-products` with `tag_id` — never a dead label. A tag has no slug, so key the URL on its id (`/shop?tag=<tag_id>`) so the page is shareable and survives reload. Use `list-tags` for a name to label it with.
 - **Offer tags as a listing filter** from `list-tags`, which hides tags no published product carries and gives a `count` for labels like "Gift (12)". `tag_id` stacks with `category_id`, price, `on_sale`, `featured`, `in_stock_only`.
-- **Tag landing page:** `list-products` filtered by `tag_id`, with the tag's `name` as heading and `description` as intro copy when present.
+- **Tag landing page:** `list-products` filtered by `tag_id`, with the tag's `name` as the heading.
 - Don't put tags in the breadcrumb, and don't use them as variant options — a size or colour is an `attribute`, not a tag.
+- Descriptive properties (Material, Care) are **modifiers** in `meta_data`, not tags and not attributes. Render them as a spec table on the product page.
 
-## 3. Product types in each view
+## 3. Product shapes in each view
 
-| `product.type` | Card | Product page |
-|---|---|---|
-| `simple` | price, **Add to cart** straight from the card if you want one | single **Add to cart** — `resolveSelection` returns no axes, `complete: true`, a ready `addToCart` |
-| `variable` | price **range or `From €19`** (see below), never selectors — link through | one selector per attribute: [`storefront-product-page.md`](./storefront-product-page.md) |
-| `grouped` | link through, no cart action | not purchasable itself: render `grouped_products` as children with their own quantity inputs, each added as its own cart line |
-| `external` | link through | `product.button_text` linking to `product.external_url`; no cart interaction |
+There are only two shapes, and **`attributes[]` tells them apart** — there is no `type` field:
+
+| Shape | Test | Card | Product page |
+|---|---|---|---|
+| **Single item** | `attributes` is empty | price, **Add to cart** straight from the card if you want one | single **Add to cart** — `resolveSelection` returns no axes, `complete: true`, a ready `addToCart` |
+| **Has variants** | `attributes` is non-empty | price **range or `From €19`** (see below), never selectors — link through | one selector per attribute: [`storefront-product-page.md`](./storefront-product-page.md) |
+
+A product with attributes is **only** sellable through a variant: `add-item` without a `variation_id` is `400 variation_required`, and there is no fall-back to the parent. So one with attributes but no variations is unsellable by design, not by accident.
 
-Downloadable/virtual products are `simple`/`variable` with `downloadable: true` — see [`media-and-downloads.md`](./media-and-downloads.md).
+Downloadable/virtual products are either shape with `downloadable: true` — see [`media-and-downloads.md`](./media-and-downloads.md).
 
-### A variable product's parent `price` is not its price
+### A variant parent's `price` is its *from* price
 
-The backend rolls **stock** up from variations to the parent, but **not price** — a variable parent's `price` is only whatever was set on the parent record, often nothing. A row has no `variations`, so a card cannot compute the real range; show `From {product.price}` or a range, never the parent price presented as *the* price, and never `€0`.
+`admin-products` rolls both **stock** and **price** up from the variations: a parent's `regular_price`, `price` and `on_sale` are derived from the cheapest publishable variant on every save. So the parent price is real and safe to sort and filter on — but it is the **lowest** price, not *the* price.
 
-This is a **data** problem before it is a UI one: `list-products` sorts and filters on `product.price ?? 0`, so a variable product with no parent price **sorts as free and drops out of every price-range filter**. Fix it in the catalog — set the parent's `regular_price` to the lowest variation price (purchasing is unaffected: a variable line always prices from its variation). Then cards, sorting and filters all agree.
+A listing row has no `variations`, so a card still cannot compute the full range from a row alone: render `From {product.price}`, never the parent price presented as *the* price. On the product page you have `variations`, so show the real range via `priceRange` from the variant helpers.
 
 ## 4. Sensible defaults per view
 

package/skills/commerce/references/reviews.md

@@ -0,0 +1,20 @@
+# Reviews
+
+**Unless you are sure the store doesn't want reviews, implement them: the backend already exists.** Skipping them is the common miss, and it costs the store the social proof most shoppers look for before buying.
+
+What ships, with nothing to write on the backend:
+
+- `commerce/storefront-catalog` `get-product` returns **paginated `reviews`** plus `average_rating` and `rating_count`, and a `verified` flag per review;
+- `list-products` rows carry `average_rating`/`rating_count`, so **stars on cards cost no extra call**;
+- `commerce/storefront-catalog` `submit-review` accepts `{ product_id, reviewer?, review, rating }` from a **signed-in** customer — the email comes from the session, never the payload;
+- `commerce/storefront-account` `my-reviews` lists a customer's own;
+- moderation is already in the admin (Products → Reviews), and `commerce/admin-reviews` recalculates the product's rating on every status change.
+
+So the work is UI: stars on cards and the product page, a reviews list, and a submit form. Behaviors to respect rather than fight:
+
+- anonymous callers get **`401 login_required`** — put the form behind a login prompt instead of hiding reviews from guests;
+- a new review is **`hold`** unless `auto_approve_reviews`, so tell the submitter it's awaiting approval rather than showing it as live;
+- `only_verified_reviews` requires the customer to have a `processing`/`completed` order with that product (**`403 verified_only`**), and `review_rating_required` makes the rating mandatory (**`400 rating_required`**);
+- the store can switch reviews off store-wide (`products.enable_reviews`) — read it and hide the UI when false.
+
+Shapes and error codes: [`docs/api-storefront.md`](../docs/api-storefront.md#submit-review--auth). Where ratings belong per view: [`references/product-render.md`](./product-render.md).

package/skills/commerce/references/storefront-product-page.md

@@ -1,6 +1,6 @@
 # Variant selection on the product page
 
-The one interaction agents reliably get wrong: turning a variable product into controls a customer can buy from. Everything else about the page — what to show, and which fields each call returns — is [`product-render.md`](./product-render.md); request/response shapes are [`docs/api-storefront.md`](../docs/api-storefront.md).
+The one interaction agents reliably get wrong: turning a product with variants into controls a customer can buy from. Everything else about the page — what to show, and which fields each call returns — is [`product-render.md`](./product-render.md); request/response shapes are [`docs/api-storefront.md`](../docs/api-storefront.md).
 
 The logic ships: **`src/commerce/utils/variants.js`** (framework-free, no I/O, full JSDoc on every export — read it for signatures). Import it and spend your effort on the markup.
 
@@ -8,7 +8,7 @@ The logic ships: **`src/commerce/utils/variants.js`** (framework-free, no I/O, f
 
 ## 1. The model, and the rule
 
-`get-product` returns `{ product, variations }`. `product.attributes[]` entries with `variation: true` are the **axes**, in `position` order; each `variations[]` record is one combination. `visible: true` + `variation: false` attributes are descriptive — a spec table, **never** a selector.
+`get-product` returns `{ product, variations }`. **Every** `product.attributes[]` entry is an **axis**, in `position` order; each `variations[]` record is one combination. There is no product type and no per-attribute flag — carrying attributes is what makes a product sell variants. Descriptive properties are `meta_data` (the admin calls them modifiers) — a spec table, **never** a selector.
 
 **One control per axis. Never one option per variation.** Do not flatten `variations[]` into `Red / S`, `Red / M`, `Blue / S`, … — that is `n × m` noise, it hides the product's structure, and it stops scaling immediately.
 
@@ -43,16 +43,16 @@ Bind the UI to `view` — not to `product.*` — so a selection actually changes
 | `purchasable` | gate **Add to cart** on this (resolved *and* buyable) |
 | `addToCart` | `{ product_id, variation_id }` to spread into the cart call, or `null` |
 
-`view.variation` and `view.candidates` are there when you need the record itself or the variations still reachable. For a `simple` product `resolveSelection` returns no axes, `complete: true` and a ready `addToCart` — the same code path; it branches on `product.type`, so `variations` can be `[]`.
+`view.variation` and `view.candidates` are there when you need the record itself or the variations still reachable. For a product with no attributes `resolveSelection` returns no axes, `complete: true` and a ready `addToCart` — the same code path; it branches on whether there are axes, so `variations` can be `[]`.
 
-A **variable product with no usable variations** — `type: "variable"` but nothing in `variations[]`, the state an attribute record alone leaves you in — is deliberately *not* given a parent fallback, because `add-item` would reject it. You get axes whose `options` arrays are empty, `purchasable: false` and `addToCart: null`. Render it as unavailable rather than painting selector groups with no buttons, and guard the "Select a …" label: with no `variation: true` attributes at all, `missingAxes` is empty and `view.missingAxes[0]?.name` is `undefined`.
+A **product with attributes but no usable variations** — the state attaching an attribute and stopping leaves you in — is deliberately *not* given a parent fallback, because `add-item` would reject it. You get axes whose `options` arrays are empty, `purchasable: false` and `addToCart: null`. Render it as unavailable rather than painting selector groups with no buttons, and guard the "Select a …" label: with no attributes at all, `missingAxes` is empty and `view.missingAxes[0]?.name` is `undefined`.
 
 The other exports cover what the view model doesn't: `selectionForVariation` (variation → selection, to hydrate controls from a cart line or `?variation=` link), `selectionToParams`/`selectionFromParams` (URL round-trip), `priceRange`, and the individual pieces if you build your own view model. Signatures and edge cases are in the JSDoc; two behaviors are easy to miss when hand-rolling: non-publishable variations never leak an option into the UI, and an empty `option` on an axis means **"any"**.
 
 ## 3. The three UI decisions the helpers can't make for you
 
 - **Unavailable vs out of stock.** `"unavailable"` (no such combination) → **disable, don't hide**; options that vanish and reappear as the customer clicks are disorienting. `"out_of_stock"` → keep it visible and label it. `onbackorder` counts as available and purchasable — label it ("Ships in 2–3 weeks"), don't disable it.
-- **Incomplete selection.** Show `view.priceRange` (`$21.99 – $23.99`, or `From $21.99`) — never `$0`, and never the parent `price`, which for a variable product is not its price ([`product-render.md` §3](./product-render.md#3-product-types-in-each-view)). Keep **Add to cart** disabled with a hint at what's missing.
+- **Incomplete selection.** Show `view.priceRange` (`$21.99 – $23.99`, or `From $21.99`) — never `$0`, and never the parent `price`, which for a product with variants is not its price ([`product-render.md` §3](./product-render.md#3-product-shapes-in-each-view)). Keep **Add to cart** disabled with a hint at what's missing.
 - **Initial state and linkability.** Start from `defaultSelection` (honours the merchant's `default_attributes`, preselects single-option axes). Mirror the selection into the URL with `selectionToParams` and hydrate with `selectionFromParams`, so a chosen variant is shareable and survives a refresh.
 
 Route every click through `selectOption` and dead ends take care of themselves: it keeps the just-picked option and clears only conflicting axes (Red/L → click Blue → `{ Color: Blue }`, size re-open) instead of leaving the customer on a combination that resolves to nothing.
@@ -63,21 +63,21 @@ Route every click through `selectOption` and dead ends take care of themselves:
 await base44.functions.invoke("commerce/storefront-cart", {
   action: "add-item",
   cart_token,
-  ...view.addToCart,   // { product_id, variation_id } — variation_id is REQUIRED for type "variable"
+  ...view.addToCart,   // { product_id, variation_id } — variation_id is REQUIRED once a product has attributes
   quantity,
 });
 ```
 
-Handle `400 variation_required` (empty `variation_id` on a variable product — the page has a bug), the stock codes (`out_of_stock`, `insufficient_stock`, …), and `404 variation_not_found` (catalog changed underneath the page: refetch `get-product`). `product.sold_individually` caps the quantity control at 1.
+Handle `400 variation_required` (empty `variation_id` on a product with attributes — the page has a bug), the stock codes (`out_of_stock`, `insufficient_stock`, …), and `404 variation_not_found` (catalog changed underneath the page: refetch `get-product`). `product.sold_individually` caps the quantity control at 1.
 
 ## 5. Checklist
 
 - [ ] One control per axis in `view.axes` — no combination list anywhere in the UI.
-- [ ] Non-variation visible attributes render as specs, not selectors.
+- [ ] `meta_data` modifiers render as specs, not selectors.
 - [ ] Image, price, SKU and availability all come from `view.display`, with a placeholder for `display.image === null`.
 - [ ] Incomplete selection shows `view.priceRange` — never `$0`, never the parent `price`.
 - [ ] `"unavailable"` disabled, `"out_of_stock"` labelled; every click routed through `selectOption`.
 - [ ] Initial state from `defaultSelection`; selection mirrored into the URL.
 - [ ] **Add to cart** gated on `view.purchasable`, sending `view.addToCart`.
-- [ ] A variable product with empty `axes[].options` shows as unavailable — no empty selector groups, no "Select a undefined".
+- [ ] A product with empty `axes[].options` shows as unavailable — no empty selector groups, no "Select a undefined".
 - [ ] Tags, ratings, upsells and the rest per [`product-render.md`](./product-render.md).

package/skills/commerce/references/webhooks.md

@@ -1,6 +1,8 @@
 # Webhooks
 
-`webhooks.ts` `dispatch()` fires on `order.*`, `product.*`, `customer.*`, `coupon.*` (created/updated/deleted, plus order/product `restored`). Each active `commerce.Webhook` matching the topic receives an HTTP POST with headers `X-Commerce-Webhook-Topic/-Resource/-Event/-ID/-Delivery-ID/-Signature`. The signature is **base64 HMAC-SHA256** of the body, keyed by the webhook's `secret` (Web Crypto).
+Managed in the admin at **Settings → Webhooks** (`settings/webhooks`; the source still lives under `pages/status/`).
+
+`webhooks.ts` `dispatch()` fires on `order.*`, `product.*`, `customer.*`, `coupon.*` (created/updated/deleted, note that `restored` is selectable on a webhook but **never emitted** — nothing dispatches it). Each active `commerce.Webhook` matching the topic receives an HTTP POST with headers `X-Commerce-Webhook-Topic/-Resource/-Event/-ID/-Delivery-ID/-Signature`. The signature is **base64 HMAC-SHA256** of the body, keyed by the webhook's `secret` (Web Crypto).
 
 - Every attempt is logged as a `commerce.WebhookDelivery` (request/response bodies truncated to 32 KB). Prune with `commerce/admin-tools` `prune-webhook-deliveries`.
 - `failure_count` increments on non-2xx/timeout and resets on success; a webhook auto-disables after **5** consecutive failures.

package/src/commerce/admin/README.md

@@ -1,4 +1,4 @@
-# Store Admin (`src/commerce/admin/`)
+# Store Management (`src/commerce/admin/`)
 
 React admin UI for the Base44 commerce template. Copy this
 folder into a Base44 app built on the default template (Vite + React +
@@ -27,14 +27,14 @@ Tailwind + shadcn/ui + React Router) to get a full store back office.
    ```jsx
    import AdminApp from "@/commerce/admin";
 
-   <Route path="/admin/*" element={<AdminApp />} />
+   <Route path="/store-admin/*" element={<AdminApp />} />
    // mounted elsewhere? → <AdminApp basePath="/backoffice" />
    ```
 
 5. Make sure your user has the **admin role** (Base44 dashboard → Users, or
    `base44.users.inviteUser(email, "admin")`). Signed-in users without the
    admin role get an access-denied screen — do not weaken this check.
-6. Open `/admin`. If the store has never been seeded (no `general` StoreSettings
+6. Open `/store-admin`. If the store has never been seeded (no `general` StoreSettings
    group) the first-run screen appears and seeds store defaults, optionally with
    sample data when the store has no products yet. If `commerce/seed-store` was
    already run during installation — including when an agent generated a real
@@ -61,7 +61,7 @@ backend functions directly as its tools.
 
 alert, alert-dialog, badge, button, calendar, card, checkbox, command, dialog,
 dropdown-menu, input, label, popover, radio-group, scroll-area, select,
-separator, sheet, skeleton, switch, table, tabs, textarea, tooltip
+separator, sheet, skeleton, switch, table, tabs, textarea
 
 The default Base44 template ships all of these. If one is missing:
 

package/src/commerce/admin/context/BasePathContext.jsx

@@ -2,15 +2,15 @@ import React, { createContext, useContext } from "react";
 import { normalizeBasePath } from "../lib/paths";
 
 /**
- * The URL prefix the admin app is mounted under (default `/admin`).
+ * The URL prefix the admin app is mounted under (default `/store-admin`).
  * All internal links are built from this, so the admin folder works no matter
  * where the consumer mounts it: `<AdminApp basePath="/backoffice" />`.
  */
-const BasePathContext = createContext("/admin");
+const BasePathContext = createContext("/store-admin");
 
-export function BasePathProvider({ value = "/admin", children }) {
+export function BasePathProvider({ value = "/store-admin", children }) {
   // normalizeBasePath also tolerates the route *pattern* being passed in
-  // (`basePath="/admin/*"`), an easy copy/paste slip from the mount — every
+  // (`basePath="/store-admin/*"`), an easy copy/paste slip from the mount — every
   // internal link would otherwise carry a literal "*" segment.
   return <BasePathContext.Provider value={normalizeBasePath(value)}>{children}</BasePathContext.Provider>;
 }
@@ -19,7 +19,7 @@ export function useBasePath() {
   return useContext(BasePathContext);
 }
 
-/** Returns a builder: href("orders/123") → "/admin/orders/123"; href() → "/admin". */
+/** Returns a builder: href("orders/123") → "/store-admin/orders/123"; href() → "/store-admin". */
 export function useAdminHref() {
   const base = useBasePath();
   return (path = "") => (path ? `${base}/${String(path).replace(/^\/+/, "")}` : base);

package/src/commerce/admin/context/SettingsContext.jsx

@@ -155,8 +155,8 @@ function SetupScreen({ onDone }) {
               onChange={(e) => setStoreName(e.target.value)}
             />
             <p className="text-xs text-muted-foreground">
-              Shown to customers and used as the sender name on every transactional email.
-              Editable later in Settings → General.
+              Used in the subject and as the sender name on every transactional email.
+              Editable later in Settings → Emails.
             </p>
           </div>
           {hasProducts === false && (
@@ -171,8 +171,8 @@ function SetupScreen({ onDone }) {
                   Include sample data
                 </Label>
                 <p className="text-xs text-muted-foreground">
-                  Adds demo categories, products (simple, variable, downloadable,
-                  external, grouped) and coupons so you can explore the admin.
+                  Adds demo categories, 10 products (three with size/colour variants, one
+                  downloadable) and coupons so you can explore the admin.
                 </p>
               </div>
             </div>

package/src/commerce/admin/index.jsx

@@ -10,15 +10,15 @@ import { BasePathProvider } from "./context/BasePathContext";
  * The store admin application.
  *
  * Mount inside your app's router:
- *   <Route path="/admin/*" element={<AdminApp />} />
+ *   <Route path="/store-admin/*" element={<AdminApp />} />
  *
- * If mounted somewhere other than /admin, pass the prefix:
+ * If mounted somewhere other than /store-admin, pass the prefix:
  *   <Route path="/backoffice/*" element={<AdminApp basePath="/backoffice" />} />
  *
  * Requires an authenticated user with role "admin" (enforced by AuthGuard,
  * and independently by entity RLS + requireAdmin() in backend functions).
  */
-export default function AdminApp({ basePath = "/admin" }) {
+export default function AdminApp({ basePath = "/store-admin" }) {
   return (
     <BasePathProvider value={basePath}>
       <Toaster richColors position="top-right" />

package/src/commerce/admin/layout/Sidebar.jsx

@@ -10,7 +10,6 @@ import {
   ShoppingCart,
   Sparkles,
   Users,
-  Webhook,
 } from "lucide-react";
 import { call } from "../lib/api";
 import { useAdminHref } from "../context/BasePathContext";
@@ -30,8 +29,6 @@ const NAV = [
     items: [
       { label: "All Products", path: "products", end: true },
       { label: "Categories", path: "products/categories" },
-      { label: "Tags", path: "products/tags" },
-      { label: "Attributes", path: "products/attributes" },
       { label: "Reviews", path: "products/reviews" },
     ],
   },
@@ -43,11 +40,6 @@ const NAV = [
   {
     items: [{ label: "Settings", path: "settings", icon: Settings }],
   },
-  {
-    title: "Status",
-    icon: Webhook,
-    items: [{ label: "Webhooks", path: "webhooks" }],
-  },
 ];
 
 /** Left navigation. `onNavigate` closes the mobile sheet; `onOpenBot` opens the StoreAdmin bot panel. */
@@ -78,7 +70,7 @@ export default function Sidebar({ onNavigate, onOpenBot }) {
     <div className="flex h-full flex-col">
       <div className="flex h-14 items-center gap-2 border-b px-4">
         <Package className="h-5 w-5 text-primary" />
-        <span className="font-semibold">Store Admin</span>
+        <span className="font-semibold">Store Management</span>
       </div>
       <nav className="flex-1 space-y-4 overflow-y-auto p-3">
         {NAV.map((group, gi) => (

package/src/commerce/admin/lib/constants.js

@@ -17,13 +17,6 @@ export const PRODUCT_STATUSES = [
   { value: "publish", label: "Published", color: "bg-green-100 text-green-800 border-green-200" },
 ];
 
-export const PRODUCT_TYPES = [
-  { value: "simple", label: "Simple product" },
-  { value: "grouped", label: "Grouped product" },
-  { value: "external", label: "External/Affiliate product" },
-  { value: "variable", label: "Variable product" },
-];
-
 export const CATALOG_VISIBILITIES = [
   { value: "visible", label: "Shop and search results" },
   { value: "catalog", label: "Shop only" },

package/src/commerce/admin/lib/paths.js

@@ -1,16 +1,16 @@
 /**
  * Mount-path handling for the admin app.
  *
- * The admin is mounted with a splat route — `<Route path="/admin/*">` — and both
+ * The admin is mounted with a splat route — `<Route path="/store-admin/*">` — and both
  * halves of that pattern leak into places they shouldn't: the `basePath` prop
- * gets the pattern pasted in verbatim, and the literal URL `/admin/*` gets
+ * gets the pattern pasted in verbatim, and the literal URL `/store-admin/*` gets
  * opened (pattern copied into the address bar, or a nav link built from the
  * route table). Neither is a real page, so both are normalized here rather than
  * dead-ending the admin.
  */
 
-/** Strip a trailing route splat and slashes: "/admin/*" → "/admin". */
-export function normalizeBasePath(value, fallback = "/admin") {
+/** Strip a trailing route splat and slashes: "/store-admin/*" → "/store-admin". */
+export function normalizeBasePath(value, fallback = "/store-admin") {
   const clean = String(value ?? "")
     .replace(/\/+\*+$/, "")
     .replace(/\/+$/, "");
@@ -21,8 +21,8 @@ export function normalizeBasePath(value, fallback = "/admin") {
  * Is this leftover path (the `*` param of the catch-all route) nothing but
  * route-*pattern* segments — `*`, its percent-encoded form, or `:param`?
  *
- * `/admin/*` → true (send them to the dashboard)
- * `/admin/ordrs` → false (a genuine 404)
+ * `/store-admin/*` → true (send them to the dashboard)
+ * `/store-admin/ordrs` → false (a genuine 404)
  */
 export function isMountPatternPath(rest) {
   const segments = String(rest ?? "")

package/src/commerce/admin/lib/product-utils.js

@@ -9,20 +9,20 @@ export function slugify(name) {
     .replace(/^-+|-+$/g, "");
 }
 
-export const isSimple = (p) => p?.type === "simple";
-export const isGrouped = (p) => p?.type === "grouped";
-export const isExternal = (p) => p?.type === "external";
-export const isVariable = (p) => p?.type === "variable";
+/**
+ * A product sells variants because it carries attributes — every entry in
+ * `attributes[]` is a variant axis, so attaching one is the whole declaration.
+ * Descriptive properties are `meta_data` (modifiers), not attributes.
+ */
+export const isVariable = (p) => (p?.attributes ?? []).length > 0;
 
 /**
- * Cartesian product of all attributes flagged `variation: true`.
+ * Cartesian product of every attribute that has options.
  * Returns [{attributes: [{attribute_id, name, option}]}] — one entry per combo.
- * Returns [] when no variation attributes with options exist.
+ * Returns [] when no attribute has options yet.
  */
 export function generateVariationCombos(attributes) {
-  const varAttrs = (attributes || []).filter(
-    (a) => a.variation && (a.options || []).length > 0
-  );
+  const varAttrs = (attributes || []).filter((a) => (a.options || []).length > 0);
   if (!varAttrs.length) return [];
   const combos = varAttrs.reduce(
     (acc, attr) =>
@@ -44,12 +44,15 @@ export function variationLabel(variation) {
     .join(" / ") || "Any";
 }
 
+/** Order-independent identity of a variation's attribute combination. */
+export function comboKey(variation) {
+  return (variation?.attributes || [])
+    .map((x) => `${(x.name || "").toLowerCase()}=${(x.option || "").toLowerCase()}`)
+    .sort()
+    .join("|");
+}
+
 /** True when two variations have the same attribute combo. */
 export function sameCombo(a, b) {
-  const key = (v) =>
-    (v?.attributes || [])
-      .map((x) => `${(x.name || "").toLowerCase()}=${(x.option || "").toLowerCase()}`)
-      .sort()
-      .join("|");
-  return key(a) === key(b);
+  return comboKey(a) === comboKey(b);
 }

package/src/commerce/admin/pages/orders/components/AddProductDialog.jsx

@@ -20,11 +20,11 @@ import { Loader2 } from "lucide-react";
 
 import { call, base44 } from "../../../lib/api";
 import SearchSelect from "../../../components/SearchSelect";
-import { variationLabel } from "../../../lib/product-utils";
+import { isVariable, variationLabel } from "../../../lib/product-utils";
 
 /**
  * Two-step product picker for the order editor:
- * product search → (variable only) variation select → quantity.
+ * product search → (products with variants only) variant select → quantity.
  *
  * Props: { open, onOpenChange, onAdd({product, variation|null, quantity}) }
  */
@@ -50,7 +50,7 @@ export default function AddProductDialog({ open, onOpenChange, onAdd }) {
     return rows.map((p) => ({
       value: p.id,
       label: p.name,
-      meta: [p.sku && `SKU: ${p.sku}`, p.type].filter(Boolean).join(" · "),
+      meta: p.sku ? `SKU: ${p.sku}` : undefined,
       product: p,
     }));
   };
@@ -59,7 +59,7 @@ export default function AddProductDialog({ open, onOpenChange, onAdd }) {
     setPicked(opt);
     setVariations(null);
     setVariationId("");
-    if (opt?.product?.type === "variable") {
+    if (isVariable(opt?.product)) {
       setLoadingVariations(true);
       try {
         const rows = await base44.entities["commerce.ProductVariation"].filter({ product_id: opt.value }, "menu_order", 200);
@@ -70,11 +70,11 @@ export default function AddProductDialog({ open, onOpenChange, onAdd }) {
     }
   };
 
-  const isVariable = picked?.product?.type === "variable";
-  const canAdd = picked && quantity > 0 && (!isVariable || variationId);
+  const hasVariants = isVariable(picked?.product);
+  const canAdd = picked && quantity > 0 && (!hasVariants || variationId);
 
   const submit = () => {
-    const variation = isVariable ? (variations || []).find((v) => v.id === variationId) : null;
+    const variation = hasVariants ? (variations || []).find((v) => v.id === variationId) : null;
     onAdd({ product: picked.product, variation, quantity });
     onOpenChange(false);
   };
@@ -97,7 +97,7 @@ export default function AddProductDialog({ open, onOpenChange, onAdd }) {
             />
           </div>
 
-          {isVariable && (
+          {hasVariants && (
             <div className="grid gap-1.5">
               <Label>Variation</Label>
               {loadingVariations ? (