@base44/app-plugin-commerce 0.1.0

package/skills/commerce/SKILL.md

@@ -0,0 +1,62 @@
+---
+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.
+---
+
+# Commerce
+
+Operational guidance for extending, operating and building on the Base44 Commerce Template. This file is the map: it stays short, and each topic links to a focused reference under [`skills/commerce/references/`](./references/) — open one only when your task touches that area. The API references live in [`skills/commerce/docs/`](./docs/).
+
+> **If you are a Base44 agent working inside the runtime, read this first:**
+> - **Don't read the whole codebase up front.** Start with this file, then open only the files your current task touches plus the matching reference below, pulling in more as you go. Reading everything first just burns context.
+> - **Don't weaken the admin gating.** The UI guard, entity RLS and function guards form three enforcement layers — see [`skills/commerce/post-installation.md`](./post-installation.md) — keep all of them intact when changing routes or schemas.
+
+## 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).
+
+## 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**.
+
+### 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`:
+   ```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.
+
+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.
+
+All functions return the envelope `{ success, data }` (or `{ success, error, code }`); with the SDK the body is on `res.data`:
+
+```js
+const res = await base44.functions.invoke("commerce/storefront-catalog", { action: "list-products", per_page: 12 });
+const { products, has_next } = res.data.data;   // res.data = envelope, .data = payload
+```
+
+## Topic references
+
+Open the matching file under `skills/commerce/references/` only when a task touches its area:
+
+| 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) |
+| 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) |
+| 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) |
+| Webhooks | outbound webhooks, HMAC signing, delivery log, auto-disable behavior | [`references/webhooks.md`](./references/webhooks.md) |
+| Images & downloads | catalog image uploads, downloadable products, private files & signed URLs | [`references/media-and-downloads.md`](./references/media-and-downloads.md) |
+| Limits & performance | pagination caps, search, no-transaction consequences, record size, reports scaling | [`references/limits-and-performance.md`](./references/limits-and-performance.md) |
+| Guest access & security | public storefront functions, `cart_token`/`order_key` handling, RLS boundaries | [`references/guest-access-security.md`](./references/guest-access-security.md) |

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

@@ -0,0 +1,186 @@
+# Admin API Reference
+
+For building store automation or an alternative admin UI against the Base44 Commerce Template. The bundled admin UI (`src/commerce/admin/`) uses exactly this surface.
+
+## Data-access contract
+
+Two access styles. **Reads are direct** entity SDK calls; **mutations with side effects go through `commerce/admin-*` functions**; simple config entities are **direct CRUD** (protected by admin-only RLS).
+
+| Resource | Reads | Writes | Why |
+|---|---|---|---|
+| commerce.Product, commerce.ProductVariation | direct (`filter`/`get`/`list`) | **`commerce/admin-products`** | derived pricing/stock, taxonomy counts, webhooks |
+| commerce.Order, commerce.OrderNote | direct | **`commerce/admin-orders`** | lifecycle side effects (stock, emails, webhooks, dates) |
+| commerce.OrderRefund | direct | **`commerce/admin-refunds`** | restock, totals, refund status transition |
+| 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.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.
+
+## Invocation & envelope
+
+```js
+const res = await base44.functions.invoke("commerce/admin-products", { action: "search", q: "shirt", limit: 20 });
+const { rows, has_next } = res.data.data;   // res.data = { success, data }; .data = payload
+```
+Success: `{ success: true, data }`. Failure: `{ success: false, error, code }` with the HTTP status set. Auth: every `commerce/admin-*` function calls `requireAdmin()` → **401** if not signed in, **403** if signed in without the `admin` role, before any data access (via the service role).
+
+## Pagination & search
+
+- No total-count API. List endpoints use **limit + skip** with a **`limit+1`** probe: request one extra row; if it comes back, there's a next page. `search` actions return `{ rows, has_next }`.
+- Entity `filter` is **exact-match only** — free-text search is server-side (`search` actions scan + JS-match), so use those for name/email/code lookups rather than `filter`.
+- Status-tab counts come from dedicated count actions (`commerce/admin-orders` `status-counts`), not from search.
+
+---
+
+## commerce/admin-products
+
+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 }`.
+- **`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.
+- **`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?` |
+
+  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.
+
+## commerce/admin-orders
+
+Actions: `create-draft` · `create` · `update` · `preview` · `update-status` · `bulk-status` · `status-counts` · `search` · `recalculate` · `apply-coupon` · `remove-coupon` · `add-note` · `delete-note` · `send-email` · `grant-download` · `revoke-download` · `delete` · `release-expired-holds`
+
+- **`create-draft`** — no payload → empty `pending` admin order (with `order_number`/`order_key`), no lifecycle effects yet. Used by "Add order".
+- **`create`** — `{ items, coupon_codes?, fees?, billing?, shipping?, customer_id?, chosen_shipping_method?, payment_method?, customer_note?, status?, reduce_stock? }`. Prices via the same totals engine as checkout, then transitions to `status` (default `pending`). `reduce_stock: false` on a pending order fires creation effects (new_order email, `order.created`) **without** reducing stock.
+- **`update`** — `{ order_id, patch }`. The **patch** shape:
+  - Any time: `billing`, `shipping`, `customer_id`, `customer_note`, `payment_method`, `meta_data`, `status`.
+  - **Line edits require pending/on-hold** (else `409 order_locked`): `items` (specs `{ product_id, variation_id?, quantity, price_override? }`), `fees`, `coupon_codes`, `chosen_shipping_method`. Providing any of these — or changing addresses — triggers a full reprice.
+  - A `status` in the patch is delegated to the transition engine last (fires the side effects below); otherwise an `order.updated` webhook fires.
+- **`preview`** — `{ order_id, patch }`. **Reads only — writes nothing, fires no webhooks.** Prices the same patch shape `update` takes and returns `{ fields }`: the Order fields `update` *would* have written (`line_items` with per-line tax, `shipping_lines`, `fee_lines`, `coupon_lines`, `tax_lines` and every total). Allowed on locked orders, since nothing is persisted. Only the pricing keys matter (`items`, `fees`, `shipping_lines`, `billing`, `shipping`); the rest are ignored. This is how the admin order editor shows live totals for **unsaved** edits — add a product and the tax, discount and grand total update before saving — without reimplementing tax and coupon rules on the client. Sharing `repriceOptsFromPatch()` with `update` is what guarantees the preview equals the saved result.
+- **`update-status`** — `{ order_id, status, note? }` → runs the transition engine (side-effect matrix below).
+- **`bulk-status`** — `{ ids, status }` → `{ results: [{ id, success, error? }] }`.
+- **`status-counts`** — no payload → `{ all, pending, processing, "on-hold", completed, cancelled, refunded, failed }` (includes the `all` key). Powers the list tabs.
+- **`search`** — `{ q?, status?, date_min?, date_max?, sort?, limit?, skip? }` → `{ rows, has_next }`. `q` matches order number, billing name, billing email.
+- **`recalculate`** — `{ order_id, reprice_from_catalog? }` → re-runs tax + totals on the current lines.
+- **`apply-coupon` / `remove-coupon`** — `{ order_id, code }` (validates, then reprices; `409 order_locked` if not editable, `409 already_applied`).
+- **`add-note`** — `{ order_id, note, is_customer_note? }` (a customer note emails the customer) · **`delete-note`** — `{ note_id }`.
+- **`send-email`** — `{ order_id, type }` (re-send an order email, e.g. `customer_invoice`; `force`d).
+- **`grant-download`** — `{ order_id, product_id }` (creates `commerce.DownloadPermission`s for the product's files) · **`revoke-download`** — `{ permission_id }`.
+- **`delete`** — `{ order_id }` — only `pending`/`cancelled`/`failed` (`409 order_locked` otherwise); cascades notes/refunds/permissions; fires `order.deleted`.
+- **`release-expired-holds`** — cancels unpaid orders past `hold_expires_at` and restores their stock → `{ released }`.
+
+### Order status side-effect matrix
+
+Applied by the transition engine; each effect is flag-guarded so a re-entered status never double-fires.
+
+| Entering | Stock | Coupons | Dates | Emails | Webhook | Downloads |
+|---|---|---|---|---|---|---|
+| pending (create) | reduce + set `hold_expires_at` | — | — | `new_order`→admin | `order.created` | — |
+| processing | ensure reduced; clear hold | count usage | `date_paid` if unset | `processing`→customer (+`new_order` if unsent) | `order.updated` | grant if virtual-only |
+| on-hold | ensure reduced; clear hold | count usage | — | `on_hold_order`→customer | `order.updated` | — |
+| completed | ensure reduced | count usage | `date_completed` (+`date_paid`) | `completed_order`→customer | `order.updated` | grant |
+| cancelled | restore if reduced | uncount if counted | — | `cancelled_order`→admin | `order.updated` | revoke |
+| failed | restore | uncount | — | `failed_order`→admin+customer | `order.updated` | — |
+| refunded | (per-refund restock) | keep counted | — | `refunded_order`→customer | `order.updated` | revoke |
+
+`total_sales` increments on first stock reduction, decrements on restore.
+
+## commerce/admin-refunds
+
+Actions: `create` · `delete`
+
+- **`create`** — `{ order_id, amount, reason?, line_items?, restock_items?, refund_payment? }`. `line_items` specs: `{ line_id, quantity, refund_total, refund_tax? }`. Validates `amount` ≤ remaining refundable (`400 amount_exceeds_refundable`, `400 invalid_amount`). Restocks per line when `restock_items`. Updates `order.total_refunded`; a full refund transitions the order to `refunded`, otherwise sends `partial_refund` + `order.updated`. With **`refund_payment: true`** the money goes back through the payment provider **first** — a failed provider refund writes nothing locally, so there is never a phantom refund — and the response carries `gateway_refund: { provider, id, status, amount }` with the record's `refunded_payment: true`. An order that wasn't paid online rejects it with `400 no_online_payment`. → `{ refund, order, gateway_refund? }`.
+- **`delete`** — `{ refund_id }`. Reverses `total_refunded`; adds a note warning that restocked items are **not** auto-un-restocked.
+
+## commerce/admin-coupons
+
+Actions: `save` · `delete` · `batch` · `search`
+
+- **`save`** — `{ coupon }`. Lowercases + enforces unique `code` (`duplicate_code`); percent amount ≤ 100. Fires `coupon.created`/`updated`.
+- **`delete`** — `{ id }` (fires `coupon.deleted`) · **`batch`** — `{ create?, update?, delete? }` · **`search`** — `{ q?, limit?, skip? }` → `{ rows, has_next }` (matches code/description).
+
+## commerce/admin-customers
+
+Actions: `save` · `delete` · `search` · `invite` · `recalculate-stats`
+
+- **`save`** — `{ customer }`. Unique email; links guest→registered. Fires `customer.*`.
+- **`delete`** — `{ id, reassign_orders_to_guest? }`.
+- **`search`** — `{ q?, limit?, skip? }` → `{ rows, has_next }` (name/email/username).
+- **`invite`** — `{ email }` → `base44.users.inviteUser(email)`, links `user_id`.
+- **`recalculate-stats`** — `{ id }` → recomputes `orders_count`, `total_spent`, `is_paying_customer` from the customer's paid orders.
+
+## commerce/admin-reviews
+
+Actions: `set-status` · `update` · `delete`. Each recomputes the product's `average_rating`/`rating_count` from approved reviews.
+- **`set-status`** — `{ id, status }` (`approved`|`hold`|`spam`|`trash`) · **`update`** — `{ id, rating?, review? }` · **`delete`** — `{ id }`.
+
+## commerce/admin-webhooks
+
+Actions: `test` · `redeliver` (webhook definitions themselves are direct `commerce.Webhook` CRUD).
+- **`test`** — `{ webhook_id }` → POSTs a sample payload, logs a `commerce.WebhookDelivery`, returns `{ delivery_id, response_code, success, duration_ms }`.
+- **`redeliver`** — `{ delivery_id }` → re-sends the original request body.
+
+## commerce/admin-reports
+
+All actions scan orders on demand (counted = `date_paid` set, or status `processing`/`completed`). See the commerce skill reference `skills/commerce/references/limits-and-performance.md` for scaling.
+
+| Action | Payload | Returns |
+|---|---|---|
+| `summary` | — | `{ sales_today, sales_month, orders_by_status, low_stock_count, out_of_stock_count, top_seller }` where `sales_*` = `{ gross_sales, net_sales, orders, items, tax, shipping, discount, refunds }` |
+| `sales` | `{ date_min?, date_max?, interval? }` (`day`\|`week`\|`month`) | `{ totals: <agg>, series: [{ period, ...agg }] }` (net = gross − refunds − tax − shipping) |
+| `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 } }` |
+| `customers-totals` | — | `{ total, guests, registered, paying }` |
+| `coupons-totals` | — | `{ total, by: { [discount_type]: count } }` |
+| `reviews-totals` | — | `{ total, by: { [status]: count } }` |
+| `categories-totals` / `tags-totals` | — | `{ total, terms: [{ id, name, count }] }` |
+| `attributes-totals` | — | `{ total, attributes: [{ id, name, terms }] }` |
+
+## commerce/admin-tools
+
+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.
+- **`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`.
+- **`recount-coupon-usage`** — repairs `usage_count`/`used_by`.
+- **`recalculate-customer-stats-all`** — repairs all customers' `orders_count`/`total_spent`.
+- **`prune-webhook-deliveries`** — `{ keep_days }`.
+- **`clear-abandoned-carts`** — `{ older_than_days }`.
+- **`regenerate-download-permissions`** — `{ order_id }`.
+
+## commerce/payments
+
+Actions: `status` · `create-link` · `complete-return` · `verify` — the admin side of online payments (the same function serves customers, who authorize with `order_key` instead; see [`api-storefront.md`](./api-storefront.md)).
+
+- **`status`** (admin) — `{ provider, provider_label, gateway_slug, connected, error? }`.
+- **`create-link`** — `{ order_id }` → `{ provider, session_id, url, expires_at? }`: a provider-hosted payment page for an unpaid order, i.e. the **payment link** to send a customer. Accepts an order with **any** payment method (including none, as admin-created orders start) and switches it onto the online gateway, logging the change — refunds key off `payment_method`, so this keeps the order honest about how it was paid. `409 already_paid`, `400 online_payments_disabled`, `503 payment_provider_unavailable`.
+- **`verify`** — `{ order_id }` → `{ paid, already_confirmed, status, order }`: re-asks the provider and moves the order to `processing` when the money is there. Idempotent.
+- **`complete-return`** — `{ order_id, order_key, payment?, return_url? }` → `{ state, paid, already_confirmed, status, order, payment_link }`: what the storefront's **mandatory** `/order-received` page calls — confirm, progress the order, and hand back a render-ready result plus a fresh payment link while unpaid.
+
+`commerce/payment-webhook` is the provider's signed callback (raw body, no `action` envelope) and needs `PAYMENT_WEBHOOK_SECRET`; it refuses every request until that is set. Provider specifics live in `base44/shared/commerce/payments.ts` — see [`../references/online-payments.md`](../references/online-payments.md).
+
+## 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" } }`.