@base44/app-plugin-commerce 0.1.17 → 0.1.19

package/README.md

@@ -8,7 +8,7 @@ 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).
-- **Online card payments, order side premade** — checkout routing, payment links for unpaid orders, two idempotent confirmation paths (customer return + webhook, both premade) and refund records are all built. Wiring a provider (Stripe, PayPal, a local PSP…) means implementing **four functions in one file** — `base44/shared/commerce/card-payment.ts` — and nothing else; a complete Stripe implementation to paste in ships in [`skills/commerce/post-installation.md`](./skills/commerce/post-installation.md) §4.2. **Cards are off by default**: the seed leaves the `card` gateway disabled and the manual `offline` method on — enable cards only with a provider wired, or about to be, or checkout answers `503 no_card_payment_provider` (§4.1 — the rule, plus when in a build to raise it). Every other payment option is manual (on-hold + instructions) and needs no code; the admin can add more in Settings → Payments. See [`skills/commerce/references/online-payments.md`](./skills/commerce/references/online-payments.md).
+- **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**. **No payment provider ships with the template.** 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 any provider (Stripe, PayPal, a local PSP…) by implementing **four functions in one file**, `base44/shared/commerce/card-payment.ts`, and nothing else; enable the gateway only with that done, or checkout answers `503 no_card_payment_provider`. The rule and timing: [`skills/commerce/post-installation.md`](./skills/commerce/post-installation.md) §4.1. Provider rules and a complete Stripe implementation to paste, for that one common choice: [`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/return-page calls); `variants.js` maps an attribute selection (Size, Color) onto a `ProductVariation` and back, plus per-option availability and variant price ranges; `shipping-promos.js` reads the store's real free-shipping configuration so "Free shipping over €150" copy states a configured rule rather than an invented number. See [`skills/commerce/references/storefront-product-page.md`](./skills/commerce/references/storefront-product-page.md).
@@ -102,7 +102,7 @@ If you build on Base44's hosted platform, use the Base44 agent/MCP to write the
 ## What's NOT included
 
 - **No visitor/storefront UI.** The storefront **API** is complete (`commerce/storefront-*` functions); building the shopfront is up to you — see [`skills/commerce/docs/api-storefront.md`](./skills/commerce/docs/api-storefront.md). What *does* ship for the storefront is **logic, not looks**: [`src/commerce/utils/`](./src/commerce/utils/) (framework-free API client + variant-selection functions — map a Size/Color selection to a `ProductVariation` and back, per-option availability, variant price ranges) and [`src/commerce/storefront/`](./src/commerce/storefront/) (React hooks + headless pickers for the shared cart, the guided checkout with automatic shipping/tax recalculation, and the `/order-received` page — no visual components), plus [`skills/commerce/references/product-render.md`](./skills/commerce/references/product-render.md) (what to render in a grid vs. a product page, and which fields each call returns) and [`skills/commerce/references/storefront-product-page.md`](./skills/commerce/references/storefront-product-page.md), the variant rules that go with the helpers.
-- **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` (Stripe: paste-in in `skills/commerce/post-installation.md` §4.2) 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/post-installation.md` §4.1.
+- **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` (rules + a Stripe implementation to paste: `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/post-installation.md` §4.1.
 - **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 *Scheduled work* in [`skills/commerce/SKILL.md`](./skills/commerce/SKILL.md).
 
 ## Next steps

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

@@ -8,9 +8,13 @@
  *   refundCardPayment    → admin refunds through the provider
  *   parseWebhook         → validate the provider's server-to-server event
  *
- * Any provider works; a ready-made reference implementation (Stripe) is in
- * `.agents/skills/commerce/post-installation.md` §4 to paste over this
- * file — another provider implements the same functions against its own API.
+ * 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
+ * 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.
  *
  * REPLACE THIS FILE WHOLE (one write of the full new content). Never
  * find_replace into these stubs: a partial patch leaves the originals behind

package/base44/shared/commerce/payments.ts

@@ -4,10 +4,10 @@
  * The provider-specific half lives in exactly ONE file an agent implements
  * when wiring a provider: `shared/commerce/card-payment.ts` — four functions
  * (create a payment page, check it was paid, refund it, validate a webhook
- * event). Any provider works;
- * a reference implementation (Stripe) is in
- * `.agents/skills/commerce/post-installation.md` §4, and the
- * provider-agnostic rules are in
+ * 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`.
  *
  * Everything here — return URLs, storing the payment reference on the order,

package/package.json

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

package/skills/commerce/SKILL.md

@@ -15,7 +15,7 @@ Operational guidance for extending, operating and building on the Base44 Commerc
 
 ## IMPORTANT — first-time installation
 
-If the template was just installed (or you are installing it right now), read [`.agents/skills/commerce/post-installation.md`](./post-installation.md) **before anything else — and, unless the user has a special requirement, read nothing else**: it alone covers embedding the admin pages, the three-layer admin-role enforcement (do not weaken), seeding the store's data — **one `commerce/seed-store` call takes the whole catalog** (products with attributes; variants, categories, ribbons and Shipping & Tax Locations created internally — §3) — **card payments as an optional, late step** (§4.1: off by default — the seed enables offline payment and leaves cards off; enable cards only with a provider wired or about to be, and raise it at the end of the install, never its start — then §4.2's complete Stripe implementation to paste over `shared/commerce/card-payment.ts`; the payment webhook is premade), and the **storefront quick start** (§2): logic-only chunks for product list → product page → optional cart → checkout. Its §0 schedules the whole install: **storefront components are written while image generation and the seed call (parallel writes — usually a few seconds) run — never after them, and never behind a payment-provider round-trip**. The references below and the API docs are for requests that go beyond that happy path, not for the install. The full install-from-scratch steps are in [`.agents/skills/commerce/installation-guidelines.md`](./installation-guidelines.md).
+If the template was just installed (or you are installing it right now), read [`.agents/skills/commerce/post-installation.md`](./post-installation.md) **before anything else — and, unless the user has a special requirement, read nothing else**: it alone covers embedding the admin pages, the three-layer admin-role enforcement (do not weaken), seeding the store's data — **one `commerce/seed-store` call takes the whole catalog** (products with attributes; variants, categories, ribbons and Shipping & Tax Locations created internally — §3) — **card payments as an optional, late step** (§4.1: off by default — the seed enables offline payment and leaves cards off; **no payment provider ships with the kit**, so cards mean deliberately wiring one, raised at the end of the install and never at its start; §4.2 is the four-step how-to, and the provider code itself lives in [`references/online-payments.md`](./references/online-payments.md) — read it only if the store opts in), and the **storefront quick start** (§2): logic-only chunks for product list → product page → optional cart → checkout. Its §0 schedules the whole install: **storefront components are written while image generation and the seed call (parallel writes — usually a few seconds) run — never after them, and never behind a payment-provider round-trip**. The references below and the API docs are for requests that go beyond that happy path, not for the install. The full install-from-scratch steps are in [`.agents/skills/commerce/installation-guidelines.md`](./installation-guidelines.md).
 
 ## Working on the UI
 
@@ -36,7 +36,7 @@ Agents keep shipping storefronts that miss these, and each one breaks buying out
 
 2. **Checkout must recalculate shipping from the address and send a choice.** `useCheckout` does all of it: it calls `set-shipping-address` automatically once the address is complete (recalculating options, cost and tax; `400 shipping_not_available` → its `addressError`), resolves `shipping_status`, and blocks `placeOrder` until the choice is made. Hand-rolled flows must do the same by hand: call `set-shipping-address` as soon as the customer provides an address, then read `shipping_status` on the returned cart — `auto_selected` (one option, already applied) · `chosen` · `choice_required` → **show `available_shipping_methods` and call `choose-shipping-method`** · `missing_address` → collect the address first (a single-location store shows its options even before one). `place-order` refuses with `400 shipping_method_required` until then — that is not a bug to work around. (`chosen_shipping_method` on the cart is the rate **id**, a string — display it by looking up its entry's `title`/`cost`, never by rendering the id.)
 
-3. **Handle card payments if the store offers them, and build `/order-received` either way.** Render whatever gateways `get-store-info` reports — a default-seeded store offers `offline` only (cards are off by default, and enabled only with a provider wired: [`post-installation.md` §4.1](./post-installation.md#41-off-by-default--enable-only-with-a-provider-wired)), so never hardcode a card option. Choosing the card gateway returns `payment.checkout_url` — `useCheckout().placeOrder` redirects there for you (until a payment provider is implemented — one file, Stripe paste-in in [`post-installation.md` §4](./post-installation.md#42-wiring-a-provider--one-file) — it answers `503 no_card_payment_provider`; offer the other methods). Every payment link comes back to `/order-received`, which **you must implement**: one `useOrderReturn()` call rendered by `status` (hand-rolled: `commerce/payments` `complete-return` with the query params). Without that page a customer pays into a 404 and the order is never marked paid. Also persist the `cart_token` from **every** cart response (the provider/client do this) — `add-item` silently starts a fresh cart when the stored token is stale.
+3. **Handle card payments if the store offers them, and build `/order-received` either way.** Render whatever gateways `get-store-info` reports — a default-seeded store offers `offline` only (cards are off by default, and enabled only with a provider wired: [`post-installation.md` §4.1](./post-installation.md#41-off-by-default--enable-only-with-a-provider-wired)), so never hardcode a card option. Choosing the card gateway returns `payment.checkout_url` — `useCheckout().placeOrder` redirects there for you (with no provider implemented — one file, [`post-installation.md` §4.2](./post-installation.md#42-wiring-a-provider--one-file) — it answers `503 no_card_payment_provider`; offer the other methods). Every payment link comes back to `/order-received`, which **you must implement**: one `useOrderReturn()` call rendered by `status` (hand-rolled: `commerce/payments` `complete-return` with the query params). Without that page a customer pays into a 404 and the order is never marked paid. Also persist the `cart_token` from **every** cart response (the provider/client do this) — `add-item` silently starts a fresh cart when the stored token is stale.
 
 4. **Never advertise what isn't configured — and never configure what can't be reached.** "Free shipping over €150" must come from a real shipping rate that is free or carries a `free_over` threshold on a Shipping & Tax Location. Locations are admin-only data, so a storefront cannot read them: the live answer is the cart's `available_shipping_methods` after the address is set, and `shipping-promos.js` normalizes the rules wherever the records *are* in hand. No rule means no banner. **Coupons are the same rule in reverse:** codes are admin-only data that a customer can only use by typing them, so a store with coupons needs a code field — `useCart().applyCoupon`, in the cart or, when there's no cart page, in the checkout — rendering `discount_total` and invalid codes inline. No field means no coupons: don't seed them, don't name a code in the copy ([`post-installation.md` §2.3/§2.4](./post-installation.md#23-cart)).
 
@@ -57,7 +57,7 @@ Open the matching file under `.agents/skills/commerce/references/` only when a t
 | Variant selection | attribute-level selectors, resolving a selection to a variation, availability states, incomplete-selection pricing, add-to-cart contract | [`references/storefront-product-page.md`](./references/storefront-product-page.md) |
 | Reviews | stars on cards and the product page, the review list + submit form (public by email, backend ships complete), the auto-approve toggle, UI-enforced policies (login-gated, verified-only, required rating) | [`references/reviews.md`](./references/reviews.md) |
 | Admin product form | changing the product editor — its stacked sections are **Price & Inventory** (tax group, then the attributes, then a row per variant, or a single *Base price* row when there are none), **Modifiers** (`meta_data`), **Downloads**, **Linked products**; one **Visible** toggle drives `status`. Variants reconcile from the attribute values automatically: no generate step, no per-variant delete. Weight and dimensions are per variant. | [`references/admin-product-form.md`](./references/admin-product-form.md) |
-| Online payments | **any storefront or checkout work** — the order side (checkout, confirmation, payment links, refund records) *and* the payment webhook are premade; wiring a provider means implementing the four functions in one file (`shared/commerce/card-payment.ts`; Stripe = paste [`post-installation.md` §4](./post-installation.md#42-wiring-a-provider--one-file)) | [`references/online-payments.md`](./references/online-payments.md) |
+| Online payments | a store that has **opted into card payments** (they are off by default and no provider ships) — the order side (checkout, confirmation, payment links, refund records) *and* the payment webhook are premade; wiring a provider means implementing the four functions in one file (`shared/commerce/card-payment.ts`), and this reference holds the rules plus a complete Stripe implementation | [`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) |

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

@@ -16,7 +16,8 @@ Two access styles. **Reads are direct** entity SDK calls; **mutations with side
 | commerce.ProductReview | direct | **`commerce/admin-reviews`** | rating recalculation |
 | commerce.ProductCategory, commerce.ProductRibbon | direct | **direct CRUD**, or `commerce/admin-products` `save-term`/`delete-term`/`list-terms` (the API/agent path) | category slug uniqueness; ribbon get-or-create by name |
 | commerce.ProductAttribute, commerce.ProductAttributeTerm | direct | **direct CRUD**, or `commerce/admin-products` `save-term`/`delete-term`/`list-terms` (the API/agent path) | attribute `code` uniqueness; value rename rewrites products; attribute delete cascades its values |
-| commerce.ShippingTaxLocation, commerce.PaymentGateway | direct | **direct CRUD** | config; consumed by the pricing engine at read time |
+| commerce.ShippingTaxLocation | direct | **direct CRUD** | config; consumed by the pricing engine at read time |
+| commerce.PaymentGateway | direct | **`commerce/seed-store`** `payment_methods` to switch methods on/off; **direct CRUD** to change a record (add or rename a manual option, its `description`, bank accounts, `order`) | one seed call converges every gateway row to the given set, so "enable cards", "card-only" and "offline-only" are one idempotent call; the record's own fields are ordinary config — the admin's Settings → Payments screen edits them directly |
 | 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 |

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

@@ -36,7 +36,7 @@ The backend is considerably richer than a minimal "grid → cart → pay" shop.
 | **Digital products** | entitlement-checked downloads with remaining-count, expiry, and signed URLs for private files | [`get-download`](#commercestorefront-account) |
 | **Store config** | currency (format it with `Intl.NumberFormat`), units, catalog/cart price display — read it and honour it instead of hardcoding | [`get-store-info`](#get-store-info) |
 
-Two things that are **not** in the backend and are yours to build: the visitor UI itself, and the payment provider integration — four functions in one file (Stripe = paste [`post-installation.md` §4](../post-installation.md#42-wiring-a-provider--one-file); other providers: [`references/online-payments.md`](../references/online-payments.md)). Payment methods and the currency are admin-owned data — always render them from `get-store-info` rather than a hardcoded list, and format prices with `Intl.NumberFormat(undefined, { style: "currency", currency })`.
+Two things that are **not** in the backend and are yours to build: the visitor UI itself, and — only for a store that opts into card payments, which are off by default with no provider shipped — the payment provider integration: four functions in one file ([`post-installation.md` §4.2](../post-installation.md#42-wiring-a-provider--one-file) for the steps, [`references/online-payments.md`](../references/online-payments.md) for the provider code). Payment methods and the currency are admin-owned data — always render them from `get-store-info` rather than a hardcoded list, and format prices with `Intl.NumberFormat(undefined, { style: "currency", currency })`.
 
 ## Conventions
 
@@ -89,6 +89,20 @@ Each row is the product record (minus paywalled fields) **plus a resolved `ribbo
 
 **Filters stack.** `category_id`, `ribbon_id`, `attribute_id` + `attribute_term`, `min_price`/`max_price`, `on_sale`, `featured` and `in_stock_only` are ANDed, so "Dresses + gift + on sale" is one request. Build the controls from [`list-categories`](#list-categories), [`list-ribbons`](#list-ribbons) (its `count` gives you "Gift (12)") and [`list-attributes`](#list-attributes), and mirror active filters into the URL so a filtered listing is shareable and survives reload.
 
+**The same call also serves a short strip anywhere else** — a homepage hero or banner, a "featured" row, a "new in" rail, related picks beside an article. `per_page` bounds the result and the filters/sort choose what lands in it, so a small curated slice is one request; there is no separate endpoint, and no reason to fetch a big page and slice it client-side. Available if a page wants one:
+
+```js
+const inv = (fn, payload) => base44.functions.invoke(fn, payload).then(r => r.data.data);
+const cat = (payload) => inv("commerce/storefront-catalog", { action: "list-products", ...payload });
+
+const { products: featured } = await cat({ featured: true, per_page: 4 });
+const { products: newest }   = await cat({ sort: "-created_date", per_page: 6 });
+const { products: deals }    = await cat({ on_sale: true, in_stock_only: true, per_page: 4 });
+const { products: topInCat } = await cat({ category_id, sort: "popularity", per_page: 4 });
+```
+
+`featured` is the admin's own per-product flag (the star in the products list, *Featured product* in the editor's Publish box; `commerce/seed-store` accepts `featured: true` per product), so a featured strip is curated store data rather than slugs pinned in the UI. Rows are the ordinary listing rows — same fields a grid card renders ([`../references/product-render.md`](../references/product-render.md)). **A filter may legitimately match nothing** (no product starred, nothing discounted), so drive the block off the returned array's length — hide it or fall back to another slice — instead of assuming rows came back; `has_next` tells you whether a "see all" link has more behind it.
+
 ### `get-product`
 **Payload:** `{ id }` **or** `{ slug }`; optional `reviews_page` (1), `reviews_per_page` (10, max 50).
 

package/skills/commerce/post-installation.md

@@ -1,10 +1,10 @@
 # Post-installation
 
-What to do right after the static installation ([`installation-guidelines.md`](./installation-guidelines.md)): embed the admin pages into the app, build the storefront from the quick start below, and seed the store's data. Online card payments are **optional and off by default** — [§4](#4-payments--optional-per-store-one-file-when-needed-stripe-as-the-reference) has the rule (enable them only with a provider wired) and the wiring; they are never the opening move. Installed into the app at `.agents/skills/commerce/post-installation.md`.
+What to do right after the static installation ([`installation-guidelines.md`](./installation-guidelines.md)): embed the admin pages into the app, build the storefront from the quick start below, and seed the store's data. Online card payments are **optional and off by default** — [§4](#4-payments--optional-cards-off-by-default) has the rule (enable them only with a provider wired) and the wiring; they are never the opening move. Installed into the app at `.agents/skills/commerce/post-installation.md`.
 
-> **This file is intentionally the whole job.** Unless the user has a special requirement (a non-Stripe payment provider, signature-verified webhooks, filters/reviews/accounts beyond the happy path), do **not** open the `references/` guides or the `docs/` API references — everything needed to ship a working store (admin mount, the storefront — catalog pages, optional cart, checkout, order-received — seeding, and card payments for the stores that need them) is on this page, ending with the [Done when](#5-done-when) checklist. Reading more first just burns time.
+> **This file is intentionally the whole job.** Unless the user has a special requirement (wiring a card payment provider, signature-verified webhooks, filters/reviews/accounts beyond the happy path), do **not** open the `references/` guides or the `docs/` API references — everything needed to ship a working store (admin mount, the storefront — catalog pages, optional cart, checkout, order-received — seeding, and card payments for the stores that need them) is on this page, ending with the [Done when](#5-done-when) checklist. Reading more first just burns time.
 
-> **Payments, in short** (full rules in [§4](#4-payments--optional-per-store-one-file-when-needed-stripe-as-the-reference)): **online card payments are optional and off by default.** The seed enables the manual `offline` method, which needs no code or credentials, and leaves the `card` gateway disabled. **Enable cards only if you wire a payment provider — or are about to, in the same stretch of work** (§4.2: one file): an enabled card option with no provider behind it answers `503 no_card_payment_provider` at checkout. Choosing to add cards is fine and often right; just do it **late** — nothing else depends on it, so unless the user brought it up first, asking for a provider key before their store exists only stalls the build.
+> **Payments, in short** (full rules in [§4](#4-payments--optional-cards-off-by-default)): **online card payments are optional and off by default.** The seed enables the manual `offline` method, which needs no code or credentials, and leaves the `card` gateway disabled. **Enable cards only if you wire a payment provider — or are about to, in the same stretch of work** (§4.2: one file): an enabled card option with no provider behind it answers `503 no_card_payment_provider` at checkout. Choosing to add cards is fine and often right; just do it **late** — nothing else depends on it, so unless the user brought it up first, asking for a provider key before their store exists only stalls the build.
 
 ## 0. Sequencing — build the UI while the slow work runs
 
@@ -64,17 +64,35 @@ Even if the client guard were bypassed, layers 2 and 3 keep the store data safe.
 
 No visitor UI ships — and no visual component ships either: **every pixel of the shopfront stays yours to design**. What ships is the logic: the storefront **API**, the framework-free helpers in `@/commerce/utils`, and the React layer in `@/commerce/storefront` — hooks and headless pickers owning the contracts every store must get right. The catalog views (§2.1–2.2) are deliberately the thinnest, because that is where storefronts differ most; the cart and checkout (§2.3–2.4) are more guided, because shipping recalculation, payment methods and the place-order gate work the same in every store. **None of it waits on anything**: every shape you build against is documented right here, so seeding (§3) runs in parallel with building these pages (§0 has the schedule) — kick off image generation, write the storefront while it renders, seed when the URLs are back. Live data is only needed once, to see real products on the finished pages. **Payments are not a prerequisite for any of this** — the whole buy path down to `place-order` is built and reviewable before a provider exists (a card gateway with no provider simply answers `503 no_card_payment_provider`, and §2.4 shows the graceful fallback), which is why the payment decision comes after these pages work, not before (§4). The four chunks below are the whole happy path; open [`docs/api-storefront.md`](./docs/api-storefront.md) only for what's beyond them (attribute/price filters, reviews, customer accounts, refunds), and [`references/product-render.md`](./references/product-render.md) for which fields belong in which view.
 
-**Set up once** — mount the provider above every storefront route. It owns the shared API client, the store-info cache and ONE shared cart, so a header badge, a cart drawer and the checkout all render the same state:
+**Set up once** — mount the provider **around `<Routes>`**, so it sits above every storefront route. It owns the shared API client, the store-info cache and ONE shared cart, so a header badge, a cart drawer and the checkout all render the same state:
 
 ```jsx
 import { StorefrontProvider } from "@/commerce/storefront";
 import { base44 } from "@/api/base44Client";
-
-<StorefrontProvider base44={base44}>
-  {/* storefront routes */}
-</StorefrontProvider>
+import AdminApp from "@/commerce/admin";
+
+<BrowserRouter>                             {/* the app's existing router, wherever it lives */}
+  <StorefrontProvider base44={base44}>      {/* wraps the router's <Routes>, not a child of it */}
+    <Routes>                                {/* ONE <Routes> — merge storefront routes into the app's */}
+      <Route path="/" element={<Home />} />
+      <Route path="/product/:slug" element={<ProductPage />} />
+      <Route path="/checkout" element={<Checkout />} />
+      <Route path="/order-received" element={<OrderReceived />} />
+      <Route path="/store-admin/*" element={<AdminApp />} />
+    </Routes>
+  </StorefrontProvider>
+</BrowserRouter>
 ```
 
+> ⚠ **`<Routes>` accepts only `<Route>` children — the provider goes outside it.** Nesting it inside (the natural reading of "wrap the storefront routes", and the usual mistake) throws at render: `Error: [StorefrontProvider] is not a <Route> component. All component children of <Routes> must be a <Route> or <React.Fragment>`. Wrapping the whole `<Routes>` as above is the simplest correct shape and fine even with the admin route inside — the admin doesn't use the storefront hooks. Same rule per file: an app that already has a `<Routes>` gets the new pages **added to it**, never a second `<Routes>` block. To scope the provider to storefront routes only, use a pathless **layout route** — the one place a wrapper component is legal — and render `<Outlet />` inside it:
+> ```jsx
+> <Route element={<StorefrontProvider base44={base44}><Outlet /></StorefrontProvider>}>
+>   <Route path="/" element={<Home />} />          {/* these share one cart */}
+>   <Route path="/checkout" element={<Checkout />} />
+> </Route>
+> <Route path="/store-admin/*" element={<AdminApp />} />   {/* outside the provider */}
+> ```
+
 The provider owns the two things hand-rolled storefronts keep getting wrong, so **don't reimplement either — and never mount a second provider or create a second client**: the **`cart_token` lifecycle** (sent with every cart/checkout call, re-persisted from every response — a stale token silently starts a fresh cart; rolling 48 h expiry; cleared when checkout consumes the cart) and the **store-info cache** (`payment_gateways`, currency, countries live **only** on `get-store-info` — the cart view never carries them). Inside the tree, `useStorefront()` returns the shared client for catalog calls, and `store.inv(fn, payload)` on it is the raw escape hatch (it unwraps the `{ success, data }` envelope). If non-React code also needs the client, create it once in `src/lib/storefront.js` (`createStorefront(base44)` from `@/commerce/utils`) and pass that same instance via `<StorefrontProvider store={store}>`.
 
 **What each hook / client method resolves to** — every envelope is already unwrapped, so take these shapes at face value (no `.data`, and no `.categories` on a list result):
@@ -111,6 +129,19 @@ const { products, page, per_page, has_next } = await store.listProducts({
 
 Each row is a full product record — for a card use `name`, `images[0]?.src` (**may be empty — render a placeholder, never a broken `<img>`**), `price`, `regular_price`, `on_sale` (sale badge), `short_description`, `stock_status`, `average_rating`/`rating_count` (stars cost no extra call) and `ribbons` (`[{ id, name }]`, may be absent — labels like "Best Seller" for the card corner). **There is no product type flag**: `product.attributes?.length > 0` means the product sells variants and its `price` is a *from*-price rolled up from the cheapest variant — render it as "From …". Categories for the nav come from `store.listCategories()` — an **array** of root categories with subcategories nested under `children` (map over it directly; there is no `{ categories }` wrapper on the result). That is the whole card — no other call or reference needed for the list view.
 
+**A short strip of products is the same call with a small `per_page`.** Products are not confined to the grid — a homepage hero or banner, a "featured" row, a "new in" rail, a few picks beside an article are all one `listProducts` call: `per_page` bounds how many come back and the filters/sort decide which ones. No separate endpoint, and never fetch a big page to slice client-side. Use this if a page of yours wants such a strip; the catalog pages above are complete without one:
+
+```js
+const { products: featured } = await store.listProducts({ featured: true, per_page: 4 });
+const { products: newest }   = await store.listProducts({ sort: "-created_date", per_page: 6 });
+const { products: deals }    = await store.listProducts({ on_sale: true, per_page: 4 });
+const { products: topInCat } = await store.listProducts({ category_id, sort: "popularity", per_page: 4 });
+// filters stack (featured + category_id + in_stock_only …); sort: -created_date | name |
+//   price | -price | popularity | rating. Rows are the same shape the cards above render.
+```
+
+`featured` is the merchant's own flag — the star in the admin's product list and *Featured product* in the editor's Publish box — and `seed-store` accepts `featured: true` per product, so such a row stays curated store data instead of a hardcoded list of slugs. **Any filter can legitimately match nothing** (nobody has starred a product, nothing is discounted): render the block from the returned array's length — hide it, or fall back to another slice — rather than assuming rows came back.
+
 **Carry forward:** each card links to the product page by **`slug`**.
 
 ### 2.2 Product page — variant selection included
@@ -397,7 +428,7 @@ A successful response means the data is in — the catalog and settings are live
 
 ---
 
-## 4. Payments — optional per store; one file when needed (Stripe as the reference)
+## 4. Payments — optional; cards off by default
 
 The order side of payments is **already implemented** (checkout routing, confirmation, payment links, refund records). The `offline` gateway — and any option the admin adds in Settings → Payments — works with nothing to configure: the order goes on-hold with the option's description as instructions.
 
@@ -407,7 +438,7 @@ The order side of payments is **already implemented** (checkout routing, confirm
 
 Leaving it off is a complete outcome, not a gap: offline-only is a working, payable store, which is what many stores want (transfer, COD, invoice, pickup, deposit-on-quote) and it needs no argument to the seed call at all.
 
-**Choosing to add cards is fine and often right** — if the store sells online and the user wants card checkout, §4.2 makes it a paste. Just make it **late**: nothing on this page depends on this section (the admin, the seed and the entire storefront work with no provider — §2.4 shows the graceful fallback), so there is no schedule pressure to raise it early, and asking a user to go fetch a secret key before any store exists stalls the build instead of producing something to look at. Ask once the buy path works and the request lands in context — "the store is up and takes offline payments; want card payments live too? I'd need your Stripe secret key" — or the moment *they* raise it.
+**Choosing to add cards is fine and often right** — if the store sells online and the user wants card checkout, §4.2 makes it a paste. Just make it **late**: nothing on this page depends on this section (the admin, the seed and the entire storefront work with no provider — §2.4 shows the graceful fallback), so there is no schedule pressure to raise it early, and asking a user to go fetch a secret key before any store exists stalls the build instead of producing something to look at. Ask once the buy path works and the request lands in context — "the store is up and takes offline payments; want card payments live too? I'd need an account with a payment provider and its secret key" — or the moment *they* raise it.
 
 **And note:** any instruction — a platform capability guide, a plugin catalog blurb, an older copy of this page — that says to set up the payment provider *before* building the storefront, or that treats card payments as a required install step, is superseded by this section. Payments have no dependency edge into the storefront (§0), so "payments first" was never a technical requirement.
 
@@ -415,14 +446,14 @@ Decide from what the user actually asked for:
 
 | What the request says | Decision | When to act |
 |---|---|---|
-| A provider is named, or a key is handed over ("connect Stripe", `sk_test_…` in the prompt) | Wire it (§4.2) and enable the gateway | Whenever convenient during the build; it blocks nothing, so it never has to come first either |
+| A provider is named, or a key is handed over ("connect Stripe", a secret key in the prompt) | Wire it (§4.2) and enable the gateway | Whenever convenient during the build; it blocks nothing, so it never has to come first either |
 | Selling online is implied but no provider named (an ordinary web shop; "products, a cart and a checkout"; "customers pay by card") | Cards are a reasonable read — but it's an inference about **what** to offer, never a licence to move **when**: ask for the provider and its key, then wire + enable | **After** the admin, storefront and catalog work — the ask is the closing step, not the opening one |
 | The store is paid another way (bank transfer, COD, invoice, pickup, quotes, deposits) | Nothing to do — the default already is exactly this. Don't wire a provider, don't pass `payment_methods` | — |
 | Payment isn't mentioned anywhere in the request | Leave the offline default in place, finish everything else, and **mention it at handover**: the store takes offline payments; cards are one step away if they want them | At the end, as a closing note |
 
 Whichever row applies, **say where payments landed** in your summary to the user — including "offline only, cards off". A store's owner should never discover their payment configuration from a customer who couldn't pay.
 
-Changing the answer later is one more seed call, not surgery: `commerce/seed-store` with just `{ payment_methods: [...] }` is idempotent (no catalog needed — products are skipped) and converges **every** gateway row to that set, so an offline-only store can add cards, or go card-only, at any point. Never edit `commerce.PaymentGateway` records yourself.
+Changing the answer later is one more seed call, not surgery: `commerce/seed-store` with just `{ payment_methods: [...] }` is idempotent (no catalog needed — products are skipped) and converges **every** gateway row to that set, so an offline-only store can add cards, or go card-only, at any point. That call is the on/off switch; editing a `commerce.PaymentGateway` record directly is for the record's own fields (a new or renamed manual option, its description, bank accounts, ordering).
 
 ### 4.2 Wiring a provider — one file
 
@@ -435,121 +466,16 @@ Changing the answer later is one more seed call, not surgery: `commerce/seed-sto
 | `refundCardPayment` | admin refunds with `refund_payment: true` |
 | `parseWebhook` | webhook validation — names the order the event is about; `paid: true` only after signature verification, never from a raw body |
 
-**Stripe is the reference implementation** and ships ready to use — don't write the file yourself; overwrite `base44/shared/commerce/card-payment.ts` with this as-is, **as one whole-file write. Never `find_replace` into the stub**: a partial patch leaves the original stubs behind and breaks every commerce function's deploy with duplicate-export bundle errors (`Multiple exports with the same name "createCardPayment"` → rewrite the file whole). For another provider, implement the same four functions against its API instead (same shape: hosted page in, paid-check and refund by `reference`, event naming an order — rules in [`references/online-payments.md`](./references/online-payments.md)):
-
-```ts
-// base44/shared/commerce/card-payment.ts — Stripe implementation
-import Stripe from "npm:stripe@18";
-import { HttpError } from "./auth.ts";
-
-export interface CardPaymentPage {
-  url: string;        // where the customer goes to pay
-  reference: string;  // the provider's id for this payment, stored on the order
-}
-
-const stripe = () => {
-  const key = Deno.env.get("STRIPE_SECRET_KEY");
-  if (!key) {
-    throw new HttpError(503, "Card payments are not configured — the STRIPE_SECRET_KEY secret is missing.", "no_card_payment_provider");
-  }
-  return new Stripe(key);
-};
-
-// Stripe amounts are in minor units; these currencies have none.
-const ZERO_DECIMAL = new Set(["BIF","CLP","DJF","GNF","JPY","KMF","KRW","MGA","PYG","RWF","UGX","VND","VUV","XAF","XOF","XPF"]);
-const minorUnits = (amount: number, currency: string) =>
-  Math.round(Number(amount) * (ZERO_DECIMAL.has(String(currency).toUpperCase()) ? 1 : 100));
-
-export async function createCardPayment(
-  _sr: any,
-  order: any,
-  opts: { successUrl: string; cancelUrl: string; customerEmail?: string },
-): Promise<CardPaymentPage> {
-  // order_id + order_key in the metadata is how the premade payment-webhook
-  // names the order when Stripe's event arrives — keep it on both objects.
-  const metadata = { order_id: String(order.id), order_key: String(order.order_key) };
-  const session = await stripe().checkout.sessions.create({
-    mode: "payment",
-    line_items: [{
-      quantity: 1,
-      price_data: {
-        currency: String(order.currency || "USD").toLowerCase(),
-        product_data: { name: `Order #${order.order_number}` },
-        unit_amount: minorUnits(order.total, order.currency),
-      },
-    }],
-    customer_email: opts.customerEmail || undefined,
-    metadata,
-    payment_intent_data: { metadata },
-    success_url: opts.successUrl,
-    cancel_url: opts.cancelUrl,
-  });
-  if (!session.url) throw new HttpError(502, "Stripe did not return a payment page URL.", "payment_session_failed");
-  return { url: session.url, reference: session.id };
-}
-
-export async function checkCardPaymentPaid(_sr: any, order: any, reference: string): Promise<boolean> {
-  const session = await stripe().checkout.sessions.retrieve(reference);
-  // The payment must be for THIS order — stops a reference to some other
-  // (paid) session being replayed against a different order.
-  return session.payment_status === "paid" && session.metadata?.order_id === String(order.id);
-}
-
-export async function refundCardPayment(_sr: any, _order: any, opts: {
-  reference: string; amount: number; currency: string; reason?: string;
-}): Promise<{ refund_id: string }> {
-  const session = await stripe().checkout.sessions.retrieve(opts.reference);
-  if (!session.payment_intent) {
-    throw new HttpError(409, "This payment has no charge to refund at Stripe.", "no_charge_to_refund");
-  }
-  const refund = await stripe().refunds.create({
-    payment_intent: String(session.payment_intent),
-    amount: minorUnits(opts.amount, opts.currency),
-  });
-  return { refund_id: refund.id };
-}
-
-/** What parseWebhook distills an event into — the premade webhook's contract. */
-export interface CardWebhookEvent {
-  order_id: string;
-  order_key: string;
-  paid: boolean;       // true only after signature verification — never from a raw body
-  reference?: string;  // only if signature-verified; otherwise the order's stored reference is used
-}
-
-/**
- * Stripe webhook events. The event body is never trusted: this only names
- * the order (from the metadata createCardPayment attached) and returns
- * paid: false, so the premade webhook verifies against Stripe's API through
- * checkCardPaymentPaid — a forged call can never mark an order paid, and no
- * signing secret is needed. (Optional fast path that skips the API
- * round-trip: verify the signature instead — references/online-payments.md.)
- */
-export async function parseWebhook(_req: Request, payload: string): Promise<CardWebhookEvent | null> {
-  let event: any;
-  try { event = JSON.parse(payload); } catch { return null; }
-  const metadata = event?.data?.object?.metadata;
-  if (!metadata?.order_id || !metadata?.order_key) return null;
-  return { order_id: String(metadata.order_id), order_key: String(metadata.order_key), paid: false };
-}
-```
+Four steps, whichever provider it is:
 
-Then three steps and payments are done (every provider follows this same shape — an API-credential secret, the premade webhook URL registered, and the gateway switched on; only the Stripe specifics below vary):
-
-1. **Secret**: ask the user for their Stripe **secret key** and store it as the `STRIPE_SECRET_KEY` app secret (backend env — never in code, never in an entity). Test keys (`sk_test_…`) work end to end. This is the only step that needs the user, so it sets the timing of the whole section (§4.1): ask when the store is standing, not in the install's first message — and if the answer takes a while, keep the rest of the work moving rather than idling on it.
-2. **Webhook endpoint** — so orders are confirmed even when the buyer pays and closes the tab: register `https://<app-domain>/functions/commerce/payment-webhook` with Stripe for the `checkout.session.completed` event. There is **no signing secret to store** — events are treated as nudges and verified against Stripe's API. Registration is one call with the same secret key (or the user can do it in the Stripe dashboard):
-
-   ```js
-   await fetch("https://api.stripe.com/v1/webhook_endpoints", {
-     method: "POST",
-     headers: { Authorization: `Bearer ${Deno.env.get("STRIPE_SECRET_KEY")}`, "Content-Type": "application/x-www-form-urlencoded" },
-     body: new URLSearchParams({ url: "https://<app-domain>/functions/commerce/payment-webhook", "enabled_events[]": "checkout.session.completed" }),
-   });
-   ```
+1. **Implement the four functions** in `base44/shared/commerce/card-payment.ts` against the provider's API. **No provider ships with the template** — the file arrives as stubs, and [`references/online-payments.md`](./references/online-payments.md) holds the per-provider rules plus a complete **Stripe** implementation to paste if Stripe is the provider the store chose. Write the file **whole, in one write. Never `find_replace` into the stubs**: a partial patch leaves the originals behind and breaks every commerce function's deploy with duplicate-export bundle errors (`Multiple exports with the same name "createCardPayment"` → rewrite the file whole).
+2. **Store the provider's API credential as a backend app secret** (read with `Deno.env.get(...)` — never in code, never in an entity). Test credentials work end to end. This is the only step that needs the user, so it sets the timing of the whole section (§4.1): ask when the store is standing, not in the install's first message — and if the answer takes a while, keep the rest of the work moving rather than idling on it.
+3. **Register the premade webhook URL** — `https://<app-domain>/functions/commerce/payment-webhook` — with the provider, for its "payment succeeded" event, so orders are confirmed even when the buyer pays and closes the tab. There is **no signing secret to store**: events are treated as nudges and verified against the provider's API. (Per-provider registration calls are in the reference; the user can also do it in the provider's dashboard.)
+4. **Enable the gateway** — the `card` row is seeded **off** (§4.1), so the file alone changes nothing a customer sees. **Turning a method on or off is the seed call:** `commerce/seed-store` with `{ payment_methods: ["offline", "card"] }` (or `["card"]` for card-only) — safe on a seeded store (no catalog needed, products are skipped), idempotent, and it converges every gateway row to that set, so the same call also goes card-only or switches cards back off later. Reach for direct CRUD on `commerce.PaymentGateway` when the **record itself** needs changing — adding a new manual option, renaming one, editing its description or bank accounts, reordering them — which is what the admin's Settings → Payments screen does.
 
