@base44/app-plugin-commerce 0.1.20 → 0.2.2

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

@@ -1,10 +1,23 @@
 # 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. Storefront *logic* does ship on two levels: the framework-free helpers in `src/commerce/utils/` (API client, variant selection, free-shipping rules) and the React layer in `src/commerce/storefront/` (shared-cart provider, guided-checkout hook, headless shipping/payment pickers, order-received hook) — in a React app, build cart/checkout on those hooks and use this reference for what lies beyond them.
+The raw HTTP/SDK surface behind a customer-facing shopfront. **A React storefront should not call most of it directly** — `src/commerce/storefront/` ships the logic layer, and this file is the reference for what lies beyond it, for non-React and headless clients, and for the exact payloads and error codes.
+
+**Logic is premade, UI never is.** In a React app, every surface here has a headless hook in `@/commerce/storefront` — `useProductList`, `useProduct` (+ `variantAxes`, `useAddToCartButton`), `useCart`/`useCartLine`/`useCoupon`, `useCheckout` (+ `useAddressForm`, the pickers), `useOrderReturn`, `useProductReviews`, `useStorefrontSeo`. The hooks own the API calls and the branching below and hand you a view-model; **all markup and styling are yours** — nothing in the kit renders UI. Never hand-roll a hook's logic. Framework-free helpers (API client, variant resolution, price and totals rules, free-shipping rules) live in `src/commerce/utils/`.
+
+## Contents
+
+- [Required behaviors](#required-behaviors--a-storefront-that-skips-these-cannot-sell) (the four hard rules) · [capabilities](#what-the-api-already-gives-you-read-before-designing-the-ui) · [conventions](#conventions) (envelope, auth, money)
+- [`storefront-catalog`](#commercestorefront-catalog): [`get-store-info`](#get-store-info) · [`list-products`](#list-products) · [`get-product`](#get-product) · [`list-categories`](#list-categories) · [`list-ribbons`](#list-ribbons) · [`list-attributes`](#list-attributes) · [`submit-review`](#submit-review)
+- [`storefront-cart`](#commercestorefront-cart): [priced view](#the-priced-cart-view-returned-by-every-action) · [actions](#actions) · [`cart_token`](#cart_token--the-storefronts-one-job) · [**shipping rules**](#shipping-is-not-optional--read-this-before-building-checkout) · [never advertise unconfigured offers](#never-advertise-what-the-store-isnt-configured-to-do)
+- [`storefront-checkout`](#commercestorefront-checkout): [`place-order`](#place-order) · [`confirm-payment`](#confirm-payment) · [`cancel-order`](#cancel-order)
+- [`payments`](#commercepayments--online-payment-for-an-order): payment links, `complete-return` for `/order-received`
+- [`storefront-account`](#commercestorefront-account): orders, notes, downloads, addresses, my reviews
+- [Walkthrough A — guest checkout](#walkthrough-a--guest-checkout) · [B — member](#walkthrough-b--member-experience) (non-React clients)
+- Entities and direct CRUD → [`entities.md`](./entities.md) · admin surface → [`api-admin.md`](./api-admin.md)
 
 ## 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:
+The canonical statement. Each is enforced by the API, not a nicety:
 
 | # | Requirement | Enforced by |
 |---|---|---|
@@ -14,29 +27,29 @@ Read this list before writing any of it. Each item is a hard requirement enforce
 | 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 a location's shipping rates) | 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.
+Four public functions — **`storefront-catalog`**, **`storefront-cart`**, **`storefront-checkout`**, **`storefront-account`** — all invoked the same way, all returning 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.
+**Build to this surface, not to the basics** — everything below already exists server-side, so leaving it out ships a storefront weaker than the store behind it.
 
 | Capability | Already supported | Where |
 |---|---|---|
-| **Product discovery** | full-text `search`, filter by category (incl. descendants), ribbon, attribute+term, price range, `featured`, `on_sale`, `in_stock_only`; sort by name / price / **newest** (the default) / **popularity** / **rating**; paging | [`list-products`](#list-products) |
+| **Product discovery** | full-text `search`; filters: category (incl. descendants), ribbon, attribute+term, price range, `featured`, `on_sale`, `in_stock_only`; sort by name / price / **newest** (default) / **popularity** / **rating**; paging | [`list-products`](#list-products) |
 | **Rich product pages** | galleries, per-variant price/stock/image, categories, ribbons, **upsells**, **cross-sells** | [`get-product`](#get-product) |
-| **Taxonomy navigation** | category tree, **ribbon list with counts**, attributes + terms for filter UIs | [`list-categories`](#list-categories), [`list-ribbons`](#list-ribbons), [`list-attributes`](#list-attributes) |
-| **Customer reviews** | paginated reviews per product with **average rating + rating count**, `verified` owner flag, and **review submission by anyone with an email address** (no login); 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) — codes are admin-only data, so a store with coupons needs a **code field** somewhere in the buy path (cart or checkout) or they can never be redeemed | [`apply-coupon`](#commercestorefront-cart) |
-| **Shipping** | address → matched location → **selectable shipping rates with live costs**, free-over thresholds | [`set-shipping-address`](#commercestorefront-cart) |
-| **Tax** | inclusive/exclusive pricing, per-location tax groups, itemized 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 (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 — 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 })`.
+| **Taxonomy navigation** | category tree, **ribbons with counts**, attributes + terms for filter UIs | [`list-categories`](#list-categories) · [`list-ribbons`](#list-ribbons) · [`list-attributes`](#list-attributes) |
+| **Customer reviews** | paginated per product with **average rating + count**, `verified` flag, **submission by anyone with an email** (no login), "my reviews" | [`submit-review`](#submit-review) |
+| **Cart** | guest carts via `cart_token`, add/update/remove, quantity merging, `sold_individually` caps, live re-pricing, stock revalidation | [`storefront-cart`](#commercestorefront-cart) |
+| **Coupons** | apply/remove by code, fully validated server-side (eligibility, limits, per-user usage). Codes are admin-only data, so a store with coupons needs a **code field** in the buy path or they can never be redeemed | [`apply-coupon`](#actions) |
+| **Shipping** | address → matched location → **selectable rates with live costs**, free-over thresholds | [`set-shipping-address`](#actions) |
+| **Tax** | inclusive/exclusive pricing, per-location tax groups, itemized display — resolved server-side | [`get-store-info`](#get-store-info) |
+| **Stock states** | in stock / out of stock / **on backorder**, low-stock signalling, out-of-stock hiding | [`list-products`](#list-products) |
+| **Checkout** | guest or authenticated, billing/shipping, per-gateway routing, **payment instructions** for manual methods, cancel, post-payment confirm | [`storefront-checkout`](#commercestorefront-checkout) |
+| **Accounts** | order history, saved addresses, **guest order tracking by `order_key`** with customer-visible notes | [`storefront-account`](#commercestorefront-account) |
+| **Digital products** | entitlement-checked downloads with remaining-count, expiry, signed URLs for private files | [`get-download`](#commercestorefront-account) |
+| **Store config** | currency, units, catalog/cart price display — honour it instead of hardcoding | [`get-store-info`](#get-store-info) |
+
+Not in the backend: the visitor UI (all of it is yours — the hooks above carry the logic), and the card-payment provider integration, which only a store that opts into cards needs — cards are off by default, the decision and its timing live in [`../install/03-data.md`](../install/03-data.md), the provider code in [`../references/online-payments.md`](../references/online-payments.md). Payment methods and the currency are admin-owned data — always render them from `get-store-info`, never a hardcoded list, and format prices with `Intl.NumberFormat(undefined, { style: "currency", currency })`.
 
 ## Conventions
 
@@ -45,8 +58,8 @@ Two things that are **not** in the backend and are yours to build: the visitor U
   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.
+- **Auth modes:** most actions are anonymous. Some require an authenticated Base44 session (marked **auth**). Two bearer credentials (HTTPS only): `order_key` for guest order access, `cart_token` for the cart — whose lifecycle rules are [in the cart section](#cart_token--the-storefronts-one-job).
+- **Identity is never a payload field.** Anything attributed to a person — a review's author, a saved profile — comes from the session. An email in the body does not make you that customer, and no request can assert that an order was paid. A feature built on client-supplied identity 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.
 
@@ -72,9 +85,9 @@ Bootstrap data for a storefront. No payload.
   "currencies": [ { "code": "USD", "name": "US Dollar", "symbol": "$", "decimals": 2 } ]
 }
 ```
-`settings` is a safe projection — only display/behavior keys, never admin config.
+`settings` is a safe projection — display/behavior keys only, never admin config.
 
-`payment_gateways` is **every gateway the admin has enabled** (sorted by their `order`) — the Payments settings switch is the single source of truth, so render this list and never a hardcoded one. The sample above shows both shapes, but a **default-seeded store reports `offline` alone**: cards are off by default and appear only once the gateway is enabled — which should only happen with a provider wired ([`post-installation.md` §4.1](../post-installation.md#41-off-by-default--enable-only-with-a-provider-wired)) — so expect the one-method case in a fresh store. `online: true` marks the card option (`place-order` answers with a payment page to redirect to; `503 no_card_payment_provider` if it was enabled with no provider behind it); everything else settles manually.
+`payment_gateways` is **every gateway the admin has enabled** (sorted by `order`) and this call is its **only** source — `cart.payment_gateways` does not exist, and a hardcoded list is a broken checkout. A **default-seeded store reports `offline` alone** (cards are off by default — [`../install/03-data.md`](../install/03-data.md)), so expect the one-method case. `online: true` marks the card option (`place-order` answers with a payment page; `503 no_card_payment_provider` if it was enabled with no provider behind it); everything else settles manually. In React: `useStoreInfo()` + `PaymentMethodPicker`.
 
 ### `list-products`
 **Payload** (all optional): `search`, `category_id` (includes descendants), `ribbon_id`, `attribute_id` + `attribute_term`, `min_price`, `max_price`, `featured` (bool), `on_sale` (bool), `in_stock_only` (bool), `sort` (`-created_date`|`name`|`price`|`-price`|`popularity`|`rating`, default `-created_date`), `page` (default 1), `per_page` (default 12, max 100).
@@ -83,25 +96,21 @@ Only `status: "publish"` products are returned — the admin's single **Visible*
 
 **Response:** `{ "products": [Product...], "page": 1, "per_page": 12, "has_next": true }`
 
-Each row is the product record (minus paywalled fields) **plus a resolved `ribbons` array** (`[{ id, name }]`), so cards can show their ribbons without a second call. `categories` are **not** resolved on rows — `category_ids` only.
+Each row is the product record (minus paywalled fields) **plus a resolved `ribbons` array** (`[{ id, name }]`), so cards show ribbons without a second call. `categories` are **not** resolved — `category_ids` only. What a row can and can't show, and how to add a `get-product`-only field to this call instead of fetching per card: [`../references/catalog-rendering.md`](../references/catalog-rendering.md).
 
-> **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, ribbons 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** — all of them 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.
 
-**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:
+**The same call serves every short strip** — homepage hero, "featured" row, "new in" rail, related picks. `per_page` bounds it and the filters/sort choose what lands in it, so a curated slice is one request; there is no separate endpoint and no reason to fetch a big page and slice client-side:
 
 ```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 });
+await cat({ featured: true, per_page: 4 });                     // curated: the admin's own star flag
+await cat({ sort: "-created_date", per_page: 6 });              // new in
+await cat({ on_sale: true, in_stock_only: true, per_page: 4 }); // deals
+await cat({ category_id, sort: "popularity", per_page: 4 });    // top in category
 ```
 
-`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.
+`featured` is the admin's per-product flag (`commerce/seed-store` accepts `featured: true`), so a featured strip is store data, not slugs pinned in the UI. **A filter may legitimately match nothing** (nothing starred, nothing discounted) — drive the block off the returned array's length, hiding it or falling back to another slice, rather than assuming rows came back; `has_next` says whether a "see all" has more behind it. In React this is `useProductList`.
 
 ### `get-product`
 **Payload:** `{ id }` **or** `{ slug }`; optional `reviews_page` (1), `reviews_per_page` (10, max 50).
@@ -122,19 +131,15 @@ const { products: topInCat } = await cat({ category_id, sort: "popularity", per_
 ```
 **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** (Size, Color, …) — every attribute is an axis — and resolve the combination to a variation client-side; `add-item` needs that `variation_id`. Variant prices come from `variations[]`, never from `product.price` (the backend rolls stock up to the parent, not price). The shipped helper does all of it:
+> **`variations[]` is not a list of choices to show.** Build **one control per `product.attributes[]` entry** (Size, Color, …) — every attribute is an axis — and resolve the combination to a variation client-side; `add-item` needs that `variation_id`. Variant prices come from `variations[]`, never from `product.price` (the parent's price is a rolled-up from-price). A React page gets all of this from `useProduct` + `useAddToCartButton` (map `variantAxes(view, pick)` into your controls, gate on `view.purchasable`); a non-React client uses the framework-free resolver:
 > ```js
 > import { resolveSelection, defaultSelection, selectOption } from "@/commerce/utils";
-> const [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
+> const view = resolveSelection(product, variations, selection);  // selection from defaultSelection(), updated via selectOption()
+> // view.axes → one control per axis          view.display → image/price/sku/stock of the resolved variation
+> // view.availability[axis.key][option] → "available" | "out_of_stock" | "unavailable"  (disable, don't hide)
 > // 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).
+> Field availability per view, ribbons, from-price rules and the variant deep-dive (availability states, incomplete-selection pricing, URL round-trip): [`../references/catalog-rendering.md`](../references/catalog-rendering.md).
 
 ### `list-categories`
 No payload. Returns a nested tree: `{ "categories": [ { ...category, "children": [...] } ] }` sorted by `menu_order` then name.
@@ -144,19 +149,19 @@ No payload. Returns a nested tree: `{ "categories": [ { ...category, "children":
 
 Returns `{ "ribbons": [ { id, name, count } ] }` sorted by name. By default it omits ribbons no published product carries, so a ribbon 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 and honoring `inventory.hide_out_of_stock` — **not** from `ProductRibbon.count`, which also counts drafts and drifts until `commerce/admin-tools` `recount-terms` runs. So `Gift (12)` and the ribbon's listing agree.
+`count` is tallied from the products this API would actually list (published, honoring `inventory.hide_out_of_stock`) — **not** from `ProductRibbon.count`, which also counts drafts and drifts until `admin-tools` `recount-terms` runs. So `Gift (12)` and the ribbon's listing agree.
 
-This is the **only** way a storefront can enumerate ribbons — `commerce.ProductRibbon` is admin-only RLS — and it's what makes `list-products` `ribbon_id` usable, since that filter needs an id. Ribbons are flat, cross-cutting labels ("Best Seller", "New", "Gift"); categories are the hierarchical spine. Show both: see [*Ribbons*](../references/product-render.md#2-ribbons--render-them-in-both-views) for where they belong in each view.
+This is the **only** way a storefront can enumerate ribbons (the entity is admin-only) and what makes `list-products` `ribbon_id` usable, since that filter needs an id. Ribbons are flat, cross-cutting labels; categories are the hierarchical spine — show both ([`../references/catalog-rendering.md`](../references/catalog-rendering.md)). In React: `useRibbons` / `useCategories`.
 
 ### `list-attributes`
-No payload. Returns `{ "attributes": [ { ...attribute, "terms": [ ...values ] } ] }` — the whole attribute record (`id, name, code, order`) plus its values (`id, attribute_id, name, order, count`), attributes sorted by `order` and each attribute's values by their own `order` — for building filter UIs. Filter with `list-products` `attribute_id` (the id, or the attribute **name**) + `attribute_term` (the value name); `code` is the stable key to put in a URL.
+No payload. Returns `{ "attributes": [ { ...attribute, "terms": [ ...values ] } ] }` — each attribute (`id, name, code, order`) with its values (`id, attribute_id, name, order, count`), both sorted by `order`; for filter UIs. Filter with `list-products` `attribute_id` (id or attribute **name**) + `attribute_term` (the value name); `code` is the stable key for a URL.
 
 ### `submit-review`
 **Payload:** `{ product_id, reviewer?, review, rating }`.
 
-**Public by default: anyone can review with an email address — no login.** A guest passes `email` in the payload; for a signed-in caller the session email always wins (the payload cannot impersonate). `reviewer` is the display name only — it defaults to the account's `full_name`, then the email's local part. `rating` is optional (0–5). `verified` is derived from the email's order history (`processing`/`completed` order containing the product). Status is `hold` unless `products.auto_approve_reviews` — the one server-side review switch.
+> A React storefront gets the whole reviews surface — this call, the paginated list from `get-product`, refresh, and the store's moderation policy — from **`useProductReviews`**; don't hand-roll it. Read on for the raw contract.
 
-Any stricter policy is the **storefront's** to enforce in its UI — login-gated forms, verified-buyers-only, a required rating: see [`../references/reviews.md`](../references/reviews.md) for the patterns.
+**Public by default: anyone can review with an email address — no login.** A guest passes `email`; for a signed-in caller the session email always wins (the payload cannot impersonate). `reviewer` is the display name only, defaulting to the account's `full_name` then the email's local part. `rating` is optional (0–5). `verified` is derived from the email's order history. Status is `hold` unless `products.auto_approve_reviews` — the one server-side switch, so a hardcoded "awaiting approval" message is wrong when it is on. Stricter policies (login-gated, verified buyers only, rating required) are a `policy` option on the hook, not code you write: [`../references/reviews.md`](../references/reviews.md).
 
 **Response:** `{ "review_id", "status": "hold"|"approved", "verified": true }`
 **Errors:** `404 not_found`, `400 email_required|review_incomplete|invalid_rating`.
@@ -165,7 +170,7 @@ Any stricter policy is the **storefront's** to enforce in its UI — login-gated
 
 ## 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).
+Token-scoped cart (guest + member). Every action **except `create`** takes `cart_token`, and **every mutating action returns the full priced cart view**. 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
@@ -193,7 +198,7 @@ Token-scoped cart (guest + member). Every action **except `create`** takes `cart
   "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`.
+Coupons that stop validating are **auto-removed** and reported in `coupon_notices`; items whose product vanished or was unpublished appear in `removed_items`. In React `useCart` exposes this view as `lines` + `notices`.
 
 ### Actions
 | Action | Payload | Notes / errors |
@@ -201,17 +206,22 @@ Stored coupons that stop validating are **auto-removed** and reported in `coupon
 | `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? }` | **Self-healing:** a missing, unknown or expired `cart_token` starts a fresh cart and adds the item to it — the response carries the new `cart_token`, so **always persist the token from the response** (see the note below the table). A product carrying attributes 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`. |
+| `add-item` | `{ cart_token?, product_id, variation_id?, quantity?, attributes? }` | **Self-healing:** a missing, unknown or expired `cart_token` starts a fresh cart and adds the item to it ([token rules](#cart_token--the-storefronts-one-job)). A product carrying attributes 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 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 location's `available_shipping_methods` and a `shipping_status`. **Fails immediately with `400 shipping_not_available`** when the store doesn't ship to the address (the error body carries the priced `cart`) — the caller learns on address entry, not at place-order. |
-| `choose-shipping-method` | `{ cart_token, method_id }` | `method_id` = a shipping rate `id` from `available_shipping_methods`. `400 invalid_shipping_method` (the error body carries `available_shipping_methods`). |
+| `set-shipping-address` | `{ cart_token, address: {country, state?, postcode?, city?} }` | Returns the matched location's `available_shipping_methods` + `shipping_status`. `400 country_required`; `400 shipping_not_available` when the store doesn't ship there (error body carries the priced `cart`). [Rules ↓](#shipping-is-not-optional--read-this-before-building-checkout) |
+| `choose-shipping-method` | `{ cart_token, method_id }` | `method_id` = a shipping rate `id` from `available_shipping_methods`. `400 invalid_shipping_method` (error body carries `available_shipping_methods`). |
 
 Common: `400 cart_token_required`, `404 cart_not_found`, `404 cart_expired` — except `add-item`, which never fails on the token: it starts a fresh cart instead.
 
-> **Handle your cart_token cache.** Cart tokens expire (48h rolling TTL) and carts are consumed at checkout, so a token cached in `localStorage` can go stale. `add-item` heals this by starting a fresh cart — but only if the storefront **reads `cart_token` from every cart response and re-persists it** instead of assuming the stored one survived. Do that after every cart call, and treat `404 cart_not_found|cart_expired` from the other actions as "clear the cached token and start over" rather than an error to show.
+### `cart_token` — the storefront's one job
+<a id="cart_token--the-storefronts-one-job"></a>
+
+The token is the cart's bearer credential (treat it as a secret) and the **only** cart state a client keeps. Tokens expire (48h rolling TTL) and carts are consumed at checkout, so one cached in `localStorage` can go stale. `add-item` heals that by starting a fresh cart — but only if the client **reads `cart_token` from every cart response and re-persists it** instead of assuming the stored one survived. Do that after every cart call, and treat `404 cart_not_found|cart_expired` from the other actions as "clear the cached token and start over", not as an error to show.
+
+**In React none of this is yours:** `StorefrontProvider` owns the token and `useCart` exposes the priced view — never read, store or send the token yourself.
 
 ### Shipping is not optional — read this before building checkout
 <a id="shipping-is-not-optional--read-this-before-building-checkout"></a>
@@ -222,40 +232,42 @@ 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 |
+| `not_needed` | every line is virtual, or shipping is off store-wide | show no shipping step |
+| `auto_selected` | exactly **one** method offered, already applied | 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 |
-| `missing_address` | the options can't be determined until an address is set (several locations defined, none yet matchable) | collect the address and call `set-shipping-address` — shipping cost is not calculated yet |
-| `none_available` | nothing ships to this address | say so, and don't let checkout proceed (`set-shipping-address` already failed `shipping_not_available` when this address was set) |
+| `choice_required` | **several** offered, none chosen | render `available_shipping_methods`, call `choose-shipping-method` — checkout refuses until then |
+| `missing_address` | options undeterminable until an address is set (several locations, none matchable yet) | collect the address, call `set-shipping-address`; cost is not calculated yet |
+| `none_available` | nothing ships to this address | say so and block checkout (`set-shipping-address` already failed `shipping_not_available`) |
 
 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 single location answers before the address.** A store with exactly **one** Shipping & Tax Location gets that location's rates (and, via auto-select, a shipping cost) on the cart with no address set — its options are the same everywhere. With several locations the cart reports `missing_address` until `set-shipping-address` resolves one.
-- **An unsupported address fails on entry.** `set-shipping-address` returns `400 shipping_not_available` the moment a validated address matches no location (e.g. the store's one location doesn't cover it) — surface it on the address form instead of letting the customer reach payment.
-- **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 **call `set-shipping-address` as soon as the customer provides an address and re-read the returned cart after every mutation**; never carry an options list you fetched earlier.
+- **A single available method is auto-selected.** One option is not a choice, and requiring a round trip for it is how a storefront ends up never sending a method at all.
+- **A single location answers before the address.** A store with exactly **one** location gets its rates (and, via auto-select, a cost) with no address set — the options are the same everywhere. With several, the cart reports `missing_address` until `set-shipping-address` resolves one.
+- **An unsupported address fails on entry**, with `400 shipping_not_available` — surface it on the address form instead of letting the customer reach payment.
+- **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 one remains) rather than silently pricing zero shipping.
+- **Costs change with the cart** — free-shipping thresholds and coupon-gated methods appear and disappear, so **call `set-shipping-address` as soon as an address exists and re-read the cart after every mutation**; never carry an options list you fetched earlier.
+
+What `place-order` does with all this: a single offered method is applied for you; several offered with none chosen is `400 shipping_method_required` (with `available_shipping_methods` in the error body); a `chosen_shipping_method` not offered for the address is `400 invalid_shipping_method`, never silently swapped; nothing offered is `400 no_shipping_available`. No order is created in any of those cases, and the order that is created prices the resolved method, so its `shipping_total` always matches what the customer was shown.
+
+**In React this is `useCheckout`**: address state debounces into `set-shipping-address`, `ShippingMethodPicker` renders the options, and `canPlaceOrder` blocks with a named blocker until a method resolves — the whole table above is the hook's behavior, not code you write. Location/zone/tax configuration: [`../references/shipping-and-tax.md`](../references/shipping-and-tax.md).
 
 ### 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.
+Copy like *"Free shipping on orders over €150"* is a **claim about store configuration**, and checkout honours only what is configured. Don't write such a line unless a matching rule exists — configure it (with the operator's agreement) or leave the copy out. The same goes for a discount claim (it needs a real `commerce.Coupon`, and only a code the operator gave you) and for delivery-time or returns promises the template cannot enforce.
 
-**Locations are admin-only data.** `commerce.ShippingTaxLocation` is `read: {role: "admin"}` like every entity, so a visitor cannot list them — do not try. Two honest sources:
+**Locations are admin-only data** like every entity, so a visitor cannot list them — do not try. Two honest sources:
 
-1. **The cart itself**, which is the live answer for a real address: after `set-shipping-address`, `available_shipping_methods` already reflects every rule the checkout will honour, free shipping included. Prefer this.
-2. **A projection you add**, if you want a threshold banner *before* an address exists: widen `get-store-info` (or add an action) to return the free-shipping rules, then normalize them with [`src/commerce/utils/shipping-promos.js`](../../../src/commerce/utils/shipping-promos.js):
+1. **The cart** — the live answer for a real address: after `set-shipping-address`, `available_shipping_methods` reflects every rule checkout will honour, free shipping included. Prefer this.
+2. **A projection you add**, for a threshold banner *before* an address exists: widen `get-store-info` (or add an action) to return the free-shipping rules, then normalize them:
 
 ```js
 import { freeShippingRules, freeShippingThreshold, freeShippingProgress } from "@/commerce/utils";
-
-// locations come from your own storefront action — NOT from a client entity read
-const threshold = freeShippingThreshold(freeShippingRules(locations));
-// null → the store has no free-shipping rule: show no banner, no progress bar.
+// locations come from your own storefront action — NOT a client entity read
+const threshold = freeShippingThreshold(freeShippingRules(locations));  // null → no rule: no banner
 const progress = freeShippingProgress(threshold, cart.totals.subtotal - cart.totals.discount_total);
 ```
 
-A free-shipping rule is a shipping rate that is free (`cost: 0`) or carries a `free_over` threshold (thresholds are **per location** — a rule in one location 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.
+A free-shipping rule is a rate that is free (`cost: 0`) or carries a `free_over` threshold. Thresholds are **per location** — a rule in one location must not become a site-wide banner.
 
 ---
 
@@ -272,31 +284,13 @@ Converts a cart into an order. **Payload:**
 ```
 **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
-  // the moment the customer provides an address — this recalculates the options and cost;
-  // an unsupported address fails right here with 400 shipping_not_available
-  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 });
-  }
-  // auto_selected / chosen: nothing to do, one option was applied for you
-  // (a single-location store may show auto_selected before any address is set)
-  ```
-  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.
+- **Shipping address** and a **shipping method** whenever the cart has any non-virtual line and shipping is enabled. Set the address on the cart first (`set-shipping-address`); the method comes either from the cart (`choose-shipping-method`) or from this call's `chosen_shipping_method`, which wins if both are present. Skipping it is the most common storefront bug — the rules, the `shipping_status` branches and the four error codes are in [**Shipping is not optional**](#shipping-is-not-optional--read-this-before-building-checkout).
 
-> **Payment.** `payment_method` is a `commerce.PaymentGateway` slug from `get-store-info`. Choosing the **card** gateway leaves the order `pending` and returns `payment: { status: "requires_payment", checkout_url, reference }` — send the customer to `checkout_url` (the provider's hosted page), then confirm on their return with `commerce/payments` `complete-return`. Never treat a return URL as proof of payment. While the store has no payment provider implemented the card gateway fails with `503 no_card_payment_provider` — tell the customer card payment is unavailable and offer the other methods. **Every other gateway is manual** (offline, and any option the admin added in Settings → Payments): the order goes on-hold and `payment_instructions` carries the gateway's description and bank accounts. Optional `success_url` / `cancel_url` / `return_url` in the payload override the default return URLs. See [`../references/online-payments.md`](../references/online-payments.md).
+> **Payment.** `payment_method` is a gateway slug from [`get-store-info`](#get-store-info). The **card** gateway leaves the order `pending` and returns `payment: { status: "requires_payment", checkout_url, reference }` — redirect to `checkout_url`, then confirm on the return with [`complete-return`](#commercepayments--online-payment-for-an-order); a return URL is never proof of payment. **Every other gateway is manual** (offline, plus anything the admin added): the order goes on-hold and `payment_instructions` carries the gateway's description and bank accounts. `success_url`/`cancel_url`/`return_url` override the default return URLs.
 
-**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: **card → stays pending** until the hosted page is paid, **everything else → on-hold** (with `payment_instructions`).
+**Steps:** release expired holds → revalidate stock & coupons → authoritative totals → find-or-create the Customer by billing email → create a `pending` order (`order_key`, `hold_expires_at`) → reduce stock, fire `new_order` email + `order.created` webhook → mark the cart `converted` → route by gateway: **card stays pending** until the hosted page is paid, **everything else goes on-hold** with `payment_instructions`.
 
-> **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.
+> **Saved profiles are only written by their owner.** The order always stores the `billing`/`shipping` it was placed with, but the `commerce.Customer` record 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 (it shows up in their `my-orders`) without changing their saved details — so no "edit my details at checkout" for guests; use `update-my-addresses` behind a login.
 
 **Response:**
 ```json
@@ -312,31 +306,26 @@ Converts a cart into an order. **Payload:**
   "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`, `503 no_card_payment_provider` (card gateway chosen but no provider is implemented — the order exists as `pending` and its stock hold expires on its own; offer another method).
+**Errors:** `401 login_required` (guest checkout disabled), `400 billing_incomplete`, `400 empty_cart`, `409 items_unavailable`, `409 coupon_invalid`, the three shipping codes above (each carrying `available_shipping_methods`), `400 invalid_payment_method`, `503 no_card_payment_provider` (card chosen, no provider implemented — the order exists as `pending`, its stock hold expires on its own; offer another 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).
+Separate function, same guest-bearer rule: `order_id` + `order_key` (an admin may act without a key). The admin-side view of these actions is in [`api-admin.md`](./api-admin.md#commercepayments).
 
 | Action | Payload | Returns |
 |---|---|---|
-| `create-link` | `{ order_id, order_key, success_url?, cancel_url?, return_url? }` | `{ url, reference }` — a fresh hosted payment page for an **unpaid** order, whatever its current payment method (the order is switched onto the card 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 card_payments_disabled` (the store turned card payment off), `503 no_card_payment_provider` |
-| `complete-return` | `{ order_id, order_key, payment?, return_url? }` | `{ state: "paid"\|"cancelled"\|"unpaid", paid, already_confirmed, status, order, payment_link, payment_instructions }` — the whole return flow in one call for your `/order-received` page: confirms with the provider, progresses the order, includes a fresh `payment_link: { url, reference }` while unpaid (card orders), and re-supplies `payment_instructions: { type, description, account_details }` for unpaid **manual** orders so the page can render bank details on every visit. `payment` is only a hint; a hand-edited `?payment=success` can never yield `paid`. **Note:** `order` carries flat totals (`order.total`, `order.shipping_total`) — there is no `order.totals` object; that nested shape belongs to the cart view |
-| `verify` | `{ order_id, order_key }` | `{ paid, already_confirmed, status, order }` — the same confirmation without the render-ready extras. **Idempotent**: call it on every return, and as often as you like. Whether money arrived is asked of the provider about the payment reference stored on the order |
+| `create-link` | `{ order_id, order_key, success_url?, cancel_url?, return_url? }` | `{ url, reference }` — a fresh hosted payment page for an **unpaid** order whatever its current method (it is switched onto the card gateway, logged): "pay now" on an order-received page or an emailed link. `409 already_paid`, `400 card_payments_disabled`, `503 no_card_payment_provider` |
+| `complete-return` | `{ order_id, order_key, payment?, return_url? }` | `{ state: "paid"\|"cancelled"\|"unpaid", paid, already_confirmed, status, order, payment_link, payment_instructions }` — the whole return flow in one call: confirms with the provider, progresses the order, adds a fresh `payment_link: { url, reference }` while a card order is unpaid, and re-supplies `payment_instructions: { type, description, account_details }` for unpaid **manual** orders so bank details render on every visit. `payment` is only a hint — a hand-edited `?payment=success` can never yield `paid`. **`order` carries flat totals** (`order.total`, `order.shipping_total`); there is no `order.totals` — that shape belongs to the cart view |
+| `verify` | `{ order_id, order_key }` | `{ paid, already_confirmed, status, order }` — the same confirmation without the render-ready extras. **Idempotent**; money is asked of the provider about the reference stored on the order |
 
-> **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).
+> **The `/order-received` route is mandatory** (requirement 4): without it a paying customer lands on a 404 *and* the order is never marked paid. It only has to call `complete-return` and render its three states — `useOrderReturn` does exactly that (your markup renders the states, including `paymentInstructions`).
 
-Provider callbacks land on `commerce/payment-webhook` (server-to-server) — the second confirmation path, for buyers who pay and close the tab. Whichever path runs second is a no-op. The webhook function is premade (it verifies through the provider's API, so no signing secret); wiring a payment provider means implementing four functions in one file — see [`../references/online-payments.md`](../references/online-payments.md).
+Provider callbacks land on `commerce/payment-webhook` (server-to-server) — the second confirmation path, for buyers who pay and close the tab; whichever path runs second is a no-op. That function is premade (it verifies through the provider's API, so no signing secret). Wiring a provider: [`../references/online-payments.md`](../references/online-payments.md).
 
 ### `confirm-payment`
-Post-payment hook for an order on the card gateway. **Payload:** `{ order_id, order_key }`.
+The bare transition for a card order — `complete-return` is the richer version and what `/order-received` should call. **Payload:** `{ order_id, order_key }` → `{ order, paid, already_confirmed }`.
 
-**The request cannot make an order paid.** The `order_key` says who is asking; the payment itself is confirmed against the provider using the payment reference stored on the 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_a_card_payment`, `404 order_not_found`, `409 invalid_status|payment_not_confirmed`.
+**The request cannot make an order paid.** The `order_key` says who is asking; payment is confirmed against the provider using the reference stored on the order. Only then does it move `pending`/`on-hold` → `processing`, set `date_paid` and bump customer stats. No caller-supplied `transaction_id`. Idempotent. **Errors:** `400 order_key_required|not_a_card_payment`, `404 order_not_found`, `409 invalid_status|payment_not_confirmed`.
 
 ### `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`.
@@ -353,28 +342,30 @@ Two access modes: **auth** (Base44 session) or **`order_key` bearer** (guest tra
 | `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 |
+| `get-download` | auth **or** order_key | `{ permission_id, order_key? }` | `{ url, download_name, downloads_remaining }` — decrements remaining, enforces `access_expires` |
 | `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`.
 
+> **Public vs. private files.** A download's `file_url` is whatever the admin stored: `Core.UploadFile` gives a public URL, handed back as-is. For files that must not be guessable, upload with **`Core.UploadPrivateFile`** — it stores a `file_uri` rather than an `http` URL, and `get-download` detects the non-`http` scheme and returns a short-lived **signed URL** (`Core.CreateFileSignedUrl`, 1h) instead. Either way the entitlement check, the `downloads_remaining` decrement and `access_expires` are enforced here — never link a customer straight to a stored URL.
+
 ---
 
 ## Walkthrough A — guest checkout
 
+Raw-call sequence for a non-React client (a React app gets this from `useCart` + `useCheckout`).
+
 ```js
 const inv = (fn, payload) => base44.functions.invoke(fn, payload).then(r => r.data.data);
 
-// 1. Browse
+// 1. Browse, then 2. open a cart with one item
 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;
+const token = cart.cart_token;   // re-read it from every response
 
-// 3. (product with variants) fetch options, then add the chosen variation
+// 3. (variants) fetch the options, then add the chosen variation
 const detail = await inv("commerce/storefront-catalog", { action: "get-product", id: products[0].id });
 if ((detail.product.attributes ?? []).length) {
   cart = await inv("commerce/storefront-cart", { action: "add-item",
@@ -384,10 +375,7 @@ if ((detail.product.attributes ?? []).length) {
 // 4. Coupon (optional)
 cart = await inv("commerce/storefront-cart", { action: "apply-coupon", cart_token: token, code: "welcome10" });
 
-// 5. Shipping address → method. Call this as soon as the address is known — it
-//    recalculates the options and cost; an unsupported address fails right here
-//    (400 shipping_not_available). A single option is already applied for you;
-//    several mean the customer has to choose or checkout will refuse.
+// 5. Shipping: address as soon as it's known, then a method if asked for one
 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") {
@@ -396,24 +384,23 @@ if (cart.shipping_status === "choice_required") {
     cart_token: token, method_id: picked.id });
 }
 
-// 6. Place the order (offline → on-hold; no money has arrived yet)
+// 6. Place it (offline → on-hold; no money has arrived yet)
 const order = await inv("commerce/storefront-checkout", { action: "place-order",
   cart_token: token, payment_method: "offline",
   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)
+// 7. Track it later without an account, using 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)
+Same, for an authenticated caller (the SDK sends the session automatically).
 
-// Browsing carts made while logged out merge into this one automatically on `get`/`create`.
+```js
+// 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
@@ -425,7 +412,7 @@ const order = await inv("commerce/storefront-checkout", { action: "place-order",
   cart_token: cart.cart_token, payment_method: "offline", billing: { /* ... */ } });
 // offline → on-hold; show order.payment_instructions.account_details
 
-// Order history, downloads, reviews (all auth, no order_key needed)
+// 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 });