@base44/app-plugin-commerce 0.1.5 → 0.1.7

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

@@ -1,201 +1,34 @@
-# Online payments
+# Online (card) payments
 
-**Card payments are implemented and shipped.** Hosted payment page, payment links for existing orders, two confirmation paths, and refunds through the provider — all wired to **Stripe** out of the box. There is **no charge flow to write**: the store starts taking card payments as soon as a payment provider is connected.
+The store ships with a **Credit card** checkout option (`commerce.PaymentGateway` slug `card`) and everything around it already built — order creation, totals, stock holds, the two idempotent confirmation paths (customer return + provider webhook), payment links for unpaid orders, refund records, emails, and the admin's payment panel.
 
-- `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` · `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.
+What it does **not** ship with is a payment provider. Wiring one (Stripe, PayPal, Adyen, a local PSP…) means implementing **exactly two files** — nothing else changes, no entity is touched, no caller or UI needs editing:
 
----
+| # | File | Implement |
+|---|------|-----------|
+| 1 | `base44/shared/commerce/card-payment.ts` | `createCardPayment` (make a hosted payment page for `order.total`, return `{url, reference}`), `checkCardPaymentPaid` (ask the provider whether `reference` was paid), and optionally `refundCardPayment` |
+| 2 | `base44/functions/commerce/payment-webhook/entry.ts` | `parseWebhook` (verify the provider's signature over the raw body, return `{order_id, order_key, paid, reference?}`) |
 
-## 1. What to do when building a store (strong recommendation, not a rule)
+Until file 1 is implemented, picking Credit card at checkout answers `503 no_card_payment_provider` (the storefront should offer the other methods); the admin can also just switch the card option off in Settings → Payments to hide it. Every other payment option is **manual**: the order goes on-hold with the option's description as payment instructions, and the operator moves it on once the money arrives — those need no code at all, and the admin can add more of them in Settings → Payments.
 
-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.**
+## How the premade flow works
 
-**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.
+1. **Checkout** (`commerce/storefront-checkout` `place-order` with the `card` gateway): the order is created `pending`, `createCardPayment(sr, order, {successUrl, cancelUrl, customerEmail})` is called, the returned `reference` is stored on the order (`_payment_reference` meta), and the customer is redirected to `url`. The return URLs already carry `order_id`, `order_key` and `payment=success|cancel`.
+2. **Confirmation — two idempotent paths**, whichever runs second is a no-op:
+   - **Customer return**: the `/order-received` page calls `commerce/payments` `complete-return`, which runs `checkCardPaymentPaid(sr, order, reference)` and, when true, moves the order to `processing` (stock/email/webhook side-effects fire from the transition).
+   - **Webhook**: register `commerce/payment-webhook`'s URL with the provider. Your `parseWebhook` verifies the signature and names the order; `paid: true` from a **verified** event is trusted directly, `paid: false` makes the premade code re-check via `checkCardPaymentPaid`. The event's `order_key` must match the order — attach `order.id` and `order.order_key` to the payment's metadata in `createCardPayment` so the event can carry them back.
+3. **Payment links**: `commerce/payments` `create-link` mints a fresh page for any unpaid order via the same `createCardPayment` — used by the admin's payment-link button and the order-received page's "Pay now".
+4. **Refunds**: `commerce/admin-refunds` with `refund_payment: true` calls `refundCardPayment` **before** writing the local record (a failed provider refund writes nothing). While unimplemented it answers `501 card_refund_not_implemented` — record the refund without `refund_payment` and return the money from the provider's own dashboard.
 
-When you get there, make it easy:
+## Implementation rules
 
-> *"Your store is set up. The last piece is taking money: card payments are already implemented, they just need Stripe connected for this app — that part is yours to do in the dashboard, and then I can place a test order end to end. Want to do that now, or start with manual payments (bank transfer / cash on delivery) for the moment?"*
+- **Credentials** come from backend secrets/env (`Deno.env.get(...)`) — never from an entity, never from the client. On Base44, env vars are injected at deploy time; after adding a secret, redeploy the backend functions so they can see it.
+- **Only the provider can say an order is paid.** `checkCardPaymentPaid` must ask the provider's API about the stored `reference`; never return true because a request claimed it. In `parseWebhook`, set `paid: true` only after verifying the request signature over the raw body bytes.
+- **Amounts**: `order.total` is in display units (e.g. `12.34`) with `order.currency`; convert to the provider's minor units yourself if it needs them.
+- The shared helpers in `base44/shared/commerce/payments.ts` (return-URL building, `confirmCardPayment`, reference bookkeeping) are premade — don't duplicate or bypass them.
 
-Then:
+## Storefront requirements (unchanged by any of this)
 
-1. **Ask the user to set Stripe up for the app.** On **Base44** that's the platform's own Stripe integration (app dashboard → Integrations → Stripe; it can start in Stripe's test mode and be claimed with a real account later) — *not* an OAuth connector: there is no Stripe connector in Base44's catalog. The platform holds the keys and injects them into backend functions as **`STRIPE_SECRET_KEY`** / **`STRIPE_PUBLISHABLE_KEY`**, which is exactly where `stripe.ts` reads the credential from. Never put keys in the store's data, in code, or in a settings field.
-2. **Redeploy the backend functions — connecting is not enough.** The platform injects `STRIPE_SECRET_KEY` **at deploy time**, so functions that were already deployed keep the environment they started with and cannot see a key added afterwards. `stripe.ts` reads `Deno.env.get("STRIPE_SECRET_KEY")`, so until the functions are redeployed the store reports *no payment provider connected* even though Stripe is set up correctly. This is the single most common "it doesn't work" after connecting.
-
-   - **Hosted app (no CLI)** — you cannot run a deploy command, so cause one by **changing a file the functions bundle**: edit anything under `base44/shared/commerce/` and every `commerce/*` function redeploys, because `shared/` is bundled into all of them. A one-line comment edit is enough — `shared/commerce/payments.ts` carries a **deploy marker** comment at the top for exactly this: bump its number, save, and the whole set redeploys. (Editing a single function's `entry.ts` redeploys only that function, which is not enough: `payments`, `payment-webhook`, `storefront-checkout`, `storefront-catalog`, `admin-tools` and `admin-refunds` all read the credential.)
-   - **CLI** — `npx base44 functions deploy`.
-
-3. **Then confirm it landed** — `commerce/admin-tools` → `payment-connector-status` returns `{ connected, provider, gateway_slug }`; the admin's Payments screen shows the same state. Still *not connected*? In order: was the integration actually completed in the dashboard, did the redeploy above really happen, and has the ~60s status cache expired (`onlinePaymentStatus` caches per isolate).
-4. **Nothing else.** The `Credit card` gateway is enabled by default and starts appearing at checkout the moment a provider is connected. No code, no keys, no placeholder to replace. (`commerce/seed-store` is idempotent and never rewrites an existing gateway, so a store seeded *before* this default landed keeps its old `enabled: false` — switch it on in Payments settings.)
-5. **Optional but recommended: register the webhook** (§4) so payments confirm even when the buyer closes the tab.
-6. **Test with the provider's test mode** — place an order, pay, and check the order reaches `processing` with `date_paid` and a payment reference; then try a refund. This is the other reason to do payments *after* the catalog: with products, a shipping method and an address in place, you can prove the whole path works instead of just wiring it.
-
-**To stop taking card payments, switch the gateway off** — don't rely on disconnecting the provider in the platform dashboard. Verified on Base44: after disconnecting Stripe there, the injected `STRIPE_SECRET_KEY` was still present *and still accepted by Stripe* (across a redeploy), so the store could genuinely still charge and correctly reported card payment as available. The store-level switch in **Payments settings** is the control that always works, because it's the store's own data.
-
-**The user can decline, and that's a legitimate answer.** Some businesses genuinely want invoice, bank transfer or cash on delivery only. If they do:
-
-- turn the `Credit card` gateway **off** in Payments settings — that is the whole opt-out;
-- the storefront never offers it, and the admin order page's payment actions sit disabled with *"No payment provider connected"*;
-- say plainly in the checkout UI how payment works (`payment_instructions` from the `place-order` response), and don't describe the store as taking cards anywhere in the copy.
-
-Don't leave the in-between state unexplained: the gateway enabled with **no provider connected** is safe (customers never see it — the storefront filters it out live), but the user should know it's waiting on them.
-
-## 2. How it works
-
-```
-place-order (gateway = card)
-  └─ order created `pending`  →  payment: { status: "requires_payment", checkout_url }
-       └─ storefront redirects the customer to checkout_url  (provider-hosted page)
-            ├─ customer returns → commerce/payments `verify`      ─┐  both idempotent,
-            └─ provider calls  → commerce/payment-webhook          ─┘  first one wins
-                 └─ order → `processing`, date_paid set, reference stored, emails + webhooks fire
-```
-
-Card data never touches this app — the customer pays on the provider's page.
-
-**Return URLs — and the route your page actually lives at.** Providers require *absolute* URLs. Resolution, most specific first:
-
-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 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 resolve to the app's own origin plus the store's configured path.
-
-### MANDATORY: the payment return page (`/order-received`)
-
-**Payment links do not work until you build this page.** Every link comes back to it — checkout, the admin's *Create payment link*, any "pay now" in an email — so without the route a customer pays and lands on a **404**, at the worst possible moment. And because confirming the payment is what moves the order to `processing`, a missing page also means **paid orders sit unpaid forever**.
-
-The template ships **no storefront UI**, so the page is yours to build. **If you don't call it `/order-received`, set your route in Settings → General → *Payment return path*** (`settings.general.order_received_path`) — that's what payment links are built from, and a mismatch is a 404 for a paying customer. All the logic is one backend call:
-
-```js
-// GET /order-received?order_id=…&order_key=…&payment=success|cancel
-const params = new URLSearchParams(window.location.search);
-const res = await base44.functions.invoke("commerce/payments", {
-  action: "complete-return",
-  order_id: params.get("order_id"),
-  order_key: params.get("order_key"),
-  payment: params.get("payment"),        // only a hint — the server decides
-  return_url: window.location.origin,    // so "pay again" can come back here
-});
-const { state, order, payment_link } = res.data.data;
-```
-
-`complete-return` confirms with the provider, progresses the order when the money landed, and answers with everything the page needs:
-
-| Field | Meaning |
-|---|---|
-| `state` | **`paid`** → thank the customer, show the order · **`cancelled`** → they backed out, order saved and unpaid · **`unpaid`** → no payment recorded yet (closed the tab, slow bank, gave up) |
-| `paid`, `already_confirmed`, `status` | the confirmed payment state and the order's new status |
-| `order` | customer-safe order (order number, totals, status) to render |
-| `payment_link` | `{ url, session_id }` while unpaid — wire it to a **Pay now** button; `null` when the store can't take card payment |
-
-Rules for whatever you build:
-
-- **Call `complete-return` on every visit.** It is idempotent, so refreshes and double-taps are safe, and it is what marks the order paid.
-- **Never treat the URL as proof.** `?payment=success` is editable by anyone; `state` comes from the provider, and a hand-edited URL can never produce `paid`.
-- **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):
-
-```js
-const res = await inv("commerce/storefront-checkout", {
-  action: "place-order", cart_token, payment_method: "stripe", billing, shipping,
-  success_url: `${origin}/order-received?order_id=…&order_key=…`,   // optional; a sensible default is used
-  cancel_url: `${origin}/checkout`,
-});
-if (res.payment?.status === "requires_payment") window.location.href = res.payment.checkout_url;
-
-// …and on the success page, confirm before showing "paid":
-const { paid, status } = await inv("commerce/payments", { action: "verify", order_id, order_key });
-```
-
-Never mark an order paid from a URL parameter — `verify` asks the provider and is the only honest answer. It is safe to call repeatedly.
-
-**Resuming a payment**: `commerce/payments` `create-link` returns a fresh hosted-page URL for any unpaid order (`{ order_id, order_key }` for a customer, or admin auth). That's what powers "pay now" links in the admin and in order-received emails.
-
-**Re-issuing after an edit is safe.** Each session is created with an idempotency key derived from the request itself, so an unchanged request (a double-click, a retry) reuses its session while an edited order gets a new one — keying on the order's total alone would break here, since editing an order without moving the total changes the request but not the key. And the previous session is **expired** before the new one is minted, so an old link can't be paid at the total the order used to have.
-
-## 3. Payment links from the admin
-
-The order page's **Payment** panel shows the method, total, paid state and payment reference, and for **any unpaid order** — with a provider connected — offers:
-
-- **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 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.
-
-Both actions are disabled with *"No payment provider connected"* when there's no provider — the capability stays visible so the operator can see what connecting unlocks.
-
-## 4. The webhook (recommended)
-
-`commerce/payment-webhook` is the second confirmation path: it catches buyers who pay and close the tab before returning.
-
-1. Register the function's URL with the provider (Stripe: *Developers → Webhooks*, events `checkout.session.completed` and `payment_intent.succeeded`).
-2. Put the signing secret in the **`PAYMENT_WEBHOOK_SECRET`** environment variable (`STRIPE_WEBHOOK_SECRET` also works).
-3. **On the hosted Base44 platform, also configure the app's Stripe webhook secret in the app settings.** Verified behavior: a request carrying a `stripe-signature` header is gated by the platform *before* any function runs — without that app-level secret every Stripe webhook is answered `400 "No Stripe webhook secret configured for this app"` and never reaches `commerce/payment-webhook`. Use the same secret in both places.
-
-**The payload is never believed on its own**, which is what makes this safe with or without a secret:
-
-- **With a signing secret**, the signature is verified here (provider scheme, timestamp tolerance so a captured request can't be replayed) and the event's "paid" is then trusted — one fewer round trip.
-- **Without one** — the case on Base44, where a function's environment is fixed (`BASE44_APP_ID`, `STRIPE_PUBLISHABLE_KEY`, `STRIPE_SECRET_KEY`) and apps can't add their own — the body counts only as *a nudge naming an order*. Whether money arrived is then asked of the provider over our own authenticated API call. A forged webhook achieves nothing beyond making the store re-check an order; it can never mark one paid.
-
-Either way the event must carry the `order_key` matching the order it names, and any session id in it is fetched and checked to have been opened for *that* order (the provider's own copy of `order_id`/`order_key`, put there at session creation). So a genuine payment for one order can never be replayed against another — a €5 order settled for real does not confirm a €500 one. A mismatch answers `409 session_order_mismatch` (and is ignored, with a 200, on the webhook so the provider stops retrying).
-
-So the webhook is worth registering either way. It remains a **resilience upgrade, not a prerequisite**: the return page confirms payments on its own.
-
-## 5. Refunds
-
-`commerce/admin-refunds` `create` with `refund_payment: true` sends the money back through the provider, then records the refund — **in that order**, so a failed provider refund never leaves a phantom refund behind. The response carries `gateway_refund: { provider, id, status, amount }` and the refund record's `refunded_payment` is true only when the provider really refunded. An order that wasn't paid online rejects `refund_payment` with `400 no_online_payment`: that money moved outside the store and has to go back the same way.
-
-The admin's refund panel offers *"Send the money back through the payment provider"* only when the order was actually paid online and a provider is connected.
-
-## 6. Using a different provider
-
-The payment utility exists for this. **Write an adapter and change one line:**
-
-```ts
-// base44/shared/commerce/payments.ts
-const paypalAdapter: PaymentAdapter = { id: "paypal", label: "PayPal", gatewaySlug: "paypal", /* … */ };
-export const ACTIVE_PROVIDER: PaymentAdapter = paypalAdapter;   // ← was stripeAdapter
-```
-
-`PaymentAdapter` is the whole contract: `connection`, `createSession`, `retrieveSession`, `refund`, `verifyWebhook`, `parseWebhookEvent`. Implement those against the provider's API (model `stripe.ts`, which is the reference implementation — including how it finds its credential: an injected secret first, a host connector second) and **nothing else changes** — checkout, the payment/webhook functions, refunds, the admin panel and the storefront gateway filter all go through the utility.
-
-Then check the remaining touchpoints, all of them data or copy rather than logic:
-
-- **The gateway record** (`commerce.PaymentGateway`, slug `stripe` by default): either keep the slug and just change `title`/`method_title`, or create a record whose slug matches your adapter's `gatewaySlug` and disable the old one. `ACTIVE_PROVIDER.gatewaySlug` is what makes a gateway "the online one".
-- **`grep -rn "stripe" base44/ src/`** — after swapping the binding, every remaining hit should be the adapter, the seeded gateway record, or the `stripe-signature` header fallback in the webhook. If it's anywhere else, that's a leak worth fixing.
-- **The webhook secret** env var stays `PAYMENT_WEBHOOK_SECRET`, and your `verifyWebhook` decides how to check it.
-
-Keeping several providers live at once (card *and* PayPal, say) means going beyond a single `ACTIVE_PROVIDER`: give each its own gateway slug and resolve the adapter per order's `payment_method`. The utility is the place to add that map — callers won't need to change.
-
-## 7. The storefront must render payment options from settings — never a hardcoded list
-
-The available payment methods are **data**, owned by the admin (Payments settings → `commerce.PaymentGateway`). A storefront that hardcodes "Card / Bank transfer / COD" will silently disagree with the store the moment an admin toggles a gateway, reorders them, or edits a title.
-
-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 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 the `offline` flow rather than hardcoding bank details in the UI.
-
-## 8. Never hardcode payment availability
-
-Whether the store can take a card is a **live fact about the connector**, not a constant. Everything derives it:
-
-- backend — `onlinePaymentStatus(sr)` from the payment utility. It doesn't just look for a key, it **verifies** it with the provider (cheapest authenticated call, answer cached ~60s): a credential that has been disconnected, rotated or revoked lingers in a function's environment until the next deploy, so presence alone would advertise card payment the store can no longer take. The same deploy-time injection is why a *newly* connected provider stays invisible until the functions are redeployed (§2, step 2). Expect up to a minute for a change to show. A *rejected* credential means not connected; a network blip does **not** flip a working store to "no payments" while a good answer is still cached;
-- admin — the `usePaymentProvider()` hook (`commerce/admin-tools` → `payment-connector-status`);
-- storefront — the filtered `payment_gateways` list.
-
-So do **not** ship a permanent "payments not set up" banner: it disappears by itself the moment a provider is connected. And never surface a provider name in a failure state — *"No payment provider connected"* is what an operator needs to read.
+- Redirect to `payment.checkout_url` when `place-order` returns `payment.status === "requires_payment"`.
+- **Build the `/order-received` page** (or set your route in Settings → General → *Payment return path*): call `commerce/payments` `complete-return` with the return query params and render its `state` (`paid | cancelled | unpaid`, with `payment_link` for "Pay now" while unpaid). Without this page a paying customer lands on a 404 and the order is never marked paid.
+- Handle `503 no_card_payment_provider` from `place-order` by telling the customer card payment is unavailable and offering the other methods.

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

@@ -4,8 +4,8 @@ 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 }` |
+| Listing / grid / search results / ribbon & category pages | `commerce/storefront-catalog` `list-products` | `{ products: [row...], page, per_page, has_next }` |
+| Product page | `commerce/storefront-catalog` `get-product` | `{ product, variations, categories, ribbons, 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).
 
@@ -15,7 +15,7 @@ You choose what belongs in each view — but you can only render what the call r
 
 ## 1. Field availability
 
-A listing **row** is the product record itself (minus paywalled fields), plus resolved `tags`. `get-product` adds everything that needs a second read.
+A listing **row** is the product record itself (minus paywalled fields), plus resolved `ribbons`. `get-product` adds everything that needs a second read.
 
 | Data | `list-products` row | `get-product` | Notes |
 |---|---|---|---|
@@ -25,25 +25,25 @@ A listing **row** is the product record itself (minus paywalled fields), plus re
 | `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 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 |