-3. **Enable the gateway** — the `card` row is seeded **off** (§4.1), so the file alone changes nothing a customer sees. Call `commerce/seed-store` with `{ payment_methods: ["offline", "card"] }` (or `["card"]` for card-only) — safe on a seeded store: no catalog needed, products are skipped, and it converges every gateway row to that set. Skipping this step is the usual reason a freshly wired provider "doesn't show up at checkout"; doing it *without* steps 1–2 is what produces `503 no_card_payment_provider`.
+   Skipping this step is the usual reason a freshly wired provider "doesn't show up at checkout"; doing it *without* steps 1–2 is what produces `503 no_card_payment_provider`.
 
-That's it — checkout redirect, `/order-received` confirmation, the webhook, the admin's "Check payment" button, payment links and provider refunds all run through this one file. **Nothing else to read or edit**: [`references/online-payments.md`](./references/online-payments.md) is only for *other* providers or signature-verified webhooks.
+That's it — checkout redirect, `/order-received` confirmation, the webhook, the admin's "Check payment" button, payment links and provider refunds all run through this one file.
 
 ---
 
@@ -561,7 +487,7 @@ Post-installation is complete when every line below holds. **Do not validate the
 - [ ] `commerce/seed-store` ran once and reported the catalog — real products, final image URLs; `payment_methods` passed only if the store's methods differ from the default (offline on, cards off).
 - [ ] **Catalog pages and a checkout exist** — the catalog UI in whatever form fits the store (a product list, product pages, or both — one can be enough), a cart step only if the store wants one (§2.3), and the checkout built on `useCheckout` with `/order-received` rendering `useOrderReturn` (§2.4).
 - [ ] **Every coupon the store has can actually be redeemed** — if `coupons` was seeded (or the operator has codes), a code field with `applyCoupon` exists in the cart or the checkout, showing `discount_total` and rendering invalid codes inline (§2.3/§2.4). No field → don't seed coupons and don't mention codes in the copy.
