@base44/app-plugin-commerce 0.1.0

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

@@ -0,0 +1,408 @@
+# Storefront API Reference
+
+Everything needed to build a customer-facing shopfront (or headless client) against the Base44 Commerce Template. No visitor UI ships with the template — this is your integration surface. Some storefront *logic* does ship: the framework-free helpers in `src/commerce/utils/` (variant selection, free-shipping rules).
+
+## Required behaviors — a storefront that skips these cannot sell
+
+Read this list before writing any of it. Each item is a hard requirement enforced by the API, not a nicety:
+
+| # | Requirement | Enforced by |
+|---|---|---|
+| 1 | **Variable products: one selector per attribute**, resolved to a `variation_id` before adding to the cart — never a flat list of combinations | `add-item` → `400 variation_required` ([product page](#get-product)) |
+| 2 | **Present shipping options and send a choice** — drive it off the cart's `shipping_status`; a single option is auto-applied, several mean you must ask | `place-order` → `400 shipping_method_required` ([shipping](#shipping-is-not-optional--read-this-before-building-checkout)) |
+| 3 | **Redirect to `payment.checkout_url`** when the customer pays by card | the order stays `pending` otherwise |
+| 4 | **Implement the return page** (`/order-received`, or your own route set in Settings → General → *Payment return path*) and call `commerce/payments` `complete-return` there | without it a paid order is never confirmed, and a wrong path is a 404 |
+| 5 | **Only advertise offers the store is configured for** (free-shipping thresholds come from zone methods) | nothing — this one is on you |
+
+Four public functions: **`commerce/storefront-catalog`**, **`commerce/storefront-cart`**, **`commerce/storefront-checkout`**, **`commerce/storefront-account`**. All are invoked the same way and return the same envelope.
+
+## What the API already gives you (read before designing the UI)
+
+The backend is considerably richer than a minimal "grid → cart → pay" shop. **Build to this surface, not to the basics** — everything below already exists server-side, so leaving it out means shipping a storefront that is weaker than the store behind it. Each row links to the section with the exact payload.
+
+| Capability | Already supported | Where |
+|---|---|---|
+| **Product discovery** | full-text `search`, filter by category (incl. descendants), tag, attribute+term, price range, `featured`, `on_sale`, `in_stock_only`; sort by menu order / price / newest / **popularity** / **rating**; paging | [`list-products`](#list-products) |
+| **Rich product pages** | galleries, variable products with per-variation price/stock/image, categories, tags, **upsells**, **cross-sells**, grouped-product children | [`get-product`](#get-product) |
+| **Taxonomy navigation** | category tree, **tag list with counts**, attributes + terms for filter UIs | [`list-categories`](#list-categories), [`list-tags`](#list-tags), [`list-attributes`](#list-attributes) |
+| **Customer reviews** | paginated reviews per product with **average rating + rating count**, `verified` owner flag, and **review submission by signed-in customers**; plus "my reviews" | [`get-product`](#get-product), [`submit-review`](#submit-review), [`my-reviews`](#commercestorefront-account) |
+| **Cart** | guest carts via `cart_token`, add/update/remove, quantity merging, `sold_individually` caps, live re-pricing, stock revalidation | [`commerce/storefront-cart`](#commercestorefront-cart) |
+| **Coupons** | apply/remove by code with full server-side validation (eligibility, limits, per-user usage) | [`apply-coupon`](#commercestorefront-cart) |
+| **Shipping** | address → matched zone → **selectable shipping methods with live costs**, free-shipping rules | [`set-shipping-address`](#commercestorefront-cart) |
+| **Tax** | inclusive/exclusive pricing, per-class rates, itemized or single display — all resolved server-side | [`get-store-info`](#get-store-info) |
+| **Stock states** | in stock / out of stock / **on backorder**, low-stock signalling, configurable out-of-stock hiding | [`list-products`](#list-products) |
+| **Checkout** | guest or authenticated, billing/shipping, per-gateway routing, **payment instructions** for manual methods, order cancel, post-payment confirm | [`commerce/storefront-checkout`](#commercestorefront-checkout) |
+| **Accounts** | order history, saved billing/shipping addresses, and **guest order tracking by `order_key`** with customer-visible order notes | [`commerce/storefront-account`](#commercestorefront-account) |
+| **Digital products** | entitlement-checked downloads with remaining-count, expiry, and signed URLs for private files | [`get-download`](#commercestorefront-account) |
+| **Store config** | currency + formatting, review toggles, 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 live card capture (see [`references/online-payments.md`](../references/online-payments.md)). Payment methods, currency and formatting are all admin-owned data — always render them from `get-store-info` rather than a hardcoded list.
+
+## Conventions
+
+- **Invoke:** `base44.functions.invoke("commerce/<function>", { action, ...payload })`. Response body is on `res.data`; the envelope is `{ success, data }` on success or `{ success, error, code }` on failure (HTTP status set accordingly).
+  ```js
+  const res = await base44.functions.invoke("commerce/storefront-catalog", { action: "get-store-info" });
+  const info = res.data.data;              // envelope → payload
+  ```
+- **Auth modes:** most actions are anonymous. Some require an authenticated Base44 session (marked **auth**). Guest order access uses `order_key`; cart access uses `cart_token` — both are bearer credentials (HTTPS only).
+- **Identity is never a payload field.** Anything attributed to a person — a review's author, a saved profile — is taken from the session. Passing an email in the body does not make you that customer, and no request can assert that an order was paid. Don't design a feature around a client-supplied identity; it will be ignored.
+- **Money:** numbers, 2-dp. **Dates:** ISO strings.
+- **Errors:** every failure has a stable `code` (listed per action) plus a human `error` message.
+
+---
+
+## commerce/storefront-catalog
+
+Public catalog browsing. No auth.
+
+### `get-store-info`
+Bootstrap data for a storefront. No payload.
+
+**Response:**
+```json
+{
+  "settings": { "currency": "USD", "currency_position": "left", "thousand_sep": ",", "decimal_sep": ".",
+                "num_decimals": 2, "weight_unit": "kg", "dimension_unit": "cm",
+                "prices_include_tax": false, "enable_reviews": true, "review_rating_required": true },
+  "payment_gateways": [ { "slug": "cod", "title": "Cash on delivery", "description": "..." } ],
+  "countries": [ { "code": "US", "name": "United States", "states": [ { "code": "CA", "name": "California" } ] } ],
+  "currencies": [ { "code": "USD", "name": "US Dollar", "symbol": "$", "decimals": 2 } ]
+}
+```
+`settings` is a safe projection — only display/behavior keys, never admin config.
+
+### `list-products`
+**Payload** (all optional): `search`, `category_id` (includes descendants), `tag_id`, `attribute_id` + `attribute_term`, `min_price`, `max_price`, `featured` (bool), `on_sale` (bool), `in_stock_only` (bool), `sort` (`menu_order`|`price`|`-price`|`-created_date`|`popularity`|`rating`, default `menu_order`), `page` (default 1), `per_page` (default 12, max 100).
+
+Only `status: "publish"` products are returned. Visibility: passing `search` uses **search context** (hides `catalog_visibility: hidden|catalog`); no `search` uses **browse context** (hides `hidden|search`). `inventory.hide_out_of_stock` (or `in_stock_only`) drops out-of-stock products.
+
+**Response:** `{ "products": [Product...], "page": 1, "per_page": 12, "has_next": true }`
+
+Each row is the product record (minus paywalled fields) **plus a resolved `tags` array** (`[{ id, name, slug }]`), so cards can show tags without a second call. `categories` are **not** resolved on rows — `category_ids` only.
+
+> **What to render, and what a row can't show:** [`../references/product-render.md`](../references/product-render.md) — field-availability table for list vs. product page, tags in both views, variable-product pricing on cards, and how to add a `get-product`-only field to the listing call instead of fetching per card.
+
+**Filters stack.** `category_id`, `tag_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-tags`](#list-tags) (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.
+
+### `get-product`
+**Payload:** `{ id }` **or** `{ slug }`; optional `reviews_page` (1), `reviews_per_page` (10, max 50).
+
+**Response:**
+```json
+{
+  "product": { Product },
+  "variations": [ ProductVariation... ],          // publishable only; [] for non-variable
+  "categories": [ ProductCategory... ],
+  "tags": [ ProductTag... ],
+  "reviews": { "items": [ { "id", "reviewer", "review", "rating", "verified", "created_date" } ],
+               "page": 1, "per_page": 10, "has_next": false,
+               "average_rating": 4.5, "rating_count": 12 },
+  "upsells":  [ { "id", "name", "slug", "price", "on_sale", "image", "stock_status" } ],
+  "cross_sells": [ ...summaries ],
+  "grouped_products": [ ...summaries ]
+}
+```
+**Errors:** `404 not_found` (missing / not published / hidden).
+
+> **Rendering this response as a product page — the rule, not just a link.** `variations[]` is **not** a list of choices to show. Build **one control per `product.attributes[]` entry with `variation: true`** (Size, Color, …), and resolve the combination to a variation client-side; `add-item` needs that `variation_id`. Variable-product prices come from `variations[]`, never from `product.price` (the backend rolls stock up to the parent, not price). The shipped helper does all of it:
+> ```js
+> import { resolveSelection, defaultSelection, selectOption } from "@/commerce/utils";
+> const [selection, setSelection] = useState(() => defaultSelection(product, variations));
+> const view = resolveSelection(product, variations, selection);
+> // view.axes → render a control per axis, options from axis.options
+> // view.availability[axis.key][option] → "available" | "out_of_stock" | "unavailable" (disable, don't hide)
+> // view.display → image / price / sku / stock for the resolved variation
+> // view.purchasable + view.addToCart → { product_id, variation_id } for add-item
+> const pick = (axisKey, option) => setSelection((s) => selectOption(product, variations, s, axisKey, option));
+> ```
+> Full variant rules (availability states, incomplete-selection pricing, defaults, URL state): [`../references/storefront-product-page.md`](../references/storefront-product-page.md).
+> What to render on the page vs. a card, and which fields exist in only one of the two calls: [`../references/product-render.md`](../references/product-render.md).
+
+### `list-categories`
+No payload. Returns a nested tree: `{ "categories": [ { ...category, "children": [...] } ] }` sorted by `menu_order` then name.
+
+### `list-tags`
+**Payload** (optional): `{ with_products_only?: boolean }` (default `true`).
+
+Returns `{ "tags": [ { id, name, slug, description, count } ] }` sorted by name. By default it omits tags no published product carries, so a tag nav never links to an empty listing; pass `with_products_only: false` for the full set (e.g. an admin-facing picker).
+
+`count` is tallied from the products this API would actually list — published, browse-visible, and honoring `inventory.hide_out_of_stock` — **not** from `ProductTag.count`, which also counts drafts and hidden products and drifts until `commerce/admin-tools` `recount-terms` runs. So `Gift (12)` and the tag's listing agree.
+
+This is the **only** way a storefront can enumerate tags — `commerce.ProductTag` is admin-only RLS — and it's what makes `list-products` `tag_id` usable, since that filter needs an id. Tags are a flat, cross-cutting axis ("gift", "summer", "vegan"); categories are the hierarchical spine. Show both: see [*Tags*](../references/product-render.md#2-tags--render-them-in-both-views) for where they belong in each view.
+
+### `list-attributes`
+No payload. Returns `{ "attributes": [ { ...attribute, "terms": [ ...terms ] } ] }` — for building filter UIs.
+
+### `submit-review` — **auth**
+**Payload:** `{ product_id, reviewer?, review, rating }`.
+
+**Requires a signed-in customer.** The reviewer's email is taken from the session, never from the payload — a `reviewer_email` field is ignored. `reviewer` is the display name only, and defaults to the account's `full_name`. Build the review form behind a login prompt: anonymous callers get `401 login_required`.
+
+Requires `products.enable_reviews` and the product's `reviews_allowed`. Rating required when `review_rating_required`. If `only_verified_reviews`, the signed-in customer must have a `processing`/`completed` order containing the product. `verified` is derived from their own order history. Status is `hold` unless `auto_approve_reviews`.
+
+**Response:** `{ "review_id", "status": "hold"|"approved", "verified": true }`
+**Errors:** `401 login_required`, `403 reviews_disabled|verified_only|forbidden`, `404 not_found`, `400 review_incomplete|rating_required|invalid_rating`.
+
+---
+
+## commerce/storefront-cart
+
+Token-scoped cart (guest + member). Every action **except `create`** takes `cart_token`. **Every mutating action returns the full priced cart view.** Carts have a rolling 48h TTL (refreshed on each touch). An authenticated caller's other active carts are merged in (quantities summed, `sold_individually` capped, coupon codes unioned; source carts marked abandoned).
+
+### The priced cart view (returned by every action)
+```json
+{
+  "cart_token": "uuid",
+  "items": [ {
+    "item_key": "uuid", "product_id": "...", "variation_id": "", "quantity": 2,
+    "attributes": [ { "name": "Color", "option": "Red" } ],
+    "name": "T-Shirt", "sku": "TS-RED-M", "image": "https://...",
+    "price": 20, "subtotal": 40, "total": 36, "total_tax": 3.6,
+    "virtual": false, "sold_individually": false,
+    "purchasable": { "ok": true }
+  } ],
+  "coupon_codes": ["welcome10"],
+  "coupons": [ { "code": "welcome10", "coupon_id": "...", "discount": 4, "discount_tax": 0, "free_shipping": false } ],
+  "coupon_notices": [ { "code": "old", "error": "Coupon has expired.", "error_code": "expired" } ],
+  "removed_items": [ { "item_key": "...", "product_id": "...", "reason": "...", "code": "unavailable" } ],
+  "shipping_address": { "country": "US", "state": "CA", "postcode": "90210", "city": "LA" },
+  "chosen_shipping_method": "<zoneMethodId>",
+  "available_shipping_methods": [ { "id": "<zoneMethodId>", "method_id": "flat_rate", "title": "Flat rate", "cost": 5 } ],
+  "shipping_status": "chosen",           // not_needed | chosen | auto_selected | choice_required | none_available
+  "totals": { "subtotal": 40, "discount_total": 4, "discount_tax": 0, "shipping_total": 5, "shipping_tax": 0,
+              "cart_tax": 3.6, "total_tax": 3.6, "total": 44.6, "prices_include_tax": false,
+              "tax_lines": [ { "rate_id": "...", "label": "CA Tax", "tax_total": 3.6 } ] },
+  "expires_at": "2025-..."
+}
+```
+Stored coupons that stop validating are **auto-removed** and reported in `coupon_notices`; items whose product vanished/unpublished appear in `removed_items`.
+
+### Actions
+| Action | Payload | Notes / errors |
+|---|---|---|
+| `create` | `{ items?: [{product_id, variation_id?, quantity, attributes?}] }` | Mints and returns a new `cart_token`. Initial items go through add validation. |
+| `get` | `{ cart_token }` | Priced view (also re-prices + merges). |
+| `totals` | `{ cart_token }` | Alias of `get`. |
+| `add-item` | `{ cart_token, product_id, variation_id?, quantity?, attributes? }` | Variable product requires `variation_id` (`400 variation_required`); `sold_individually` caps qty at 1; merges same product+variation. `400 <stock code>`, `404 product_not_found|variation_not_found`. |
+| `update-item` | `{ cart_token, item_key, quantity }` | qty ≤ 0 removes the line. `404 item_not_found`, `400 <stock code>`. |
+| `remove-item` | `{ cart_token, item_key }` | |
+| `apply-coupon` | `{ cart_token, code }` | Full validation. `400 coupons_disabled|code_required|already_applied|<coupon code>`. |
+| `remove-coupon` | `{ cart_token, code }` | |
+| `set-shipping-address` | `{ cart_token, address: {country, state?, postcode?, city?} }` | `400 country_required`. Returns the matched zone's `available_shipping_methods` and a `shipping_status`. |
+| `choose-shipping-method` | `{ cart_token, method_id }` | `method_id` = a `commerce.ShippingZoneMethod` id from `available_shipping_methods`. `400 invalid_shipping_method` (the error body carries `available_shipping_methods`). |
+
+Common: `400 cart_token_required`, `404 cart_not_found`, `404 cart_expired`.
+
+### Shipping is not optional — read this before building checkout
+<a id="shipping-is-not-optional--read-this-before-building-checkout"></a>
+
+A shippable order with no shipping line ships **for free**, so the API refuses to
+create one. Every priced cart view carries `shipping_status`; drive the UI from it
+rather than assuming:
+
+| `shipping_status` | Meaning | What the storefront must do |
+|---|---|---|
+| `not_needed` | every line is virtual, or shipping is disabled store-wide | show no shipping step |
+| `auto_selected` | exactly **one** method is offered, so the cart already applied it | show it as the (only) delivery option — **don't** make the customer pick from a list of one |
+| `chosen` | the customer's pick is still offered | show it, allow changing |
+| `choice_required` | **several** methods are offered and none is chosen | render `available_shipping_methods` and call `choose-shipping-method`; checkout will refuse until then |
+| `none_available` | nothing ships to this address | say so, and don't let checkout proceed |
+
+Rules the cart enforces on every price, so you get them for free:
+
+- **A single available method is auto-selected.** One option is not a choice; requiring a round trip for it is exactly how a storefront ends up never sending a method at all.
+- **A stale choice is dropped.** If the address or cart changes so the chosen method is no longer offered, it is cleared (and re-auto-selected when only one remains) instead of silently pricing zero shipping.
+- **Costs change with the cart.** `available_shipping_methods` is recomputed per price — free-shipping thresholds and coupon-gated methods appear and disappear — so re-read it after every cart mutation, not just after setting the address.
+
+### Never advertise what the store isn't configured to do
+
+Copy like *"Free shipping on orders over €150"* is a **claim about store configuration**, and the checkout will only honour what's actually configured. Don't write such a line into a storefront unless a matching rule exists — either configure it (with the operator's agreement) or leave the copy out.
+
+`commerce.ShippingZone` and `commerce.ShippingZoneMethod` are **public-read**, so the real rule is available to the storefront, and [`src/commerce/utils/shipping-promos.js`](../../../src/commerce/utils/shipping-promos.js) reads it:
+
+```js
+import { freeShippingRules, freeShippingThreshold, freeShippingProgress } from "@/commerce/utils";
+
+const [zones, methods] = await Promise.all([
+  base44.entities["commerce.ShippingZone"].list("order", 100),
+  base44.entities["commerce.ShippingZoneMethod"].list(undefined, 200),
+]);
+const threshold = freeShippingThreshold(freeShippingRules(zones, methods));
+// null → the store has no free-shipping rule: show no banner, no progress bar.
+const progress = freeShippingProgress(threshold, cart.totals.subtotal);  // { threshold, qualifies, remaining }
+```
+
+A free-shipping rule is a `free_shipping` zone method whose `settings.requires` is `min_amount`/`either`/`both` with a `min_amount` (a `coupon` requirement is **not** a spend threshold, and thresholds are **per zone** — a rule in one zone must not become a site-wide banner). The same applies to any other promise: a discount claim needs a real `commerce.Coupon` (admin-read only — only advertise a code the operator gave you), and delivery-time or returns claims the template cannot enforce need the operator's confirmation.
+
+---
+
+## commerce/storefront-checkout
+
+### `place-order`
+Converts a cart into an order. **Payload:**
+```json
+{ "cart_token": "uuid", "payment_method": "cod",
+  "billing":  { "first_name", "last_name", "address_1", "address_2?", "city", "state?", "postcode?", "country", "email", "phone?" },
+  "shipping": { ...address without email },
+  "chosen_shipping_method?": "<zoneMethodId>",
+  "customer_note?": "...", "create_account?": false }
+```
+**Mandatory fields:**
+- **Billing:** `first_name, last_name, address_1, city, country, email`.
+- **Shipping address** and a **shipping method** — mandatory whenever the cart has any non-virtual (physical) line and shipping is enabled. Your checkout UI has to *offer* the options; there is no default. The whole contract:
+  ```js
+  cart = await inv("commerce/storefront-cart", { action: "set-shipping-address", cart_token, address });
+  if (cart.shipping_status === "choice_required") {
+    // MUST render cart.available_shipping_methods and let the customer pick
+    cart = await inv("commerce/storefront-cart", { action: "choose-shipping-method", cart_token, method_id: picked.id });
+  } else if (cart.shipping_status === "none_available") {
+    // the store doesn't ship there — stop, don't try to place the order
+  }
+  // auto_selected / chosen: nothing to do, one option was applied for you
+  ```
+  Skipping this is the most common storefront bug: `place-order` answers `400 shipping_method_required` with the methods attached, and no order is created. Set the address on the cart first (`set-shipping-address`); the method can come either from the cart (`choose-shipping-method`) or straight from this call via `chosen_shipping_method`, which wins if both are present. What happens then:
+  - **one method offered** → applied automatically, nothing to send;
+  - **several offered, none chosen** → `400 shipping_method_required`, with `available_shipping_methods` in the error body so you can prompt;
+  - **`chosen_shipping_method` not offered** for this address → `400 invalid_shipping_method` (never silently swapped for another);
+  - **nothing offered** → `400 no_shipping_available`.
+
+  The order is priced with the resolved method, so its `shipping_total` always matches what the customer was shown.
+
+> **Payment.** `payment_method` is a `commerce.PaymentGateway` slug from `get-store-info`. Card payments are **implemented**: choosing the online gateway leaves the order `pending` and returns `payment: { status: "requires_payment", checkout_url, session_id }` — send the customer to `checkout_url` (the provider's hosted page), then confirm on their return with `commerce/payments` `verify`. Never treat a return URL as proof of payment. The manual gateways (`cod`, `bacs`, `cheque`) settle outside the store and return `payment_instructions` instead. An online gateway is only listed while a payment provider is connected, so anything `get-store-info` offers is payable. Optional `success_url` / `cancel_url` / `return_url` in the payload override the default return URLs. See [`../references/online-payments.md`](../references/online-payments.md).
+
+**Steps:** releases expired holds → revalidates stock & coupons → computes authoritative totals → finds-or-creates the Customer by billing email → creates a `pending` order (with `order_key`, `hold_expires_at`) → reduces stock, fires `new_order` email + `order.created` webhook → marks cart `converted` → routes by gateway: **cod → processing**, **bacs/cheque → on-hold** (with `payment_instructions`), **stripe → stays pending** with a `not_implemented` placeholder, **custom → pending_external**.
+
+> **Saved profiles are only written by their owner.** The order always stores the `billing`/`shipping` it was placed with. The **`commerce.Customer`** record behind it — the one a storefront prefills from — is refreshed only when the caller is signed in *as* the billing email. A guest checkout quoting an existing customer's address still attaches the order to them (so it shows up in their `my-orders`), but cannot change their saved name or addresses. Don't build an "edit my details at checkout" flow for guests; use `update-my-addresses` behind a login instead.
+
+**Response:**
+```json
+{
+  "order_id": "...", "order_number": 1001, "order_key": "order_...",
+  "status": "processing", "currency": "USD",
+  "payment_method": "cod", "payment_method_title": "Cash on delivery",
+  "payment_instructions": { "type": "cod", "description": "...", "account_details?": [...] },
+  "payment": null,                       // or { "status": "not_implemented" | "pending_external", "note": "..." } for stripe/custom
+  "notices": [],                         // e.g. ["account_creation_requires_login"]
+  "totals": { "subtotal", "discount_total", "shipping_total", "shipping_tax", "cart_tax", "total_tax", "total" },
+  "order": { ...customer-safe order (internal flags/ip stripped) }
+}
+```
+**Errors:** `401 login_required` (guest checkout disabled), `400 billing_incomplete`, `400 empty_cart`, `409 items_unavailable`, `409 coupon_invalid`, `400 shipping_method_required` / `400 invalid_shipping_method` / `400 no_shipping_available` (each carrying `available_shipping_methods`; these replace the earlier catch-all `shipping_required`), `400 invalid_payment_method`.
+
+### `commerce/payments` — online payment for an order
+
+Separate function, same guest-bearer rule (`order_id` + `order_key`; an admin may act without a key).
+
+| Action | Payload | Returns |
+|---|---|---|
+| `create-link` | `{ order_id, order_key, success_url?, cancel_url?, return_url? }` | `{ provider, session_id, url, expires_at? }` — a fresh hosted payment page for an **unpaid** order, whatever its current payment method (the order is switched onto the online gateway and the change is logged). This is how a storefront offers "pay now" on an order-received page or an emailed link, and what the admin's payment-link button calls. `409 already_paid`, `400 online_payments_disabled` (the store turned card payment off), `503 payment_provider_unavailable` |
+| `complete-return` | `{ order_id, order_key, payment?, return_url? }` | `{ state: "paid"\|"cancelled"\|"unpaid", paid, already_confirmed, status, order, payment_link }` — the whole return flow in one call for your `/order-received` page: confirms with the provider, progresses the order, and includes a fresh `payment_link` while unpaid. `payment` is only a hint; a hand-edited `?payment=success` can never yield `paid` |
+| `verify` | `{ order_id, order_key, session_id? }` | `{ paid, already_confirmed, status, order }` — the same confirmation without the render-ready extras. **Idempotent**: call it on every return, and as often as you like. A `session_id` you pass must be one the provider opened for *this* order, or `409 session_order_mismatch`; omit it and the order's own session is used |
+
+> **You must build the `/order-received` page** — it is mandatory for payment links to work. No storefront UI ships with the template, and without that route a paying customer lands on a 404 *and* the order never gets marked paid. It only needs to call `complete-return` and render its three states: see [`../references/online-payments.md`](../references/online-payments.md).
+
+Provider callbacks land on `commerce/payment-webhook` (signed, server-to-server) — the second confirmation path, for buyers who pay and close the tab. Whichever path runs second is a no-op.
+
+### `confirm-payment`
+Post-payment hook for an order on the online gateway. **Payload:** `{ order_id, order_key, session_id? }`.
+
+**The request cannot make an order paid.** The `order_key` says who is asking; the payment itself is confirmed against the provider, and the session it names must be one the provider opened for *this* order. Only then does the order move `pending`/`on-hold` → `processing`, set `date_paid` and bump customer stats. There is no caller-supplied `transaction_id` — it comes from the provider. Idempotent.
+
+`commerce/payments` `complete-return` is the richer version of this and what an `/order-received` page should call; use `confirm-payment` when you only need the transition.
+
+**Response:** `{ "order": { ...customer-safe order }, "paid": true, "already_confirmed": false }`
+**Errors:** `400 order_key_required|not_an_online_payment`, `404 order_not_found`, `409 invalid_status|payment_not_confirmed|session_order_mismatch`.
+
+### `cancel-order`
+Customer-initiated cancel. **Payload:** `{ order_id, order_key }`. Only `pending`/`on-hold` (restores stock). **Response:** `{ "order": { ...customer-safe order } }` · **Errors:** `400 order_key_required`, `404 order_not_found`, `409 invalid_status`.
+
+---
+
+## commerce/storefront-account
+
+Two access modes: **auth** (Base44 session) or **`order_key` bearer** (guest tracking).
+
+| Action | Auth | Payload | Response |
+|---|---|---|---|
+| `my-orders` | auth | `{ page?, per_page? }` | `{ orders: [customer-safe], page, per_page, has_next }` |
+| `get-order` | order_key | `{ order_id, order_key }` | `{ order: customer-safe }` |
+| `order-notes` | order_key | `{ order_id, order_key }` | `{ notes: [{ id, note, created_date }] }` (customer notes only) |
+| `my-downloads` | auth | — | `{ downloads: [{ permission_id, order_id, product_id, download_name, downloads_remaining, access_expires, download_count }] }` |
+| `get-download` | auth **or** order_key | `{ permission_id, order_key? }` | `{ url, download_name, downloads_remaining }` — decrements remaining; returns a signed URL for private files |
+| `update-my-addresses` | auth | `{ billing?, shipping? }` | `{ customer: { email, first_name, last_name, billing, shipping } }` |
+| `my-reviews` | auth | — | `{ reviews: [{ id, product_id, review, rating, status, verified, created_date }] }` |
+
+**Errors:** `401 login_required`, `400 order_key_required|permission_required|nothing_to_update`, `404 order_not_found|download_not_found`, `403 forbidden|download_limit_reached|download_expired`.
+
+---
+
+## Walkthrough A — guest checkout
+
+```js
+const inv = (fn, payload) => base44.functions.invoke(fn, payload).then(r => r.data.data);
+
+// 1. Browse
+const { products } = await inv("commerce/storefront-catalog", { action: "list-products", per_page: 12 });
+
+// 2. New cart with one item
+let cart = await inv("commerce/storefront-cart", { action: "create",
+  items: [{ product_id: products[0].id, quantity: 1 }] });
+const token = cart.cart_token;
+
+// 3. (variable product) fetch options, then add the chosen variation
+const detail = await inv("commerce/storefront-catalog", { action: "get-product", id: products[0].id });
+if (detail.product.type === "variable") {
+  cart = await inv("commerce/storefront-cart", { action: "add-item",
+    cart_token: token, product_id: detail.product.id, variation_id: detail.variations[0].id });
+}
+
+// 4. Coupon (optional)
+cart = await inv("commerce/storefront-cart", { action: "apply-coupon", cart_token: token, code: "welcome10" });
+
+// 5. Shipping address → method. A single option is already applied for you;
+//    several mean the customer has to choose or checkout will refuse.
+cart = await inv("commerce/storefront-cart", { action: "set-shipping-address",
+  cart_token: token, address: { country: "US", state: "CA", postcode: "90210", city: "Los Angeles" } });
+if (cart.shipping_status === "choice_required") {
+  const picked = await askCustomer(cart.available_shipping_methods);   // your UI
+  cart = await inv("commerce/storefront-cart", { action: "choose-shipping-method",
+    cart_token: token, method_id: picked.id });
+} else if (cart.shipping_status === "none_available") {
+  throw new Error("We don't ship to this address");
+}
+
+// 6. Place the order (COD → processing immediately)
+const order = await inv("commerce/storefront-checkout", { action: "place-order",
+  cart_token: token, payment_method: "cod",
+  billing: { first_name: "Ada", last_name: "Lovelace", address_1: "1 St",
+             city: "Los Angeles", state: "CA", postcode: "90210", country: "US", email: "ada@example.com" } });
+
+// 7. Track it later without an account (order_key from step 6)
+const tracked = await inv("commerce/storefront-account", { action: "get-order",
+  order_id: order.order_id, order_key: order.order_key });
+```
+
+## Walkthrough B — member experience
+
+```js
+const inv = (fn, payload) => base44.functions.invoke(fn, payload).then(r => r.data.data);
+// (caller is authenticated via base44 auth — the SDK sends the session automatically)
+
+// Browsing carts made while logged out merge into this one automatically on `get`/`create`.
+let cart = await inv("commerce/storefront-cart", { action: "create", items: [{ product_id, quantity: 2 }] });
+
+// Saved addresses speed up checkout
+await inv("commerce/storefront-account", { action: "update-my-addresses",
+  billing: { first_name: "Ada", last_name: "Lovelace", address_1: "1 St", city: "LA",
+             state: "CA", postcode: "90210", country: "US", email: "ada@example.com" } });
+
+const order = await inv("commerce/storefront-checkout", { action: "place-order",
+  cart_token: cart.cart_token, payment_method: "bacs", billing: { /* ... */ } });
+// bacs → on-hold; show order.payment_instructions.account_details
+
+// Order history, downloads, reviews (all auth, no order_key needed)
+const { orders } = await inv("commerce/storefront-account", { action: "my-orders", per_page: 10 });
+const { downloads } = await inv("commerce/storefront-account", { action: "my-downloads" });
+const file = await inv("commerce/storefront-account", { action: "get-download", permission_id: downloads[0]?.permission_id });
+```

package/skills/commerce/installation-guidelines.md

@@ -0,0 +1,91 @@
+# Installation Guidelines
+
+How to install the Base44 Commerce Template into an existing Base44 app. This file lives inside the **commerce skill** folder and is installed into the app at `skills/commerce/installation-guidelines.md`. Once the files are in place, continue with [`post-installation.md`](./post-installation.md) (embedding the admin pages, `AGENTS.md` registration); day-2 guidance lives in [`skills/commerce/SKILL.md`](./SKILL.md), alongside the API references in [`skills/commerce/docs/`](./docs/).
+
+> **If you are a Base44 agent working inside the runtime, read this first:**
+> - **Skip the `npx base44` commands.** The runtime deploys functions and pushes entities automatically the moment you write the files — writing a resource file *is* the deploy.
+> - **Don't grant admin roles.** Granting a user the `admin` role is not an install step for you; instead, validate that the admin-role gating (see [`post-installation.md`](./post-installation.md)) is preserved when you merge the admin routes into the app's router.
+> - **Don't read the whole codebase up front.** Copy the files, wire the router, and open only what your current task touches.
+
+---
+
+## 1. Static installation (copying the files)
+
+**Scripted.** Copy this entire repository into the target app at `examples/commerce/`, then run from the app root:
+
+```bash
+node examples/commerce/scripts/install.js
+```
+
+Relative to the script's own folder (`examples/commerce/scripts/`), it copies:
+
+| From (template) | To (app) |
+|---|---|
+| `../base44/entities/commerce.*.jsonc` | `../../../base44/entities/` |
+| `../base44/functions/commerce/` | `../../../base44/functions/commerce/` |
+| `../base44/shared/commerce/` | `../../../base44/shared/commerce/` |
+| `../base44/agents/commerce/` | `../../../base44/agents/commerce/` |
+| `../src/commerce/admin/` | `../../../src/commerce/admin/` |
+| `../src/commerce/utils/` | `../../../src/commerce/utils/` |
+| `../skills/commerce/` | `../../../skills/commerce/` |
+
+Directories are merged: files owned by the template are overwritten (re-running after a template update is safe); everything else in your app is left untouched. Files the template has since **renamed or retired** are deleted on install (it reports each one) — otherwise stale guidance would sit in `skills/` forever, and agents read whatever is there. The skill folder carries all the documentation — `SKILL.md`, this file, `post-installation.md`, the topic references in `references/` and the API docs in `docs/` — so the installed app gets it at `skills/commerce/` where agents pick it up natively; the template repo itself also stays under `examples/commerce/` for reference.
+
+**Manual.** Equivalently, copy by hand:
+
+1. Copy `base44/entities/commerce.*`, `base44/functions/commerce/*`, `base44/shared/commerce/*` and `base44/agents/commerce/*` into your app's `base44/` dir (merge, don't overwrite unrelated files). `shared/` is bundled into every function at deploy time.
+2. Copy `src/commerce/admin/` → `src/commerce/admin/` and `src/commerce/utils/` → `src/commerce/utils/` (the storefront variant-selection helpers; framework-free, no deps).
+3. Copy `skills/commerce/` → `skills/commerce/` (the commerce skill — `SKILL.md`, this file, `post-installation.md`, the `references/` topic guides and the `docs/` API references — for agents working on the app).
+
+Confirm your `base44/config.jsonc` `entitiesDir`/`functionsDir` point at these folders (the defaults do).
+
+## 2. Deploy and wire up
+
+1. `npx base44 entities push` — creates/updates the 24 entity schemas. *(CLI path only — the Base44 runtime deploys on write.)*
+2. `npx base44 functions deploy` — deploys the 16 functions. *(CLI path only.)*
+3. `npx base44 agents push` — registers the `commerce/StoreAdmin` agent (§3). *(CLI path only.)*
+4. Verify `sonner` and `recharts` are installed and install them if not (`npm i sonner recharts`) — they ship with the default Base44 template, as does `react-markdown`; nothing else is needed. Verify the shadcn primitives listed in [`src/commerce/admin/README.md`](../../src/commerce/admin/README.md) exist in your app.
+5. Mount the admin router (see [`post-installation.md`](./post-installation.md)).
+6. Grant your user the `admin` role.
+7. Decide the store's data with the user — generate a real starter catalog, seed the generic demo data, or leave the store empty and let the operator hit **Initialize store defaults** on the admin's first-run screen. See [`post-installation.md`](./post-installation.md) §2; both seeded options mark the business as ready and the first-run screen never appears.
+
+Check the install at any time:
+
+```js
+const { data } = (await base44.functions.invoke("commerce/admin-tools", { action: "status" })).data;
+// → { template_version, seeded, settings_groups, counts: {...}, checks: [...] }
+```
+
+`commerce/seed-store` is **idempotent** and starts with a **canary schema check**: it probe-writes one record per entity it will touch and deletes it. If you've modified an entity schema incompatibly, it aborts with HTTP 422 `schema_incompatible` and writes nothing:
+
+```json
+{ "success": false, "code": "schema_incompatible",
+  "errors": [{ "entity": "Product", "error": "..." }] }
+```
+
+The admin setup screen surfaces these errors verbatim. Sample catalog data is only created when `with_sample_data: true` **and** the store has zero products.
+
+---
+
+## 3. The StoreAdmin agent (admin copilot)
+
+The template ships an AI copilot for store operators:
+
+- **Agent definition** — [`base44/agents/commerce/StoreAdmin.jsonc`](../../base44/agents/commerce/StoreAdmin.jsonc), registered as **`commerce/StoreAdmin`** (the folder namespaces the agent, exactly like functions). The hosted runtime registers it when the file lands; on the CLI path run `npx base44 agents push`.
+- **Tools** — the `commerce/*` backend functions attached directly (`commerce/admin-products`, `commerce/admin-orders`, …, `commerce/seed-store`, plus read-only `commerce/storefront-catalog` for enumerating product variations). Tool calls run **with the chatting user's credentials**, so `requireAdmin()` in every admin function still authorizes the actual user — the agent has no entity tools and no service-role shortcut; a non-admin chatting with it gets `401/403` from every admin operation.
+- **No `model` field, on purpose.** The platform's default-model path accepts slash-namespaced tool names; explicitly setting a `model` currently rejects them (LLM tool names must match `^[a-zA-Z0-9_-]{1,128}$`). If you set a model, the bot fails at message time with a `tools.0.custom.name` error.
+- **Variant safety** — the agent is instructed to never auto-pick a variation: for variable products it fetches `{product, variations}` via `commerce/storefront-catalog get-product`, presents the variations as a table, and asks the operator which `variation_id` to use before touching an order, stock, or download grant.
+- **Bot UI** — `src/commerce/admin/bot/` (chat panel; "StoreAdmin bot" launcher at the bottom of the admin sidebar). Responses render as markdown via `react-markdown`, with the agent's GFM tables (`| col |` with `|---|` separators) rendered by the template's own `bot/pipe-tables.js` — no markdown plugin dependency. The panel lives behind the same `AuthGuard` as the rest of the admin.
+- **Config it can't change, it links to.** Store settings, tax rates, shipping zones, gateways and webhook definitions have no function tool, so the agent is instructed to name the screen and emit an `admin:`-scheme link (`[Settings → Tax](admin:settings/tax)`) rather than telling the operator to "do it manually". `bot/Markdown.jsx` resolves `admin:` through `useAdminHref()`, so links follow your actual mount point (`basePath`) and navigate in-app instead of opening a tab. If you add screens, add the path to the table in the agent's instructions.
+
+**Do not weaken the tool set.** The agent's power comes only from the admin functions' own `requireAdmin()` layer — don't add entity tools or service-role calls to the agent config, and keep `commerce/storefront-*` tools limited to the read-only catalog.
+
+---
+
+## 4. Building on it — the four storefront requirements
+
+If your work includes a customer-facing shopfront, read **[`SKILL.md` → *If you build a storefront, these four are not optional*](./SKILL.md)** before writing it, and [`docs/api-storefront.md`](./docs/api-storefront.md)'s *Required behaviors* table. In short: attribute-level variant selectors resolved to a `variation_id`; shipping options presented and chosen; card payment redirect plus an `/order-received` page; and no offers the store isn't configured for. The API enforces the first three — a storefront that skips them cannot complete a purchase.
+
+## 5. Next steps
+
+Continue with [`post-installation.md`](./post-installation.md): embedding the admin pages (router mount, admin-role enforcement) and registering the template + skill in the app's `AGENTS.md`. After that, [`skills/commerce/SKILL.md`](./SKILL.md) is the map for all day-2 work.