+| **`ribbons`** (resolved `{id, name}`) | ✅ | ✅ | `get-product` returns the full ribbon records; rows carry the short form |
+| `ribbon_ids`, `category_ids` | ✅ | ✅ | Raw ids |
 | **`categories`** (resolved) | ❌ *ids only* | ✅ | See §5 to add |
 | **`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}` |
 | `downloads[]`, `download_limit`, `download_expiry` | ❌ | ❌ | **Never** exposed publicly — paywalled. Gated by `commerce/storefront-account` `get-download` |
 
-## 2. Tags — render them in **both** views
+## 2. Ribbons — 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.
+Ribbons are flat, cross-cutting labels ("Best Seller", "New", "Gift"); categories are the hierarchical spine. Generated storefronts routinely omit ribbons entirely. Don't.
 
-- **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 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.
+- **Listing rows carry resolved `ribbons`** (`{id, name}`), so a card can render them with no extra call. One or two per card is useful (a corner label like "Best Seller"); more is noise. Hide the block when the array is empty — never a dangling "Ribbons:" label.
+- **On the product page**, render `product.ribbons` (the top-level `ribbons` array) as labels near the metadata, visually lighter than the category breadcrumb.
+- **Every ribbon can link to a filtered listing** — `list-products` with `ribbon_id` — never a dead label. A ribbon has no slug, so key the URL on its id (`/shop?ribbon=<ribbon_id>`) so the page is shareable and survives reload. Use `list-ribbons` for a name to label it with.
+- **Offer ribbons as a listing filter** from `list-ribbons`, which hides ribbons no published product carries and gives a `count` for labels like "Gift (12)". `ribbon_id` stacks with `category_id`, price, `on_sale`, `featured`, `in_stock_only`.
+- **Ribbon landing page:** `list-products` filtered by `ribbon_id`, with the ribbon's `name` as the heading.
+- Don't put ribbons in the breadcrumb, and don't use them as variant options — a size or colour is an `attribute`, not a ribbon.
+- Descriptive properties (Material, Care) are **modifiers** in `meta_data`, not ribbons and not attributes. Render them as a spec table on the product page.
 
 ## 3. Product shapes in each view
 