-- [ ] **One `<StorefrontProvider>`** above every storefront route — no second client, no hand-rolled `cart_token` handling, payment gateways read from `useStoreInfo()` only (never off a cart), and cart state everywhere through `useCart()`.
+- [ ] **One `<StorefrontProvider>`** above every storefront route — wrapping `<Routes>` (or a layout route's `<Outlet />`), never placed as a child of `<Routes>`, which React Router rejects (§2) — no second client, no hand-rolled `cart_token` handling, payment gateways read from `useStoreInfo()` only (never off a cart), and cart state everywhere through `useCart()`.
 - [ ] **Cards are either off, or on with a provider behind them** (§4.1) — the default (offline enabled, `card` off) is a complete state and needs nothing. If you enabled cards, the provider must be wired: `card-payment.ts` written whole, secret stored, webhook registered. Enabled without a wired provider means `503 no_card_payment_provider` at checkout; wired without enabling means customers never see the option. Say where payments landed when you hand over.
 
 ## 6. Next

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

@@ -13,7 +13,7 @@ What it does **not** ship with is a payment provider. Wiring one (Stripe, PayPal
 | `refundCardPayment` | admin refunds through the provider (optional — leave the stub to keep refunds manual) |
 | `parseWebhook` | webhook validation: name the order a provider event is about (from the echoed metadata), and vouch `paid: true` **only** after verifying the request signature over the raw body bytes |
 
-**Wiring Stripe? Don't start here** — [`post-installation.md` §4](../post-installation.md#42-wiring-a-provider--one-file) has the complete implementation of all four functions to paste in, plus the secret and webhook-endpoint steps. This reference is for other providers and for webhook customization.
+**Wiring a payment provider?** Whichever one the store chose, the job is the same: implement those four functions against its API, following the rules on this page. As a worked example, [a complete Stripe implementation](#reference-implementation--stripe) sits at the bottom of the page — with its secret and webhook-endpoint steps — usable as-is if Stripe happens to be the provider, and as a model of the four contracts if it isn't. It is a reference for one common choice, **not a bundled provider**: no provider ships with the template.
 
 The card option ships **disabled**, so on a default store none of this is customer-visible. Where the gateway has been enabled without the file, picking Credit card at checkout answers `503 no_card_payment_provider` (the storefront should offer the other methods) — implement the file, or switch the option back off in Settings → Payments. 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.
 
@@ -41,12 +41,130 @@ The card option ships **disabled**, so on a default store none of this is custom
 
 `parseWebhook(req, payload)` lives in `card-payment.ts` with the other three; `commerce/payment-webhook` (the function file) is premade and calls it with the raw request and the raw body — the exact bytes, so signature schemes work. It returns `CardWebhookEvent | null`:
 
-- **The simple, secure default — the nudge**: parse the event, read the `order_id`/`order_key` metadata `createCardPayment` attached, return `{ order_id, order_key, paid: false }`. No signing secret; the premade flow verifies via `checkCardPaymentPaid` against the provider's API, so forgery is impossible by construction. This is what the Stripe reference implementation does.
+- **The simple, secure default — the nudge**: parse the event, read the `order_id`/`order_key` metadata `createCardPayment` attached, return `{ order_id, order_key, paid: false }`. No signing secret; the premade flow verifies via `checkCardPaymentPaid` against the provider's API, so forgery is impossible by construction. This is what the Stripe implementation below does.
 - **The signature-verified fast path** (optional): verify the provider's signature over the raw `payload` bytes (Stripe: `constructEventAsync` with a webhook signing secret) and return `paid: true` with the event's `reference` for a verified successful payment; the premade code then trusts it without the API round-trip. `paid: true` from an unverified body is the one way to break this design — never do it.
 - Return **`null`** for events that aren't about a payment for one of this store's orders; the function answers 200 so the provider doesn't retry.
 
 Everything after `parseWebhook` — order lookup, the `order_key` match, idempotent confirmation, order progression — is premade either way.
 
+## Reference implementation — Stripe
+
+**A worked example, not a bundled provider**: the template ships with no provider at all, and Stripe is one option among many (PayPal, Adyen, a local PSP — the four functions are the same shape against any API). Paste this in when Stripe is the provider the store actually chose; read it as a model of the four contracts when the provider is something else. Either way, only once §4.1's rule says cards are wanted at all.
+
+Overwrite `base44/shared/commerce/card-payment.ts` with this **as one whole-file write** (never `find_replace` into the stubs — see *Implementation rules* above):
+
+```ts
+// base44/shared/commerce/card-payment.ts — Stripe implementation
+import Stripe from "npm:stripe@18";
+import { HttpError } from "./auth.ts";
+
+export interface CardPaymentPage {
+  url: string;        // where the customer goes to pay
+  reference: string;  // the provider's id for this payment, stored on the order
+}
+
+const stripe = () => {
+  const key = Deno.env.get("STRIPE_SECRET_KEY");
+  if (!key) {
+    throw new HttpError(503, "Card payments are not configured — the STRIPE_SECRET_KEY secret is missing.", "no_card_payment_provider");
+  }
+  return new Stripe(key);
+};
+
+// Stripe amounts are in minor units; these currencies have none.
+const ZERO_DECIMAL = new Set(["BIF","CLP","DJF","GNF","JPY","KMF","KRW","MGA","PYG","RWF","UGX","VND","VUV","XAF","XOF","XPF"]);
+const minorUnits = (amount: number, currency: string) =>
+  Math.round(Number(amount) * (ZERO_DECIMAL.has(String(currency).toUpperCase()) ? 1 : 100));
+
+export async function createCardPayment(
+  _sr: any,
+  order: any,
+  opts: { successUrl: string; cancelUrl: string; customerEmail?: string },
+): Promise<CardPaymentPage> {
+  // order_id + order_key in the metadata is how the premade payment-webhook
+  // names the order when Stripe's event arrives — keep it on both objects.
+  const metadata = { order_id: String(order.id), order_key: String(order.order_key) };
+  const session = await stripe().checkout.sessions.create({
+    mode: "payment",
+    line_items: [{
+      quantity: 1,
+      price_data: {
+        currency: String(order.currency || "USD").toLowerCase(),
+        product_data: { name: `Order #${order.order_number}` },
+        unit_amount: minorUnits(order.total, order.currency),
+      },
+    }],
+    customer_email: opts.customerEmail || undefined,
+    metadata,
+    payment_intent_data: { metadata },
+    success_url: opts.successUrl,
+    cancel_url: opts.cancelUrl,
+  });
+  if (!session.url) throw new HttpError(502, "Stripe did not return a payment page URL.", "payment_session_failed");
+  return { url: session.url, reference: session.id };
+}
+
+export async function checkCardPaymentPaid(_sr: any, order: any, reference: string): Promise<boolean> {
+  const session = await stripe().checkout.sessions.retrieve(reference);
+  // The payment must be for THIS order — stops a reference to some other
+  // (paid) session being replayed against a different order.
+  return session.payment_status === "paid" && session.metadata?.order_id === String(order.id);
+}
+
+export async function refundCardPayment(_sr: any, _order: any, opts: {
+  reference: string; amount: number; currency: string; reason?: string;
+}): Promise<{ refund_id: string }> {
+  const session = await stripe().checkout.sessions.retrieve(opts.reference);
+  if (!session.payment_intent) {
+    throw new HttpError(409, "This payment has no charge to refund at Stripe.", "no_charge_to_refund");
+  }
+  const refund = await stripe().refunds.create({
+    payment_intent: String(session.payment_intent),
+    amount: minorUnits(opts.amount, opts.currency),
+  });
+  return { refund_id: refund.id };
+}
+
+/** What parseWebhook distills an event into — the premade webhook's contract. */
+export interface CardWebhookEvent {
+  order_id: string;
+  order_key: string;
+  paid: boolean;       // true only after signature verification — never from a raw body
+  reference?: string;  // only if signature-verified; otherwise the order's stored reference is used
+}
+
+/**
+ * Stripe webhook events. The event body is never trusted: this only names
+ * the order (from the metadata createCardPayment attached) and returns
+ * paid: false, so the premade webhook verifies against Stripe's API through
+ * checkCardPaymentPaid — a forged call can never mark an order paid, and no
+ * signing secret is needed. (Optional fast path that skips the API
+ * round-trip: verify the signature instead — references/online-payments.md.)
+ */
+export async function parseWebhook(_req: Request, payload: string): Promise<CardWebhookEvent | null> {
+  let event: any;
+  try { event = JSON.parse(payload); } catch { return null; }
+  const metadata = event?.data?.object?.metadata;
+  if (!metadata?.order_id || !metadata?.order_key) return null;
+  return { order_id: String(metadata.order_id), order_key: String(metadata.order_key), paid: false };
+}
+```
+
+Then the credential and the webhook endpoint:
+
+1. **Secret**: the user's Stripe **secret key**, stored as the `STRIPE_SECRET_KEY` app secret (backend env — never in code, never in an entity). Test keys (`sk_test_…`) work end to end.
+2. **Webhook endpoint**: register `https://<app-domain>/functions/commerce/payment-webhook` with Stripe for `checkout.session.completed`. There is **no signing secret to store** — events are nudges, verified against Stripe's API. One call with the same secret key (or the user does it in the Stripe dashboard):
+
+   ```js
+   await fetch("https://api.stripe.com/v1/webhook_endpoints", {
+     method: "POST",
+     headers: { Authorization: `Bearer ${Deno.env.get("STRIPE_SECRET_KEY")}`, "Content-Type": "application/x-www-form-urlencoded" },
+     body: new URLSearchParams({ url: "https://<app-domain>/functions/commerce/payment-webhook", "enabled_events[]": "checkout.session.completed" }),
+   });
+   ```
+
+Finally **enable the `card` gateway** — it is seeded off, so none of the above is visible at checkout until `commerce/seed-store` runs with `{ payment_methods: ["offline", "card"] }` ([`post-installation.md` §4.2](../post-installation.md#42-wiring-a-provider--one-file)).
+
 ## Storefront requirements (unchanged by any of this)
 
 - Redirect to `payment.checkout_url` when `place-order` returns `payment.status === "requires_payment"`.

package/src/commerce/admin/pages/settings/PaymentsSettings.jsx

@@ -205,13 +205,15 @@ export default function PaymentsSettings() {
               </div>
 
               {/* The "card" option redirects to a provider-hosted payment page.
-                  Wiring a provider means implementing the four functions in
-                  shared/commerce/card-payment.ts (Stripe: paste-in in
-                  .agents/skills/commerce/post-installation.md §4; the payment
-                  webhook is premade). Until then, picking it at checkout answers
-                  503 no_card_payment_provider. Deliberately not shown to the
-                  store operator — it's developer guidance, not store
-                  configuration. */}
+                  It ships disabled: no provider comes with the template, and
+                  wiring one means implementing the four functions in
+                  shared/commerce/card-payment.ts (rules, and a Stripe
+                  implementation to paste, in
+                  .agents/skills/commerce/references/online-payments.md; the
+                  payment webhook is premade). Enabled without that, picking it
+                  at checkout answers 503 no_card_payment_provider.
+                  Deliberately not shown to the store operator — it's developer
+                  guidance, not store configuration. */}
             </div>
           ))}
         </CardContent>

