@base44/app-plugin-commerce 0.2.1 → 0.2.2

package/README.md

@@ -8,11 +8,11 @@ It provides a full-featured **commerce data model and behavior** (variant-driven
 
 - **20 entities** — Products (a product sells variants when it carries attributes; no type field), variations, categories, ribbons, attributes + values, reviews, orders (embedded line/shipping/tax/fee/coupon lines), order notes, refunds, coupons, customers, Shipping & Tax Locations (shipping rates + tax groups per location), payment gateways, store settings, webhooks + deliveries, carts, download permissions, email log.
 - **16 backend functions** — 9 admin (`commerce/admin-products`, `commerce/admin-orders`, `commerce/admin-refunds`, `commerce/admin-coupons`, `commerce/admin-customers`, `commerce/admin-reviews`, `commerce/admin-webhooks`, `commerce/admin-reports`, `commerce/admin-tools`), 4 storefront (`commerce/storefront-catalog`, `commerce/storefront-cart`, `commerce/storefront-checkout`, `commerce/storefront-account`), 2 payment (`commerce/payments`, `commerce/payment-webhook`), and an idempotent `commerce/seed-store` — one call seeds the business defaults **and the whole catalog** (products with attributes in, variants/categories/taxonomy created internally).
-- **Payments: manual methods work out of the box; online cards are opt-in** — the seed enables the manual `offline` method (bank transfer, cash on delivery, pickup: on-hold + instructions, no code) and leaves the `card` gateway **disabled**. The order side of card payments *is* premade — checkout routing, payment links for unpaid orders, two idempotent confirmation paths (customer return + webhook) and refund records — so a store that opts in wires a provider by implementing **four functions in one file**, `base44/shared/commerce/card-payment.ts`. **For Stripe there is nothing to write**: `base44/shared/commerce/card-payment.stripe.ts` is a complete implementation — copy it over the stub, store the secret, register the webhook, enable the gateway. Any other provider (PayPal, Adyen, a local PSP) follows the same shape. Enable the gateway only with a provider behind it, or checkout answers `503 no_card_payment_provider`. The rule and timing: [`skills/commerce/install/03-data.md`](./skills/commerce/install/03-data.md); provider mechanics: [`skills/commerce/references/online-payments.md`](./skills/commerce/references/online-payments.md). The admin can add more manual methods in Settings → Payments.
+- **Payments: manual methods work out of the box; online cards are opt-in** — the seed enables the manual `offline` method (bank transfer, cash on delivery, pickup: on-hold + instructions, no code) and leaves the `card` gateway **disabled**. The order side of card payments *is* premade — checkout routing, payment links for unpaid orders, two idempotent confirmation paths (customer return + webhook) and refund records — so a store that opts in wires a provider by implementing **four functions in one file**, `base44/shared/commerce/card-payment.ts`. **For Stripe there is nothing to write**: `base44/shared/commerce/card-payment.stripe.ts` is a complete implementation used as-is — copy it over the stub and enable the gateway. Any other provider (PayPal, Adyen, a local PSP) follows the same shape. Enable the gateway only with a provider behind it, or checkout answers `503 no_card_payment_provider`. The rule and timing: [`skills/commerce/install/03-data.md`](./skills/commerce/install/03-data.md); provider mechanics: [`skills/commerce/references/online-payments.md`](./skills/commerce/references/online-payments.md). The admin can add more manual methods in Settings → Payments.
 - **Shared commerce engine** (`base44/shared/commerce/`) — totals, tax, shipping, coupons, stock, order lifecycle, webhook dispatch (HMAC-signed), emails, card-payment plumbing, plus static country/currency/continent data.
 - **Admin UI** (`src/commerce/admin/`) — a React/Tailwind/shadcn admin with a familiar store back-office information architecture: dashboard, orders, products, coupons, customers, reports, and full settings including webhooks. Admin-role gated.
 - **Storefront helpers** (`src/commerce/utils/`) — framework-free, dependency-free modules for the shopfront you build: `storefront.js` is the API client (`createStorefront(base44)` — cart-token lifecycle, cached store-info, catalog/cart/checkout/reviews/return-page calls); `variants.js` maps an attribute selection (Size, Color) onto a `ProductVariation` and back, plus per-option availability and price ranges; `price.js` encodes the from-price and price-range rules; `totals.js` projects a cart *or* an order into one summary shape; `address-spec.js` is the checkout address form as data; `images.js` normalizes catalog images; `shipping-promos.js` reads the store's real free-shipping configuration so "Free shipping over €150" states a configured rule rather than an invented number.
-- **Storefront React layer** (`src/commerce/storefront/`) — **two tiers.** The *identity* surfaces stay yours to design (home, collection grid, product-page layout, product card, theme — the kit ships no markup for them). The *commodity* surfaces ship as **blocks** that inherit your theme and can be restyled, slotted or replaced: `CheckoutBlock`, `CartLinesBlock`, `TotalsBlock`, `CouponFieldBlock`, `QuantityStepper`, `OrderReceivedBlock`, `ReviewsBlock`, `AddressFieldsBlock`, plus the product page's internals (`VariantSelectorBlock`, `AddToCartBlock`, `ProductGalleryBlock`, `ProductSpecsBlock`, `BreadcrumbsBlock`, `ProductStripBlock`). Each is a thin composition of the hooks underneath: `StorefrontProvider`, `useProductList`/`useCategories`/`useRibbons`, `useProduct`/`useAddToCart`/`useProductPrice`/`useProductGallery`, `useProductReviews`, `useCart`/`useCartLine`/`useCoupon`, `useCheckout` + `useAddressForm`/`useTotalsLines`/`useCheckoutBlockers`, the headless `ShippingMethodPicker`/`PaymentMethodPicker`, `useOrderReturn`, and `useStorefrontSeo`. Needs React and nothing else.
+- **Storefront React layer** (`src/commerce/storefront/`) — **headless: the logic is premade, the UI never is.** Nothing in the layer renders markup or carries CSS; every element, class and word of copy in the storefront you build is yours, so a brief like "make it feel like <site>" applies to the whole store, checkout included. What ships is every piece of logic that is the same in all stores, as hooks returning complete view-models: `StorefrontProvider`, `useProductList`/`useCategories`/`useRibbons`, `useProduct`/`useAddToCart`/`useAddToCartButton`/`useProductPrice`/`useProductGallery` (+ the `variantAxes`/`productSpecs` render-model helpers), `useProductReviews`, `useCart`/`useCartLine`/`useCoupon`, `useCheckout` + `useAddressForm`/`useTotalsLines`/`useCheckoutBlockers`, `useOrderReturn`, and `useStorefrontSeo` — plus three render-prop components that stay just as headless (`ShippingMethodPicker`/`PaymentMethodPicker` for the two checkout choices that are store data, `CartLine` for per-row cart bindings). Each hook's doc comment states the render rules that keep a store correct (an unbuyable variant option renders disabled, not hidden; a receipt page must render `paymentInstructions`; …). Needs React and nothing else.
 - **StoreAdmin agent + bot** — an AI copilot (`base44/agents/commerce/StoreAdmin.jsonc`, registered as `commerce/StoreAdmin`) with the `commerce/*` functions attached directly as tools (calls run as the chatting user → `requireAdmin()` still applies), variant-aware order editing, plus a chat panel in the admin sidebar with GFM markdown-table rendering.
 - **Docs** — this README plus the commerce skill folder [`skills/commerce/`](./skills/commerce/): [`SKILL.md`](./skills/commerce/SKILL.md) is the map every agent starts from (and the only path the platform needs to know); [`install/`](./skills/commerce/install/) holds the three stage files that are the whole install (`01-install` → `02-storefront` → `03-data`, each read at the moment its work starts and dropped when its checklist passes); [`references/`](./skills/commerce/references/) holds per-topic guides opened only on demand; [`docs/`](./skills/commerce/docs/) holds the data-model map ([`entities.md`](./skills/commerce/docs/entities.md)) and the two API references. The whole folder is installed into the app at `.agents/skills/commerce/` so agents pick it up natively.
 
@@ -32,8 +32,8 @@ base44-commerce-template/
 │   └── commerce/
 │       ├── admin/      React admin UI (copy into your app's src/commerce/)
 │       ├── utils/      storefront helpers — API client, variants, price/totals rules
-│       └── storefront/ storefront React layer — hooks (cart, checkout, catalog,
-│           └── blocks/ reviews, SEO) + default markup for the commodity UI
+│       └── storefront/ storefront React layer — headless hooks (cart, checkout,
+│                       catalog, reviews, SEO); no markup or CSS ships
 ├── scripts/
 │   └── install.js         static installer (run from <app>/examples/commerce/scripts/)
 ├── skills/
@@ -42,7 +42,7 @@ base44-commerce-template/
 │       ├── SKILL.md       the map: what to read, when, and what to skip
 │       ├── install/       the whole install, in three staged files
 │       │   ├── 01-install.md     files, admin mount, role gating, the schedule
-│       │   ├── 02-storefront.md  storefront pages on the hooks + blocks
+│       │   ├── 02-storefront.md  storefront pages on the headless hooks
 │       │   └── 03-data.md        seeding, shipping zones, images, payments decision
 │       ├── references/    opened on demand (catalog rendering, shipping & tax,
 │       │                  online payments, reviews, store settings, emails,
@@ -105,7 +105,7 @@ If you build on Base44's hosted platform, use the Base44 agent/MCP to write the
 ## What's NOT included
 
 - **No storefront *design*.** The parts of a shopfront that carry a brand — the home page, the collection grid, the product card, the product page's layout, the theme — ship as nothing at all, on purpose: that is the work a build should spend its effort on. Everything under those surfaces does ship: the storefront API, the hooks, and default markup for the commodity UI (checkout, cart, totals, coupon field, reviews, order-received, and the product page's internals), all restylable and replaceable — see [`skills/commerce/install/02-storefront.md`](./skills/commerce/install/02-storefront.md) for how the two tiers fit together, [`skills/commerce/references/catalog-rendering.md`](./skills/commerce/references/catalog-rendering.md) for what each catalog call returns, and [`skills/commerce/docs/api-storefront.md`](./skills/commerce/docs/api-storefront.md) for the raw API.
-- **No payment provider — and cards are off by default.** The order side of card payments is premade (see above), but charging a card needs a provider, so `commerce/seed-store` enables the manual **`offline`** method (bank transfer, cash on delivery, pickup — no code, no credentials) and leaves the **`card`** gateway **switched off**. **Enable cards only if a provider is wired, or is about to be** — implement the four functions in `base44/shared/commerce/card-payment.ts` (for Stripe, copy the shipped `card-payment.stripe.ts` over it — see `skills/commerce/references/online-payments.md`) and enable the gateway via the seed's `payment_methods: ["offline", "card"]`; enabled with nothing behind it, checkout answers `503 no_card_payment_provider`. The rule and why it belongs at the end of a build rather than its start: `skills/commerce/install/03-data.md`.
+- **No payment provider — and cards are off by default.** The order side of card payments is premade (see above), but charging a card needs a provider, so `commerce/seed-store` enables the manual **`offline`** method (bank transfer, cash on delivery, pickup — no code, no credentials) and leaves the **`card`** gateway **switched off**. **Enable cards only if a provider is wired, or is about to be** — implement the four functions in `base44/shared/commerce/card-payment.ts`, or for Stripe copy the shipped `card-payment.stripe.ts` over it and use it as-is (`skills/commerce/references/online-payments.md`), then enable the gateway via the seed's `payment_methods: ["offline", "card"]`; enabled with nothing behind it, checkout answers `503 no_card_payment_provider`. The rule and why it belongs at the end of a build rather than its start: `skills/commerce/install/03-data.md`.
 - **No scheduled workflows shipped.** Base44 *does* have a scheduler, but this template ships no workflow files — time-based jobs (stock-hold release, cart expiry, webhook-log pruning) run **opportunistically** where possible, and for the rest you (or the Base44 agent) create scheduled workflows that call `commerce/admin-tools`/`commerce/admin-orders` actions — see [`skills/commerce/references/operations.md`](./skills/commerce/references/operations.md).
 
 ## Next steps

package/base44/agents/commerce/StoreAdmin.jsonc

@@ -10,7 +10,7 @@
 {
   "name": "StoreAdmin",
   "description": "Store administration copilot for the commerce template: manage products, orders, refunds, coupons, customers, reviews, reports and maintenance.",
-  "instructions": "You are StoreAdmin, the store administration copilot for this shop's back office. You help store operators inspect and manage the store: products, orders, refunds, coupons, customers, reviews, webhooks, reports, and maintenance.\n\n## How you access the store\nEvery tool takes a JSON body of the form {\"action\": \"<action>\", ...payload} (exception: commerce/seed-store takes {store_name, currency?, weight_unit?, dimension_unit?, with_sample_data?, products?, coupons?, locations?} with no action key — store_name is REQUIRED on a first seed, and products can bootstrap a whole catalog in one call, variants and ribbons included; see .agents/skills/commerce/docs/api-admin.md) and responds {success, data} or {success:false, error, code}. Search/list actions return {rows, has_next} using limit+skip pagination (there are no total counts). Use search actions for free-text lookups (product name, customer email, coupon code, order number).\n\nStore configuration (settings, Shipping & Tax Locations, payment gateways, webhook definitions) is not editable through your tools — see \"Sending the operator to a screen\" below.\n\n## Sending the operator to a screen\nSome configuration is only editable in the admin UI. When one of those is asked for, say plainly that you cannot change it from chat, name the screen, and give a link the operator can click — never just \"do it manually\", and never imply you tried and failed. Do not blame permissions or a security error: the reason is simply that the UI is the only place that configuration is edited.\n\nLinks use the `admin:` scheme with a path from the table below — `[Settings → Shipping & Tax](admin:settings/shipping-tax)`. The chat resolves that to wherever the admin is mounted, so never write `/store-admin/...` yourself.\n\n| Ask | Screen | Link |\n|---|---|---|\n| Currency, measurement units, payment return path | Settings → General | admin:settings/general |\n| Stock thresholds, hold minutes | Settings → Inventory | admin:settings/inventory |\n| Locations, shipping rates, tax groups, shipping tax | Settings → Shipping & Tax | admin:settings/shipping-tax |\n| Enabling a gateway, offline bank details | Settings → Payments | admin:settings/payments |\n| Store name (subjects + sender), admin + stock notification recipients, per-email overrides | Settings → Emails | admin:settings/emails |\n| Auto-approve reviews toggle | Products → Reviews | admin:products/reviews |\n| Creating or deleting a webhook (you CAN test and redeliver) | Settings → Webhooks | admin:settings/webhooks |\n\nExample: \"Tax rates aren't something I can change from here — they live per location. Open [Settings → Shipping & Tax](admin:settings/shipping-tax), edit the location and add the rate, then tell me and I'll re-check the order's totals.\"\n\nCatalog taxonomy is the opposite: you CAN create categories, ribbons, attributes and attribute values yourself with commerce/admin-products save-term. Never send the operator to a screen to create one — link to admin:products/categories if they want to review the category list by hand. Ribbons and attributes have no screen of their own: attributes are edited in the Attributes section of a product's Price & Inventory section, ribbons in the Ribbons card of the product sidebar — so link to the product (admin:products) instead.\n\n## Product variants — be careful\nA product that carries attributes is sold through its variants (there is no product type), and every variant can differ in attributes (e.g. size/color), SKU, price and stock.\n- NEVER pick a variation automatically. When an order line, stock change, or download grant involves a product that carries attributes, first fetch its variations with commerce/storefront-catalog {\"action\":\"get-product\",\"id\":...} (returns {product, variations}), present them in a table (attributes, SKU, price, stock status), and ask the operator which variation to use — then include that variation_id in the item spec.\n- If the operator already named an exact variation (by SKU or full attribute combination), match it against the fetched variations and confirm the match in your reply; if the description is partial or matches more than one variation, ask.\n- Order item specs for commerce/admin-orders create/update are {product_id, variation_id?, quantity, price_override?} — variation_id is REQUIRED for a product with attributes.\n- The same applies to commerce/admin-products set-stock (pass variation_id to change a variation's stock, not the parent's).\n\n## Behavior\n- Be concise and operational. Confirm before destructive or irreversible operations (delete, refund, bulk-status, prune, clear-abandoned-carts) by restating what will happen and asking the user to confirm — unless the user's message already explicitly confirms it.\n- When showing lists or reports, format them as GitHub-flavored markdown tables (| col | col | with a |---| separator row). Keep tables ≤ 8 columns; prefer the most decision-relevant fields (name/number, status, total, date). Format money with the store currency.\n- After a mutation, report exactly what changed (ids, statuses, totals) and surface any error/code verbatim.\n- If a request is ambiguous (which order? which product?), search first and present the candidates in a table, then ask.\n- For store health questions, start with commerce/admin-tools {\"action\":\"status\"} and commerce/admin-reports {\"action\":\"summary\"}.\n- Payments: for an unpaid order paid online, commerce/payments create-link {order_id} gives a payment page link to send the customer, and verify {order_id} re-checks whether the money arrived. If no payment provider is connected, say \"no payment provider is connected\" and that connecting one enables card payments — don't name or troubleshoot a specific provider. Never invent a payment link or claim an order is paid without verifying.\n- You act with store-operator privileges; do not attempt to weaken or bypass access controls, and never expose secrets (webhook secrets, tokens).",
+  "instructions": "You are StoreAdmin, the store administration copilot for this shop's back office. You help store operators inspect and manage the store: products, orders, refunds, coupons, customers, reviews, webhooks, reports, and maintenance.\n\n## How you access the store\nEvery tool takes a JSON body of the form {\"action\": \"<action>\", ...payload} (exception: commerce/seed-store takes {store_name, currency?, weight_unit?, dimension_unit?, with_sample_data?, products?, coupons?, locations?} with no action key — store_name is REQUIRED on a first seed, and products can bootstrap a whole catalog in one call, variants and ribbons included; see the commerce skill's docs/api-admin.md) and responds {success, data} or {success:false, error, code}. Search/list actions return {rows, has_next} using limit+skip pagination (there are no total counts). Use search actions for free-text lookups (product name, customer email, coupon code, order number).\n\nStore configuration (settings, Shipping & Tax Locations, payment gateways, webhook definitions) is not editable through your tools — see \"Sending the operator to a screen\" below.\n\n## Sending the operator to a screen\nSome configuration is only editable in the admin UI. When one of those is asked for, say plainly that you cannot change it from chat, name the screen, and give a link the operator can click — never just \"do it manually\", and never imply you tried and failed. Do not blame permissions or a security error: the reason is simply that the UI is the only place that configuration is edited.\n\nLinks use the `admin:` scheme with a path from the table below — `[Settings → Shipping & Tax](admin:settings/shipping-tax)`. The chat resolves that to wherever the admin is mounted, so never write `/store-admin/...` yourself.\n\n| Ask | Screen | Link |\n|---|---|---|\n| Currency, measurement units, payment return path | Settings → General | admin:settings/general |\n| Stock thresholds, hold minutes | Settings → Inventory | admin:settings/inventory |\n| Locations, shipping rates, tax groups, shipping tax | Settings → Shipping & Tax | admin:settings/shipping-tax |\n| Enabling a gateway, offline bank details | Settings → Payments | admin:settings/payments |\n| Store name (subjects + sender), admin + stock notification recipients, per-email overrides | Settings → Emails | admin:settings/emails |\n| Auto-approve reviews toggle | Products → Reviews | admin:products/reviews |\n| Creating or deleting a webhook (you CAN test and redeliver) | Settings → Webhooks | admin:settings/webhooks |\n\nExample: \"Tax rates aren't something I can change from here — they live per location. Open [Settings → Shipping & Tax](admin:settings/shipping-tax), edit the location and add the rate, then tell me and I'll re-check the order's totals.\"\n\nCatalog taxonomy is the opposite: you CAN create categories, ribbons, attributes and attribute values yourself with commerce/admin-products save-term. Never send the operator to a screen to create one — link to admin:products/categories if they want to review the category list by hand. Ribbons and attributes have no screen of their own: attributes are edited in the Attributes section of a product's Price & Inventory section, ribbons in the Ribbons card of the product sidebar — so link to the product (admin:products) instead.\n\n## Product variants — be careful\nA product that carries attributes is sold through its variants (there is no product type), and every variant can differ in attributes (e.g. size/color), SKU, price and stock.\n- NEVER pick a variation automatically. When an order line, stock change, or download grant involves a product that carries attributes, first fetch its variations with commerce/storefront-catalog {\"action\":\"get-product\",\"id\":...} (returns {product, variations}), present them in a table (attributes, SKU, price, stock status), and ask the operator which variation to use — then include that variation_id in the item spec.\n- If the operator already named an exact variation (by SKU or full attribute combination), match it against the fetched variations and confirm the match in your reply; if the description is partial or matches more than one variation, ask.\n- Order item specs for commerce/admin-orders create/update are {product_id, variation_id?, quantity, price_override?} — variation_id is REQUIRED for a product with attributes.\n- The same applies to commerce/admin-products set-stock (pass variation_id to change a variation's stock, not the parent's).\n\n## Behavior\n- Be concise and operational. Confirm before destructive or irreversible operations (delete, refund, bulk-status, prune, clear-abandoned-carts) by restating what will happen and asking the user to confirm — unless the user's message already explicitly confirms it.\n- When showing lists or reports, format them as GitHub-flavored markdown tables (| col | col | with a |---| separator row). Keep tables ≤ 8 columns; prefer the most decision-relevant fields (name/number, status, total, date). Format money with the store currency.\n- After a mutation, report exactly what changed (ids, statuses, totals) and surface any error/code verbatim.\n- If a request is ambiguous (which order? which product?), search first and present the candidates in a table, then ask.\n- For store health questions, start with commerce/admin-tools {\"action\":\"status\"} and commerce/admin-reports {\"action\":\"summary\"}.\n- Payments: for an unpaid order paid online, commerce/payments create-link {order_id} gives a payment page link to send the customer, and verify {order_id} re-checks whether the money arrived. If no payment provider is connected, say \"no payment provider is connected\" and that connecting one enables card payments — don't name or troubleshoot a specific provider. Never invent a payment link or claim an order is paid without verifying.\n- You act with store-operator privileges; do not attempt to weaken or bypass access controls, and never expose secrets (webhook secrets, tokens).",
   "tool_configs": [
     {
       "function_name": "commerce/admin-products",

package/base44/entities/commerce.OrderRefund.jsonc

@@ -21,7 +21,7 @@
     "refunded_payment": {
       "type": "boolean",
       "default": false,
-      "description": "True when a real refund was made at the payment provider (via shared/commerce/card-payment.ts refundCardPayment — see .agents/skills/commerce/references/online-payments.md)"
+      "description": "True when a real refund was made at the payment provider (via shared/commerce/card-payment.ts refundCardPayment — see the commerce skill's references/online-payments.md)"
     },
     "restock_items": {
       "type": "boolean",

package/base44/entities/commerce.PaymentGateway.jsonc

@@ -35,7 +35,7 @@
     },
     "settings": {
       "type": "object",
-      "description": "Per-gateway settings. offline: {account_details: [{account_name, account_number, bank_name, sort_code, iban, bic}]}; card: {} — provider config lives in code and backend secrets, never here; see .agents/skills/commerce/references/online-payments.md"
+      "description": "Per-gateway settings. offline: {account_details: [{account_name, account_number, bank_name, sort_code, iban, bic}]}; card: {} — provider config lives in code and backend secrets, never here; see the commerce skill's references/online-payments.md"
     }
   },
   "required": ["slug"],

package/base44/entities/commerce.Webhook.jsonc

@@ -34,7 +34,7 @@
     },
     "secret": {
       "type": "string",
-      "description": "HMAC-SHA256 signing secret (see .agents/skills/commerce/references/webhooks.md on storage tradeoffs)"
+      "description": "HMAC-SHA256 signing secret (see the commerce skill's references/operations.md on storage tradeoffs)"
     },
     "api_version": {
       "type": "string",

package/base44/functions/commerce/admin-products/entry.ts

@@ -4,7 +4,7 @@
  *
  * Actions: save | delete | batch | duplicate | set-stock | search |
  * save-term | delete-term | list-terms
- * Body: { action, ...payload } — see .agents/skills/commerce/docs/api-admin.md.
+ * Body: { action, ...payload } — see the commerce skill's docs/api-admin.md.
  */
 import { createClientFromRequest } from "npm:@base44/sdk";
 import { HttpError, requireAdmin } from "../../../shared/commerce/auth.ts";

package/base44/functions/commerce/admin-reports/entry.ts

@@ -1,7 +1,7 @@
 /**
  * commerce/admin-reports — on-demand report aggregation over orders.
  * Fine to ~10k orders; larger stores should materialize stats
- * (see .agents/skills/commerce/references/operations.md).
+ * (see the commerce skill's references/operations.md).
  *
  * Actions: summary | sales | top-sellers | stock |
  * orders-totals | products-totals | customers-totals | coupons-totals |

package/base44/functions/commerce/payments/entry.ts

@@ -1,8 +1,8 @@
 /**
  * commerce/payments — online payment for an order.
  *
- * The provider specifics live in the two implementable files (see
- * `.agents/skills/commerce/references/online-payments.md`); this function is
+ * The provider specifics live in the two implementable files (see the commerce
+ * skill's references/online-payments.md); this function is
  * the premade API the storefront and the admin use.
  *
  * Actions:

package/base44/functions/commerce/seed-store/defaults.ts

@@ -42,7 +42,7 @@ export const SETTINGS_DEFAULTS: Array<{ group_id: string; values: Record<string,
     values: {
       // The one review switch the server enforces; every other review policy
       // (login-gated, verified-only, required rating) belongs to the storefront
-      // UI — see .agents/skills/commerce/references/reviews.md.
+      // UI — see the commerce skill's references/reviews.md.
       auto_approve_reviews: false,
     },
   },

package/base44/functions/commerce/storefront-catalog/entry.ts

@@ -375,7 +375,7 @@ async function getStoreInfo(sr: any): Promise<any> {
  * signed-in session supplies the email (and can't spoof another); a guest
  * passes `email` in the payload. Stricter policies (login-gated forms,
  * verified-buyers-only, required ratings) are the storefront's to enforce in
- * its UI — see .agents/skills/commerce/references/reviews.md. The one server switch is
+ * its UI — see the commerce skill's references/reviews.md. The one server switch is
  * auto-approval; everything else submits as `hold` for moderation.
  */
 async function submitReview(sr: any, p: any, user: any): Promise<any> {

package/base44/functions/commerce/storefront-checkout/entry.ts

@@ -220,7 +220,7 @@ async function placeOrder(sr: any, req: Request, user: any, payload: any): Promi
   // (4) customer upsert by billing email
   const notices: string[] = [];
   if (payload.create_account && !user) {
-    notices.push("account_creation_requires_login"); // see .agents/skills/commerce/references/guest-access-security.md
+    notices.push("account_creation_requires_login"); // see the commerce skill's references/guest-access-security.md
   }
   const customer = await upsertCustomer(sr, billing, shippingAddress, user);
 

package/base44/shared/commerce/card-payment.stripe.ts

@@ -11,13 +11,14 @@
  *     "base44/shared/commerce/card-payment.ts",
  *   );
  *
- * then (1) store the merchant's Stripe **secret key** as the `STRIPE_SECRET_KEY`
- * app secret and redeploy the backend so the functions see it, (2) register
- * `https://<app-domain>/functions/commerce/payment-webhook` with Stripe for
- * `checkout.session.completed` — there is no signing secret to store, see
- * `parseWebhook` below — and (3) enable the `card` gateway
- * (`commerce/seed-store` with `payment_methods: ["offline", "card"]`), which is
- * what makes any of this visible at checkout.
+ * and **enable the `card` gateway** — `commerce/seed-store` with
+ * `payment_methods: ["offline", "card"]`. It ships disabled, so that is what
+ * makes card payment visible at checkout.
+ *
+ * That is the whole job. This file assumes the app is connected to Stripe and
+ * reads the secret key the connection publishes (`stripeSecret()` below); how
+ * the app gets connected is not this file's concern and nothing here needs
+ * filling in.
  *
  * NEVER patch this file (or the stub it replaces) with partial edits. A
  * find_replace that leaves the originals behind gives every commerce function a
@@ -56,10 +57,29 @@ export interface CardPaymentPage {
  * the secret answers a clean 503 at checkout instead of failing to boot every
  * commerce function that imports it.
  */
+/**
+ * Stripe's secret key, as published to the backend environment by the app's
+ * Stripe connection. The names below are the conventional ones; if the key
+ * arrives under a different name, this list is the only thing to change.
+ */
+const STRIPE_KEY_VARS = ["STRIPE_SECRET_KEY", "STRIPE_API_KEY", "STRIPE_KEY"];
+
+const stripeSecret = () => {
+  for (const name of STRIPE_KEY_VARS) {
+    const value = Deno.env.get(name);
+    if (value) return value;
+  }
+  return null;
+};
+
 const stripe = () => {
-  const key = Deno.env.get("STRIPE_SECRET_KEY");
+  const key = stripeSecret();
   if (!key) {
-    throw new HttpError(503, "Card payments are not configured — the STRIPE_SECRET_KEY secret is missing.", "no_card_payment_provider");
+    throw new HttpError(
+      503,
+      `Card payments are not configured — no Stripe secret key in the backend environment (looked for ${STRIPE_KEY_VARS.join(", ")}).`,
+      "no_card_payment_provider",
+    );
   }
   return new Stripe(key);
 };

package/base44/shared/commerce/card-payment.ts

@@ -11,7 +11,7 @@
  * NO PROVIDER SHIPS WITH THE TEMPLATE, and card payments are off by default
  * (the `card` gateway is seeded disabled) — this file stays stubs unless a
  * store deliberately opts into online cards. When one does, any provider
- * works: `.agents/skills/commerce/references/online-payments.md` has the
+ * works: the commerce skill's references/online-payments.md has the
  * rules, plus a complete Stripe implementation to paste over this file if
  * Stripe is the provider chosen. Another provider implements the same four
  * functions against its own API.

package/base44/shared/commerce/payments.ts

@@ -7,8 +7,8 @@
  * event). No provider ships with the template and the `card` gateway is
  * seeded disabled, so this half is dormant until a store opts into online
  * cards. Any provider works; the rules — and a complete Stripe
- * implementation, for that one common choice — are in
- * `.agents/skills/commerce/references/online-payments.md`.
+ * implementation, for that one common choice — are in the commerce skill's
+ * references/online-payments.md.
  *
  * Everything here — return URLs, storing the payment reference on the order,
  * idempotent confirmation that moves the order to processing, refund routing —

package/base44/shared/commerce/scan.ts

@@ -2,7 +2,7 @@
  * Full-collection scan helper. Base44's filter() is exact-match with a 5k page
  * cap and no total count, so server-side search/aggregation loops pages of 500.
  * Keep `cap` sane — reports over very large stores should move to a
- * materialized stats entity (see .agents/skills/commerce/references/operations.md).
+ * materialized stats entity (see the commerce skill's references/operations.md).
  */
 
 export interface ScanOpts {

package/base44/shared/commerce/sequence.ts

@@ -3,8 +3,8 @@
  *
  * NOTE ON CONCURRENCY: Base44 has no transactions, so nextOrderNumber() is a
  * read-max-then-increment and two simultaneous checkouts could race. The window
- * is tiny and order ids (not numbers) are the primary key; see
- * .agents/skills/commerce/references/operations.md for mitigations.
+ * is tiny and order ids (not numbers) are the primary key; see the commerce
+ * skill's references/operations.md for mitigations.
  */
 
 const ORDER_NUMBER_START = 1001;

package/package.json

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

package/scripts/install.js

@@ -203,7 +203,7 @@
     "  1. No deps to add: sonner, recharts and react-markdown ship with the default\n" +
     "     Base44 template — check package.json and npm i only what is truly missing\n" +
     '  2. Mount the admin router: <Route path="/store-admin/*" element={<AdminApp />} />\n' +
-    "     plus the mandatory /order-received route (<OrderReceivedBlock/>)\n" +
+    "     plus the mandatory /order-received route (useOrderReturn + your markup)\n" +
     "  3. Seed the store — one commerce/seed-store call (store_name required) takes the\n" +
     "     catalog, currency, shipping locations and payment methods\n" +
     "  4. CLI installs only: npx base44 agents push (the hosted runtime syncs agents on write)"

package/skills/commerce/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: commerce
-description: Base44 Commerce — commerce.* entities, commerce/* backend functions (storefront + admin APIs, payments, webhooks), the shared engine under base44/shared/commerce/, the Store Management UI at /store-admin, and the storefront hooks + UI blocks under src/commerce/. Read before working on store features: installing, building a storefront, seeding a catalog, shipping zones, payments, or the admin.
+description: Base44 Commerce — commerce.* entities, commerce/* backend functions (storefront + admin APIs, payments, webhooks), the shared engine under base44/shared/commerce/, the Store Management UI at /store-admin, and the headless storefront hooks under src/commerce/. Read before working on store features: installing, building a storefront, seeding a catalog, shipping zones, payments, or the admin.
 ---
 
 # Commerce
@@ -11,9 +11,19 @@ Nothing else in this skill needs to be open right now.
 The kit ships, already written and tested: 20 `commerce.*` entities, the
 `commerce/*` backend functions (storefront API, admin API, payments, webhooks,
 emails), the shared commerce engine, a complete admin back office at
-`/store-admin`, the `commerce/StoreAdmin` copilot, and the storefront's logic
-and commodity UI (`@/commerce/storefront`, `@/commerce/utils`). None of that
-costs you generation — your work is the *store*, not the plumbing.
+`/store-admin`, the `commerce/StoreAdmin` copilot, and the storefront's entire
+logic layer (`@/commerce/storefront`, `@/commerce/utils`). None of that costs
+you generation — your work is the store's *UI and data*, not the plumbing.
+
+**Paths in this skill.** Every skill file named anywhere — in these docs, in a
+checklist, in a code comment — is written **relative to this skill's folder**
+(`.agents/skills/commerce/` in an installed app). So `references/online-payments.md`
+means `.agents/skills/commerce/references/online-payments.md`, and
+`install/03-data.md` means `.agents/skills/commerce/install/03-data.md`. Resolve
+them from the skill folder, never from the directory of the file that mentioned
+them — a comment in `src/…` naming `install/03-data.md` is not
+`src/install/03-data.md`. (Markdown links between skill files are ordinary
+relative links and resolve as written.)
 
 ## Installing right now?
 
@@ -42,25 +52,25 @@ and each one says when a reference is genuinely needed.
   step, and the decision plus the timing live in
   [`install/03-data.md`](./install/03-data.md).
 
-## The storefront: two tiers
+## The storefront: logic is premade, UI never is
 
-**Identity surfaces are yours to design** — the home page, the collection grid,
-the product page's layout, the product card, the theme. That is where a brief
-like "make it feel like <site>" lives, and the kit deliberately ships no markup
-for it.
+**The UI is yours, all of it** — every page, element, class and word of copy,
+from the home page to the checkout's place-order button. That is where a brief
+like "make it feel like <site>" lives, and the kit deliberately ships **no
+markup and no CSS anywhere**: there are no premade components to drop in or
+restyle. You design the storefront the way you would any app.
 
-**Commodity surfaces ship as working blocks** that inherit your theme — checkout,
-cart lines, totals, the coupon field, reviews, order-received, and the product
-page's internals (variant selector, gallery, specs, breadcrumbs, product
-strips). Every store's version of these is functionally identical. Restyle them
-with your CSS, swap one region with `slots`, or drop to the hooks each block is
-built from when the design needs different structure — but never hand-roll their
-logic.
+**The logic ships as headless hooks** (`@/commerce/storefront`) — checkout
+repricing from the address, variant resolution, cart state, coupon redemption,
+review policies, order-return verification. Every store's version of these is
+functionally identical and hand-writing them is where storefront bugs cluster,
+so **never re-implement what a hook does**. Each hook returns a complete
+view-model — a `status` to branch on, ready-to-map arrays, handlers, error
+objects — that your markup renders:
 
 ```jsx
-import { CheckoutBlock } from "@/commerce/storefront";
-// the whole checkout page body:
-<main className="mx-auto max-w-3xl px-6 py-16"><CheckoutBlock /></main>
+import { useCart, CartLine, useTotalsLines } from "@/commerce/storefront";
+const { status, lines } = useCart();   // branch on status, map lines into YOUR rows
 ```
 
 The admin UI (`src/commerce/admin/`) is finished and **also yours to change** —
@@ -68,16 +78,16 @@ restyle it, add pages, rework flows. To understand the backend it talks to, read
 [`docs/api-admin.md`](./docs/api-admin.md).
 
 Four rules the API enforces — a storefront that skips them cannot complete a
-purchase. In a React app the blocks and hooks above already implement all four;
-the API-level statements are in
+purchase. In a React app the hooks implement all four; your markup just has to
+render what they hand back. The API-level statements are in
 [`docs/api-storefront.md`](./docs/api-storefront.md) for non-React clients:
 
 1. A product with variants needs **one selector per attribute**, resolved to a
-   `variation_id` (`<VariantSelectorBlock/>` / `useProduct`).
+   `variation_id` (`useProduct` + `variantAxes`).
 2. Checkout must **recalculate shipping from the address and send a choice**
-   (`<CheckoutBlock/>` / `useCheckout`).
+   (`useCheckout` — automatic).
 3. **`/order-received` must exist** and render the return state, including a
-   manual order's payment instructions (`<OrderReceivedBlock/>`).
+   manual order's payment instructions (`useOrderReturn`).
 4. **Never advertise what isn't configured** — no free-shipping banner without a
    real rate, no coupon codes without a field to redeem them in.
 
@@ -103,7 +113,7 @@ so you can answer "would that file help?" without paying for it.
 | [`references/catalog-rendering.md`](./references/catalog-rendering.md) | which fields each catalog call returns, variant edge cases | the install's product list/page chunks already render correct cards, prices and selectors | 12K |
 | [`references/shipping-and-tax.md`](./references/shipping-and-tax.md) | zones beyond the standard recipe, taxes, editing locations later | "€X in a region, €Y worldwide" is inline in `install/03-data.md` | 8K |
 | [`references/online-payments.md`](./references/online-payments.md) | the store opted into cards and you are wiring the provider **now** | the decision and its timing are in `install/03-data.md`; wiring Stripe is a one-file copy, not code to write | 9K |
-| [`references/reviews.md`](./references/reviews.md) | moderation, or a policy beyond the `policy` prop | `<ReviewsBlock/>` covers list + form + policies | 4K |
+| [`references/reviews.md`](./references/reviews.md) | moderation, or a policy beyond the `policy` prop | `useProductReviews` covers list + form + policies | 4K |
 | [`references/store-settings.md`](./references/store-settings.md) | changing store behavior through settings keys | the seeded defaults are right for a new store | 5K |
 | [`references/emails.md`](./references/emails.md) | order-email recipients, subjects, per-type overrides, the log | transactional emails already send | 5K |
 | [`references/admin-product-form.md`](./references/admin-product-form.md) | editing the shipped product editor | the editor works as shipped | 4K |
@@ -119,4 +129,4 @@ opened at the moment it is used. Open one reference when its task starts, take
 what you need, and when a stage's checklist passes, record that stage's
 carry-forward lines and treat the file as gone. If a reference and this map
 disagree, the reference wins — but if a *rule* appears in code (a hook's return
-value, a block's markup), the code wins over both.
+value, its doc comment), the code wins over both.

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

@@ -2,7 +2,7 @@
 
 The raw HTTP/SDK surface behind a customer-facing shopfront. **A React storefront should not call most of it directly** — `src/commerce/storefront/` ships the logic layer, and this file is the reference for what lies beyond it, for non-React and headless clients, and for the exact payloads and error codes.
 
-**Two tiers.** The *identity* surfaces — home, the collection grid, the product page's layout, the product card, the theme — are yours to design; build them on the hooks (`useProductList`, `useProduct`, `useProductPrice`, `useStorefrontSeo`). The *commodity* surfaces — checkout, cart, order-received, reviews, and the product page's internals — ship as **blocks** that inherit your theme (`CheckoutBlock`, `CartLinesBlock`, `TotalsBlock`, `CouponFieldBlock`, `OrderReceivedBlock`, `ReviewsBlock`, `VariantSelectorBlock`, …). Restyle or replace them; never hand-roll their logic. Framework-free helpers (API client, variant resolution, free-shipping rules) live in `src/commerce/utils/`.
+**Logic is premade, UI never is.** In a React app, every surface here has a headless hook in `@/commerce/storefront` — `useProductList`, `useProduct` (+ `variantAxes`, `useAddToCartButton`), `useCart`/`useCartLine`/`useCoupon`, `useCheckout` (+ `useAddressForm`, the pickers), `useOrderReturn`, `useProductReviews`, `useStorefrontSeo`. The hooks own the API calls and the branching below and hand you a view-model; **all markup and styling are yours** — nothing in the kit renders UI. Never hand-roll a hook's logic. Framework-free helpers (API client, variant resolution, price and totals rules, free-shipping rules) live in `src/commerce/utils/`.
 
 ## Contents
 
@@ -49,7 +49,7 @@ Four public functions — **`storefront-catalog`**, **`storefront-cart`**, **`st
 | **Digital products** | entitlement-checked downloads with remaining-count, expiry, signed URLs for private files | [`get-download`](#commercestorefront-account) |
 | **Store config** | currency, units, catalog/cart price display — honour it instead of hardcoding | [`get-store-info`](#get-store-info) |
 
-Not in the backend: the visitor UI (identity tier — yours; commodity tier — the blocks), and the card-payment provider integration, which only a store that opts into cards needs — cards are off by default, the decision and its timing live in [`../install/03-data.md`](../install/03-data.md), the provider code in [`../references/online-payments.md`](../references/online-payments.md). Payment methods and the currency are admin-owned data — always render them from `get-store-info`, never a hardcoded list, and format prices with `Intl.NumberFormat(undefined, { style: "currency", currency })`.
+Not in the backend: the visitor UI (all of it is yours — the hooks above carry the logic), and the card-payment provider integration, which only a store that opts into cards needs — cards are off by default, the decision and its timing live in [`../install/03-data.md`](../install/03-data.md), the provider code in [`../references/online-payments.md`](../references/online-payments.md). Payment methods and the currency are admin-owned data — always render them from `get-store-info`, never a hardcoded list, and format prices with `Intl.NumberFormat(undefined, { style: "currency", currency })`.
 
 ## Conventions
 
@@ -131,7 +131,7 @@ await cat({ category_id, sort: "popularity", per_page: 4 });    // top in catego
 ```
 **Errors:** `404 not_found` (missing / not published / hidden).
 
-> **`variations[]` is not a list of choices to show.** Build **one control per `product.attributes[]` entry** (Size, Color, …) — every attribute is an axis — and resolve the combination to a variation client-side; `add-item` needs that `variation_id`. Variant prices come from `variations[]`, never from `product.price` (the parent's price is a rolled-up from-price). A React page gets all of this from `useProduct` + `useAddToCart` (render `view.axes`, gate on `view.purchasable`) or `<VariantSelectorBlock/>`; a non-React client uses the framework-free resolver:
+> **`variations[]` is not a list of choices to show.** Build **one control per `product.attributes[]` entry** (Size, Color, …) — every attribute is an axis — and resolve the combination to a variation client-side; `add-item` needs that `variation_id`. Variant prices come from `variations[]`, never from `product.price` (the parent's price is a rolled-up from-price). A React page gets all of this from `useProduct` + `useAddToCartButton` (map `variantAxes(view, pick)` into your controls, gate on `view.purchasable`); a non-React client uses the framework-free resolver:
 > ```js
 > import { resolveSelection, defaultSelection, selectOption } from "@/commerce/utils";
 > const view = resolveSelection(product, variations, selection);  // selection from defaultSelection(), updated via selectOption()
@@ -159,7 +159,7 @@ No payload. Returns `{ "attributes": [ { ...attribute, "terms": [ ...values ] }
 ### `submit-review`
 **Payload:** `{ product_id, reviewer?, review, rating }`.
 
-> A React storefront gets the whole reviews surface — this call, the paginated list from `get-product`, refresh, and the store's moderation policy — from **`useProductReviews`** / **`<ReviewsBlock/>`**; don't hand-roll it. Read on for the raw contract.
+> A React storefront gets the whole reviews surface — this call, the paginated list from `get-product`, refresh, and the store's moderation policy — from **`useProductReviews`**; don't hand-roll it. Read on for the raw contract.
 
 **Public by default: anyone can review with an email address — no login.** A guest passes `email`; for a signed-in caller the session email always wins (the payload cannot impersonate). `reviewer` is the display name only, defaulting to the account's `full_name` then the email's local part. `rating` is optional (0–5). `verified` is derived from the email's order history. Status is `hold` unless `products.auto_approve_reviews` — the one server-side switch, so a hardcoded "awaiting approval" message is wrong when it is on. Stricter policies (login-gated, verified buyers only, rating required) are a `policy` option on the hook, not code you write: [`../references/reviews.md`](../references/reviews.md).
 
@@ -318,7 +318,7 @@ Separate function, same guest-bearer rule: `order_id` + `order_key` (an admin ma
 | `complete-return` | `{ order_id, order_key, payment?, return_url? }` | `{ state: "paid"\|"cancelled"\|"unpaid", paid, already_confirmed, status, order, payment_link, payment_instructions }` — the whole return flow in one call: confirms with the provider, progresses the order, adds a fresh `payment_link: { url, reference }` while a card order is unpaid, and re-supplies `payment_instructions: { type, description, account_details }` for unpaid **manual** orders so bank details render on every visit. `payment` is only a hint — a hand-edited `?payment=success` can never yield `paid`. **`order` carries flat totals** (`order.total`, `order.shipping_total`); there is no `order.totals` — that shape belongs to the cart view |
 | `verify` | `{ order_id, order_key }` | `{ paid, already_confirmed, status, order }` — the same confirmation without the render-ready extras. **Idempotent**; money is asked of the provider about the reference stored on the order |
 
-> **The `/order-received` route is mandatory** (requirement 4): without it a paying customer lands on a 404 *and* the order is never marked paid. It only has to call `complete-return` and render its three states — `<OrderReceivedBlock/>` / `useOrderReturn` do exactly that.
+> **The `/order-received` route is mandatory** (requirement 4): without it a paying customer lands on a 404 *and* the order is never marked paid. It only has to call `complete-return` and render its three states — `useOrderReturn` does exactly that (your markup renders the states, including `paymentInstructions`).
 
 Provider callbacks land on `commerce/payment-webhook` (server-to-server) — the second confirmation path, for buyers who pay and close the tab; whichever path runs second is a no-op. That function is premade (it verifies through the provider's API, so no signing secret). Wiring a provider: [`../references/online-payments.md`](../references/online-payments.md).
 
@@ -354,7 +354,7 @@ Two access modes: **auth** (Base44 session) or **`order_key` bearer** (guest tra
 
 ## Walkthrough A — guest checkout
 
-Raw-call sequence for a non-React client (a React app gets this from `useCart` + `CheckoutBlock`).
+Raw-call sequence for a non-React client (a React app gets this from `useCart` + `useCheckout`).
 
 ```js
 const inv = (fn, payload) => base44.functions.invoke(fn, payload).then(r => r.data.data);

package/skills/commerce/install/01-install.md

@@ -21,7 +21,7 @@ What lands in the app, how the admin gets mounted, and the order to do the rest
 | `base44/entities/commerce.*.jsonc` | 20 entity schemas, all admin-only RLS |
 | `base44/functions/commerce/` + `shared/` + `agents/` | 16 functions, the engine, the StoreAdmin copilot |
 | `src/commerce/admin/` | the finished admin app — **don't validate it, it ships tested** |
-| `src/commerce/storefront/` + `utils/` | the hooks and blocks you build against ([`./02-storefront.md`](./02-storefront.md)) |
+| `src/commerce/storefront/` + `utils/` | the headless hooks you build the storefront UI on ([`./02-storefront.md`](./02-storefront.md)) |
 | `.agents/skills/commerce/` | these docs |
 
 <details>
@@ -61,7 +61,7 @@ import { Navigate } from "react-router-dom";
 
 - **The `/*` splat is required.** The admin renders nested routes; a bare `path="/store-admin"` matches only the dashboard and every deeper link 404s. Mounting elsewhere: `<AdminApp basePath="/backoffice" />` — the prefix *without* the splat.
 - **Give `/` something.** A blank Base44 app has no `/` route, so after mounting only the admin the app's own URL renders "page not found", which reads exactly like a broken install. Redirect until the storefront exists.
-- **`/order-received` is mandatory**, even for a store that only ever takes offline payments. Every payment link (checkout, the admin's payment link, emails) returns there, and confirming is what marks an order paid — without the route a paying customer hits a 404 and the order stays unpaid. The page body is one block, `<OrderReceivedBlock />` ([`./02-storefront.md`](./02-storefront.md)). A different path must be set in Settings → General → *Payment return path*.
+- **`/order-received` is mandatory**, even for a store that only ever takes offline payments. Every payment link (checkout, the admin's payment link, emails) returns there, and confirming is what marks an order paid — without the route a paying customer hits a 404 and the order stays unpaid. The page is one hook, `useOrderReturn()`, plus your markup for its states ([`./02-storefront.md`](./02-storefront.md)). A different path must be set in Settings → General → *Payment return path*.
 
 ## Admin-role enforcement — do not weaken