@@ -66,9 +66,9 @@ A listing row has no `variations`, so a card still cannot compute the full range
 
 ## 4. Sensible defaults per view
 
-**Card:** image, name, price (or range), sale badge from `on_sale`, stars from `average_rating`/`rating_count`, out-of-stock state from `stock_status`, one or two tags. Link the whole card to the product page.
+**Card:** image, name, price (or range), sale badge from `on_sale`, stars from `average_rating`/`rating_count`, out-of-stock state from `stock_status`, one or two ribbons. Link the whole card to the product page.
 
-**Product page:** gallery, name, price, variant selectors, stock, `short_description` then `description`, SKU, categories breadcrumb, tags, reviews, then upsells/cross-sells.
+**Product page:** gallery, name, price, variant selectors, stock, `short_description` then `description`, SKU, categories breadcrumb, ribbons, reviews, then upsells/cross-sells.
 
 ## 5. Adding a `get-product`-only field to the list view
 
@@ -77,10 +77,10 @@ If a customer asks for something the row doesn't carry — resolved categories a
 `list-products` resolves its page slice through a helper in `base44/functions/commerce/storefront-catalog/entry.ts`:
 
 ```ts
-const pageItems = await withTags(sr, products.slice(start, start + perPage).map(publicProduct));
+const pageItems = await withRibbons(sr, products.slice(start, start + perPage).map(publicProduct));
 ```
 