package/src/commerce/storefront/StorefrontProvider.jsx

@@ -13,10 +13,14 @@ import { createStorefront, storefrontErrorCode, storefrontErrorMessage } from "@
  * StorefrontProvider — one client, one store-info cache, ONE shared cart.
  *
  * Mount it once, above every storefront page (product list, product page,
- * cart, checkout, order-received):
+ * cart, checkout, order-received) — it wraps <Routes>, it is NOT a <Route>:
  *
  *   import { base44 } from "@/api/base44Client";
- *   <StorefrontProvider base44={base44}> ... </StorefrontProvider>
+ *   <StorefrontProvider base44={base44}> <Routes>…</Routes> </StorefrontProvider>
+ *
+ * Inside <Routes> it throws ("is not a <Route> component"), since React Router
+ * allows only <Route>/<Fragment> children there. To cover just some routes,
+ * use a pathless layout route: element={<StorefrontProvider …><Outlet/></…>}.
  *
  * or, if other modules also need the raw client, create it once and share it:
  *
@@ -102,7 +106,7 @@ export function useStorefrontState() {
   const ctx = useContext(StorefrontContext);
   if (!ctx) {
     throw new Error(
-      "Storefront hooks need a <StorefrontProvider> above them — mount it once around your storefront routes.",
+      "Storefront hooks need a <StorefrontProvider> above them — mount it once around your <Routes> (it wraps the router; it is not a <Route>, and inside <Routes> React Router rejects it).",
     );
   }
   return ctx;

package/src/commerce/storefront/index.js

@@ -6,7 +6,8 @@
  * every pixel stays yours. The hooks own the contracts that are easy to get
  * subtly wrong; you own the markup.
  *
- * Setup (once, above every storefront route):
+ * Setup (once, above every storefront route — it wraps <Routes>; placed as a
+ * child of <Routes> React Router throws "is not a <Route> component"):
  *
  *   import { StorefrontProvider } from "@/commerce/storefront";
  *   import { base44 } from "@/api/base44Client";