-`withTags` reads the taxonomy **once per request** and maps ids on the rows — not once per row. Extend that pattern: read the entity for the whole page, build an id→record `Map`, attach the short shape each card needs. Keep it to the fields the UI renders; a listing payload is served on every browse.
+`withRibbons` reads the taxonomy **once per request** and maps ids on the rows — not once per row. Extend that pattern: read the entity for the whole page, build an id→record `Map`, attach the short shape each card needs. Keep it to the fields the UI renders; a listing payload is served on every browse.
 
 What not to do:
 

package/skills/commerce/references/reviews.md

@@ -6,15 +6,21 @@ 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;
+- `commerce/storefront-catalog` `submit-review` accepts `{ product_id, email, reviewer?, review, rating? }` from **anyone — no login**. For a signed-in caller the session email always wins (the payload cannot impersonate); a guest supplies `email`. `verified` is derived from that email's order history;
+- `commerce/storefront-account` `my-reviews` lists a signed-in 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:
+**The one server-side switch is auto-approval** (`products.auto_approve_reviews`, the toggle on the admin's Reviews screen): off (the default) holds every new review as `hold` for moderation; on publishes immediately. Tell the submitter their review is awaiting approval rather than showing it as live.
 
-- 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.
+## Policies are yours to enforce in the UI
 
-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).
+The server deliberately ships the **most open default — anyone can review by email**. Anything stricter is storefront policy, implemented where you build the form:
+
+- **Login-gated reviews** — render the form only for a signed-in session (`base44.auth.me()`), and omit `email` from the payload: the session email is used automatically.
+- **Verified buyers only** — before showing the form to a signed-in customer, check their history: `commerce/storefront-account` `my-orders` and look for a `processing`/`completed` order containing the product. (For guests there is nothing to check against — pair this policy with login-gating.) The `verified` flag on every stored review tells moderators and readers which reviews came from buyers either way — an honest middle ground is to accept all reviews and render a "Verified purchase" badge from it.
+- **Required rating** — `rating` is optional server-side (0–5 when present); make the stars mandatory in the form before submitting if the store wants no unrated reviews.
+- **Disabling reviews store-wide** — simply build no review UI. There is no server switch to keep in sync.
+
+If a policy must hold even against handcrafted API calls (not just your UI), enforce it in a backend function of your own that wraps `submit-review` — the same pattern as any custom storefront action.
+
+Shapes and error codes (`400 email_required|review_incomplete|invalid_rating`): [`docs/api-storefront.md`](../docs/api-storefront.md#submit-review). Where ratings belong per view: [`references/product-render.md`](./product-render.md).

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

@@ -80,4 +80,4 @@ Handle `400 variation_required` (empty `variation_id` on a product with attribut
 - [ ] Initial state from `defaultSelection`; selection mirrored into the URL.
 - [ ] **Add to cart** gated on `view.purchasable`, sending `view.addToCart`.
 - [ ] 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).
+- [ ] Ribbons, ratings, upsells and the rest per [`product-render.md`](./product-render.md).

package/src/commerce/admin/README.md

@@ -4,8 +4,8 @@ React admin UI for the Base44 commerce template. Copy this
 folder into a Base44 app built on the default template (Vite + React +
 Tailwind + shadcn/ui + React Router) to get a full store back office.
 
-> Install docs: [`skills/commerce/installation-guidelines.md`](../../../skills/commerce/installation-guidelines.md) · mounting & role setup: [`skills/commerce/post-installation.md`](../../../skills/commerce/post-installation.md) · architecture & operations: the commerce skill, [`skills/commerce/SKILL.md`](../../../skills/commerce/SKILL.md)
-> API references: [`skills/commerce/docs/api-admin.md`](../../../skills/commerce/docs/api-admin.md), [`skills/commerce/docs/api-storefront.md`](../../../skills/commerce/docs/api-storefront.md)
+> Install docs: [`.agents/skills/commerce/installation-guidelines.md`](../../../.agents/skills/commerce/installation-guidelines.md) · mounting & role setup: [`.agents/skills/commerce/post-installation.md`](../../../.agents/skills/commerce/post-installation.md) · architecture & operations: the commerce skill, [`.agents/skills/commerce/SKILL.md`](../../../.agents/skills/commerce/SKILL.md)
+> API references: [`.agents/skills/commerce/docs/api-admin.md`](../../../.agents/skills/commerce/docs/api-admin.md), [`.agents/skills/commerce/docs/api-storefront.md`](../../../.agents/skills/commerce/docs/api-storefront.md)
 
 ## Mounting
 
@@ -39,7 +39,7 @@ Tailwind + shadcn/ui + React Router) to get a full store back office.
    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
    catalog — the store counts as ready and this screen never shows; see
-   `skills/commerce/post-installation.md` §2.
+   `.agents/skills/commerce/post-installation.md` §2.
 
 ## External touchpoints
 
@@ -77,8 +77,7 @@ routes.jsx       Route table + <AdminRoutes/>
 layout/          AdminLayout, Sidebar, Topbar, AuthGuard (admin-role gate), AccessDenied
 bot/             StoreAdminBot (chat panel over the commerce/StoreAdmin agent), Markdown (GFM renderer)
 context/         SettingsContext (store settings + first-run seeding), BasePathContext
-hooks/           useAsync, usePagedList, useRealtime (live updates), useMoney, useDebounce,
-                 usePaymentProvider (is an online payment provider connected?)
+hooks/           useAsync, usePagedList, useRealtime (live updates), useMoney, useDebounce
 lib/             api (function calls), constants, format, geo-data, order/product utils
 components/      DataTable, SearchSelect, MoneyInput, DateRangePicker, AddressForm, …
 pages/           All admin pages (orders, products, coupons, customers, reports, settings, webhooks)

package/src/commerce/admin/bot/Markdown.jsx

@@ -16,7 +16,7 @@ import { useAdminHref } from "../context/BasePathContext";
  */
 /**
  * `admin:` links are the agent's way to send the operator to a page it cannot
- * act on itself (`[Settings → Tax](admin:settings/tax)`). Resolved through
+ * act on itself (`[Settings → Shipping & Tax](admin:settings/shipping-tax)`). Resolved through
  * useAdminHref so they follow the actual mount point, and routed in-app rather
  * than opening a tab. Everything else stays an external link.
  */

package/src/commerce/admin/hooks/useMoney.js

@@ -3,7 +3,9 @@ import { useSettings } from "../context/SettingsContext";
 import { CURRENCIES } from "../lib/constants";
 
 /**
- * Currency formatter driven by the `general` settings group.
+ * Currency formatter driven by `general.currency`. Formatting itself is
+ * localization's job — Intl.NumberFormat renders the symbol, separators and
+ * decimals for the browser locale; there are no format settings.
  * Returns { format(n), symbol, code, decimals }.
  */
 export default function useMoney() {
@@ -13,13 +15,17 @@ export default function useMoney() {
     const get = settings?.get || (() => undefined);
     const code = get("general", "currency", "USD");
     const currency = CURRENCIES.find((cc) => cc.code === code);
+    let formatter = null;
+    try {
+      formatter = new Intl.NumberFormat(undefined, { style: "currency", currency: code });
+    } catch {
+      formatter = null; // unknown code — fall back below
+    }
     return {
       code,
       symbol: currency?.symbol || code,
-      position: get("general", "currency_position", "left"),
-      thousandSep: get("general", "thousand_sep", ","),
-      decimalSep: get("general", "decimal_sep", "."),
-      decimals: get("general", "num_decimals", currency?.decimals ?? 2),
+      decimals: currency?.decimals ?? 2,
+      formatter,
     };
   }, [settings]);
 
@@ -27,23 +33,8 @@ export default function useMoney() {
     (n) => {
       const num = Number(n);
       const val = isNaN(num) ? 0 : num;
-      const negative = val < 0;
-      const fixed = Math.abs(val).toFixed(cfg.decimals);
-      const [intPart, decPart] = fixed.split(".");
-      const grouped = intPart.replace(/\B(?=(\d{3})+(?!\d))/g, cfg.thousandSep);
-      const amount = decPart ? grouped + cfg.decimalSep + decPart : grouped;
-      const sign = negative ? "-" : "";
-      switch (cfg.position) {
-        case "right":
-          return `${sign}${amount}${cfg.symbol}`;
-        case "left_space":
-          return `${sign}${cfg.symbol} ${amount}`;
-        case "right_space":
-          return `${sign}${amount} ${cfg.symbol}`;
-        case "left":
-        default:
-          return `${sign}${cfg.symbol}${amount}`;
-      }
+      if (cfg.formatter) return cfg.formatter.format(val);
+      return `${cfg.symbol} ${val.toFixed(cfg.decimals)}`;
     },
     [cfg]
   );

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

@@ -24,7 +24,7 @@ const AUTH_CHECK_TIMEOUT_MS = 8000;
 
 /**
  * Blocks the admin UI unless the caller is an authenticated user with
- * role === "admin". Do NOT weaken this check — see skills/commerce/post-installation.md.
+ * role === "admin". Do NOT weaken this check — see .agents/skills/commerce/post-installation.md.
  * (Server-side RLS + requireAdmin() in functions enforce this independently.)
  *
  * Timing out resolves to **no user**, i.e. the sign-in screen — it never grants

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 CATALOG_VISIBILITIES = [
-  { value: "visible", label: "Shop and search results" },
-  { value: "catalog", label: "Shop only" },
-  { value: "search", label: "Search results only" },
-  { value: "hidden", label: "Hidden" },
-];
-
 export const STOCK_STATUSES = [
   { value: "instock", label: "In stock", color: "bg-green-100 text-green-800 border-green-200" },
   { value: "outofstock", label: "Out of stock", color: "bg-red-100 text-red-800 border-red-200" },
@@ -38,7 +31,6 @@ export const BACKORDER_OPTIONS = [
 
 export const TAX_STATUSES = [
   { value: "taxable", label: "Taxable" },
-  { value: "shipping", label: "Shipping only" },
   { value: "none", label: "None" },
 ];
 
@@ -68,20 +60,6 @@ export const WEBHOOK_TOPICS = [
   "coupon.created", "coupon.updated", "coupon.deleted",
 ];
 
-export const SHIPPING_METHOD_TYPES = [
-  { value: "flat_rate", label: "Flat rate" },
-  { value: "free_shipping", label: "Free shipping" },
-  { value: "local_pickup", label: "Local pickup" },
-];
-
-export const FREE_SHIPPING_REQUIRES = [
-  { value: "", label: "No requirement" },
-  { value: "coupon", label: "A valid free shipping coupon" },
-  { value: "min_amount", label: "A minimum order amount" },
-  { value: "either", label: "A minimum order amount OR a coupon" },
-  { value: "both", label: "A minimum order amount AND a coupon" },
-];
-
 /**
  * The 11 transactional emails.
  * `recipient: "admin"` emails expose a Recipient override in the Emails settings.
@@ -91,6 +69,8 @@ export const EMAIL_TYPES = [
   { id: "new_order", label: "New order", recipient: "admin" },
   { id: "cancelled_order", label: "Cancelled order", recipient: "admin" },
   { id: "failed_order", label: "Failed order", recipient: "admin" },
+  { id: "low_stock", label: "Low stock", recipient: "admin", stock: true },
+  { id: "out_of_stock", label: "Out of stock", recipient: "admin", stock: true },
   { id: "on_hold_order", label: "Order on-hold", recipient: "customer" },
   { id: "processing_order", label: "Processing order", recipient: "customer" },
   { id: "completed_order", label: "Completed order", recipient: "customer" },
@@ -135,13 +115,6 @@ export const CURRENCIES = [
   { code: "VND", name: "Vietnamese Dong", symbol: "₫", decimals: 0 },
 ];
 
-export const CURRENCY_POSITIONS = [
-  { value: "left", label: "Left ($99.99)" },
-  { value: "right", label: "Right (99.99$)" },
-  { value: "left_space", label: "Left with space ($ 99.99)" },
-  { value: "right_space", label: "Right with space (99.99 $)" },
-];
-
 export const WEIGHT_UNITS = ["kg", "g", "lbs", "oz"];
 export const DIMENSION_UNITS = ["cm", "m", "mm", "in", "yd"];
 

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

@@ -98,7 +98,7 @@ export function buildOrderPatch(draft, before) {
     patch.fees = (draft.fee_lines || []).map((f) => ({
       name: f.name,
       amount: f.total,
-      tax_class: f.tax_class,
+      tax_group: f.tax_group,
       tax_status: f.tax_status,
     }));
   }