@base44/app-plugin-commerce 0.1.6 → 0.1.7

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

@@ -14,10 +14,9 @@ Two access styles. **Reads are direct** entity SDK calls; **mutations with side
 | commerce.Coupon | direct | **`commerce/admin-coupons`** | code normalization/uniqueness, webhooks |
 | commerce.Customer | direct | **`commerce/admin-customers`** | email uniqueness, invite/link, stats |
 | commerce.ProductReview | direct | **`commerce/admin-reviews`** | rating recalculation |
-| commerce.ProductCategory, commerce.ProductTag | direct | **direct CRUD**, or `commerce/admin-products` `save-term`/`delete-term`/`list-terms` (the API/agent path) | category slug uniqueness; tag get-or-create by name |
+| commerce.ProductCategory, commerce.ProductRibbon | direct | **direct CRUD**, or `commerce/admin-products` `save-term`/`delete-term`/`list-terms` (the API/agent path) | category slug uniqueness; ribbon get-or-create by name |
 | commerce.ProductAttribute, commerce.ProductAttributeTerm | direct | **direct CRUD**, or `commerce/admin-products` `save-term`/`delete-term`/`list-terms` (the API/agent path) | attribute `code` uniqueness; value rename rewrites products; attribute delete cascades its values |
-| commerce.ShippingClass | direct | **direct CRUD** | plain config; RLS enforces admin-only |
-| commerce.TaxClass, commerce.TaxRate, commerce.ShippingZone, commerce.ShippingZoneMethod, commerce.PaymentGateway | direct | **direct CRUD** | config; consumed by the pricing engine at read time |
+| commerce.ShippingTaxLocation, commerce.PaymentGateway | direct | **direct CRUD** | config; consumed by the pricing engine at read time |
 | commerce.StoreSettings | direct | **direct CRUD** (one record per `group_id`) | grouped config |
 | commerce.Webhook | direct | **direct CRUD** (+ `commerce/admin-webhooks` for test/redeliver) | definition is data; dispatch is engine |
 | commerce.WebhookDelivery, commerce.EmailLog | direct (read-only logs) | written by the engine | audit logs |
@@ -45,26 +44,26 @@ Success: `{ success: true, data }`. Failure: `{ success: false, error, code }` w
 Actions: `save` · `delete` · `batch` · `duplicate` · `set-stock` · `search` · `save-term` · `delete-term` · `list-terms`
 
 - **`save`** — `{ product, variations? }`. Upserts the product (create if no `id`); when `variations` is provided, diffs them (create/update/delete-missing).
-  > **Selling variants takes both of these in *this* call**: the attribute listed **on the product** as `attributes: [{ attribute_id, name, position, options: [...] }]`, plus a `variations` array with one entry per stocked combination (each `{ attributes: [{ attribute_id, name, option }], sku, regular_price, manage_stock: "yes", stock_quantity, status: "publish" }`) and `default_attributes` for the pre-selected combination. There is **no `type` field**: carrying attributes is what makes a product sell variants, so a `commerce.ProductAttribute` record on its own changes nothing — and a product listing an attribute with no variations cannot be added to a cart at all (`400 variation_required`). Descriptive properties belong in `meta_data`, not `attributes`. **Don't set the parent's price** — `regular_price`, `price` and `on_sale` are derived from the cheapest publishable variant on every save, which is what makes catalog cards, price sorting and price filters agree. Enforces SKU + slug uniqueness across products *and* variations (auto-suffixes slug on collision; `duplicate_sku` on SKU clash). Derives `price`/`on_sale` from the sale window and `stock_status` when stock is managed; updates category/tag `count`; rolls parent stock **and price** up when the product has attributes; fires `product.created`/`product.updated`. → `{ product, variations }`.
+  > **Selling variants takes both of these in *this* call**: the attribute listed **on the product** as `attributes: [{ attribute_id, name, position, options: [...] }]`, plus a `variations` array with one entry per stocked combination (each `{ attributes: [{ attribute_id, name, option }], sku, regular_price, manage_stock: "yes", stock_quantity, status: "publish" }`) and `default_attributes` for the pre-selected combination. There is **no `type` field**: carrying attributes is what makes a product sell variants, so a `commerce.ProductAttribute` record on its own changes nothing — and a product listing an attribute with no variations cannot be added to a cart at all (`400 variation_required`). Descriptive properties belong in `meta_data`, not `attributes`. **Don't set the parent's price** — `regular_price`, `price` and `on_sale` are derived from the cheapest publishable variant on every save, which is what makes catalog cards, price sorting and price filters agree. Enforces SKU + slug uniqueness across products *and* variations (auto-suffixes slug on collision; `duplicate_sku` on SKU clash). Derives `price`/`on_sale` from the sale window and `stock_status` when stock is managed; updates category/ribbon `count`; rolls parent stock **and price** up when the product has attributes; fires `product.created`/`product.updated`. → `{ product, variations }`.
 - **`delete`** — `{ id }`. Cascades variations, decrements counts, fires `product.deleted`.
 - **`batch`** — `{ create?: [], update?: [], delete?: [] }` (≤100 total) → per-item results.
 - **`duplicate`** — `{ id }` → new draft copy (name "(Copy)", suffixed SKU, reset sales/ratings) incl. variations.
 - **`set-stock`** — `{ id, variation_id?, quantity }`. Sets quantity, re-derives status, sends low/out-of-stock admin emails on threshold crossings.
 - **`search`** — `{ q?, category_id?, stock_status?, status?, sort?, limit?, skip? }` → `{ rows, has_next }`. `category_id` includes descendant categories.
-- **`save-term`** — `{ taxonomy, term }` → the term. Upserts one taxonomy record. `taxonomy` is `"category"` | `"tag"` | `"attribute"` | `"attribute-term"`, and `term` takes the fields for that one:
+- **`save-term`** — `{ taxonomy, term }` → the term. Upserts one taxonomy record. `taxonomy` is `"category"` | `"ribbon"` | `"attribute"` | `"attribute-term"`, and `term` takes the fields for that one:
 
   | taxonomy | entity | `term` fields |
   |---|---|---|
   | `category` | commerce.ProductCategory | `id?, name, slug?, description?, parent_id?, image?, menu_order?` |
-  | `tag` | commerce.ProductTag | `id?, name` |
+  | `ribbon` | commerce.ProductRibbon | `id?, name` |
   | `attribute` | commerce.ProductAttribute | `id?, name, code?, order?` |
   | `attribute-term` | commerce.ProductAttributeTerm | `id?, attribute_id` (**required**, must exist)`, name, order?` |
 
-  Only a category has a slug, derived from its name and made unique; its `parent_id` pointing at itself is coerced to `""` (`categoryWithDescendants` would loop). An attribute's **`code`** is derived from the name and made unique — it is the key a storefront filter URL should carry. Creating a **tag** is get-or-create: a name that already exists case-insensitively returns the existing record instead of splitting the tag in two. Renaming an **attribute value** rewrites `attributes[].options` and `default_attributes` on every product using it, and the matching `option` on their variations — products store a value by name, so the rename would otherwise orphan them.
+  Only a category has a slug, derived from its name and made unique; its `parent_id` pointing at itself is coerced to `""` (`categoryWithDescendants` would loop). An attribute's **`code`** is derived from the name and made unique — it is the key a storefront filter URL should carry. Creating a **ribbon** is get-or-create: a name that already exists case-insensitively returns the existing record instead of splitting the ribbon in two. Renaming an **attribute value** rewrites `attributes[].options` and `default_attributes` on every product using it, and the matching `option` on their variations — products store a value by name, so the rename would otherwise orphan them.
 
-  This is how a non-UI caller (notably the StoreAdmin agent) creates the records that `category_ids`/`tag_ids`/`attributes[].attribute_id` reference — assigning an id is useless if the record can't be created. **A product's `commerce.ProductAttribute` and its values must exist first**, so create those, then `save` the product with `attributes[]`/`variations[]`. (At install time, `commerce/seed-store` can do all of this in one call — it takes whole products by display name and get-or-creates the taxonomy internally; see below.)
-- **`delete-term`** — `{ taxonomy, id, detach? }` → `{ deleted, detached, terms_deleted }`. Deleting an **attribute** always deletes its terms (a term outliving its attribute is unreachable); `detach: true` additionally strips the attribute from every product's `attributes[]`. For a category or tag, products keep the id by default (the storefront skips ids that no longer resolve); `detach: true` strips it from every product first. **For an attribute *value* `detach` is a no-op** — deleting a value leaves its name in every product's `attributes[].options` and leaves the variations that use it in place, so remove the value from the products first (or expect variants the storefront can no longer resolve).
-- **`list-terms`** — `{ taxonomy, q?, attribute_id?, limit?, skip? }` → `{ rows, has_next }`. Categories sort by `menu_order`, attributes and attribute values by `order`, tags by `name`; `attribute_id` filters values to one attribute. Use it to reuse an existing record instead of creating a duplicate.
+  This is how a non-UI caller (notably the StoreAdmin agent) creates the records that `category_ids`/`ribbon_ids`/`attributes[].attribute_id` reference — assigning an id is useless if the record can't be created. **A product's `commerce.ProductAttribute` and its values must exist first**, so create those, then `save` the product with `attributes[]`/`variations[]`. (At install time, `commerce/seed-store` can do all of this in one call — it takes whole products by display name and get-or-creates the taxonomy internally; see below.)
+- **`delete-term`** — `{ taxonomy, id, detach? }` → `{ deleted, detached, terms_deleted }`. Deleting an **attribute** always deletes its terms (a term outliving its attribute is unreachable); `detach: true` additionally strips the attribute from every product's `attributes[]`. For a category or ribbon, products keep the id by default (the storefront skips ids that no longer resolve); `detach: true` strips it from every product first. **For an attribute *value* `detach` is a no-op** — deleting a value leaves its name in every product's `attributes[].options` and leaves the variations that use it in place, so remove the value from the products first (or expect variants the storefront can no longer resolve).
+- **`list-terms`** — `{ taxonomy, q?, attribute_id?, limit?, skip? }` → `{ rows, has_next }`. Categories sort by `menu_order`, attributes and attribute values by `order`, ribbons by `name`; `attribute_id` filters values to one attribute. Use it to reuse an existing record instead of creating a duplicate.
 
 ## commerce/admin-orders
 
@@ -109,14 +108,14 @@ Applied by the transition engine; each effect is flag-guarded so a re-entered st
 
 Actions: `create` · `delete`
 
-- **`create`** — `{ order_id, amount, reason?, line_items?, restock_items?, refund_payment? }`. `line_items` specs: `{ line_id, quantity, refund_total, refund_tax? }`. Validates `amount` ≤ remaining refundable (`400 amount_exceeds_refundable`, `400 invalid_amount`). Restocks per line when `restock_items`. Updates `order.total_refunded`; a full refund transitions the order to `refunded`, otherwise sends `partial_refund` + `order.updated`. With **`refund_payment: true`** the money goes back through the payment provider **first** — a failed provider refund writes nothing locally, so there is never a phantom refund — and the response carries `gateway_refund: { provider, id, status, amount }` with the record's `refunded_payment: true`. An order that wasn't paid online rejects it with `400 no_online_payment`. → `{ refund, order, gateway_refund? }`.
+- **`create`** — `{ order_id, amount, reason?, line_items?, restock_items?, refund_payment? }`. `line_items` specs: `{ line_id, quantity, refund_total, refund_tax? }`. Validates `amount` ≤ remaining refundable (`400 amount_exceeds_refundable`, `400 invalid_amount`). Restocks per line when `restock_items`. Updates `order.total_refunded`; a full refund transitions the order to `refunded`, otherwise sends `partial_refund` + `order.updated`. With **`refund_payment: true`** the money goes back through the payment provider **first** — a failed provider refund writes nothing locally, so there is never a phantom refund — and the response carries `gateway_refund: { refund_id }` with the record's `refunded_payment: true`. An order that wasn't paid by card rejects it with `400 no_card_payment`; while the store's `card-payment.ts` refund stub is unimplemented it answers `501 card_refund_not_implemented` (record the refund without `refund_payment` instead). → `{ refund, order, gateway_refund? }`.
 - **`delete`** — `{ refund_id }`. Reverses `total_refunded`; adds a note warning that restocked items are **not** auto-un-restocked.
 
 ## commerce/admin-coupons
 
 Actions: `save` · `delete` · `batch` · `search`
 
-- **`save`** — `{ coupon }`. Lowercases + enforces unique `code` (`duplicate_code`); percent amount ≤ 100. Fires `coupon.created`/`updated`.
+- **`save`** — `{ coupon }`. Lowercases + enforces unique `code` (`duplicate_code`); percent amount ≤ 100. `enabled: false` disables the coupon — it can't be applied and carts holding it drop it on the next re-price (validation code `disabled`). Fires `coupon.created`/`updated`.
 - **`delete`** — `{ id }` (fires `coupon.deleted`) · **`batch`** — `{ create?, update?, delete? }` · **`search`** — `{ q?, limit?, skip? }` → `{ rows, has_next }` (matches code/description).
 
 ## commerce/admin-customers
@@ -142,7 +141,7 @@ Actions: `test` · `redeliver` (webhook definitions themselves are direct `comme
 
 ## commerce/admin-reports
 
-All actions scan orders on demand (counted = `date_paid` set, or status `processing`/`completed`). See the commerce skill reference `skills/commerce/references/limits-and-performance.md` for scaling.
+All actions scan orders on demand (counted = `date_paid` set, or status `processing`/`completed`). See the commerce skill reference `.agents/skills/commerce/references/limits-and-performance.md` for scaling.
 
 | Action | Payload | Returns |
 |---|---|---|
@@ -155,17 +154,16 @@ All actions scan orders on demand (counted = `date_paid` set, or status `process
 | `customers-totals` | — | `{ total, guests, registered, paying }` |
 | `coupons-totals` | — | `{ total, by: { [discount_type]: count } }` |
 | `reviews-totals` | — | `{ total, by: { [status]: count } }` |
-| `categories-totals` / `tags-totals` | — | `{ total, terms: [{ id, name, count }] }` |
+| `categories-totals` / `ribbons-totals` | — | `{ total, terms: [{ id, name, count }] }` |
 | `attributes-totals` | — | `{ total, attributes: [{ id, name, terms }] }` |
 
 ## commerce/admin-tools
 
-Actions: `status` · `payment-connector-status` · `admin-email-recipients` · `recount-terms` · `recount-coupon-usage` · `recalculate-customer-stats-all` · `prune-webhook-deliveries` · `clear-abandoned-carts` · `regenerate-download-permissions`
+Actions: `status` · `admin-email-recipients` · `recount-terms` · `recount-coupon-usage` · `recalculate-customer-stats-all` · `prune-webhook-deliveries` · `clear-abandoned-carts` · `regenerate-download-permissions`
 
-- **`status`** — `{ template_version, seeded, settings_groups, counts: { "commerce.Product": n | "1000+", ... }, checks: { has_payment_gateways, has_default_zone } }` — `counts` is keyed by the **namespaced** entity name, and `checks` is an object, not an array. — mini system-status; also the seeded/health check for install verification.
-- **`payment-connector-status`** — no payload → `{ provider, provider_label, gateway_slug, connected, error?, connector }`. Whether an online payment provider is usable **right now**, answered by the payment utility for whichever provider is wired — so UI derives payment readiness instead of hardcoding a "not set up" notice, and shows "No payment provider connected" rather than a brand. Connectors are service-role only, hence the round trip; any failure reports `connected: false`. A provider connected **after** the function's last deploy reads as `connected: false` until the functions are redeployed — env vars are injected at deploy time ([`references/online-payments.md`](../references/online-payments.md) §1). (`connector` repeats `provider` for callers written against the older shape.)
+- **`status`** — `{ template_version, seeded, settings_groups, counts: { "commerce.Product": n | "1000+", ... }, checks: { has_payment_gateways, has_default_location } }` — `counts` is keyed by the **namespaced** entity name, and `checks` is an object, not an array. — mini system-status; also the seeded/health check for install verification.
 - **`admin-email-recipients`** — no payload → `{ recipients: string[], source: "settings" | "admin_users", admin_users: string[] }`. Where admin notifications go **right now**: `recipients` is the configured `emails.admin_recipients`, or the app's admin users when that is empty (the runtime fallback), with `source` saying which. `admin_users` is returned either way, so Settings → Emails can show the fallback as the field's placeholder even while explicit recipients are set. A client can't resolve it itself — listing users needs service role.
-- **`recount-terms`** — repairs category/tag/term `count`.
+- **`recount-terms`** — repairs category/ribbon/term `count`.
 - **`recount-coupon-usage`** — repairs `usage_count`/`used_by`.
 - **`recalculate-customer-stats-all`** — repairs all customers' `orders_count`/`total_spent`.
 - **`prune-webhook-deliveries`** — `{ keep_days }`.
@@ -174,19 +172,18 @@ Actions: `status` · `payment-connector-status` · `admin-email-recipients` · `
 
 ## commerce/payments
 
-Actions: `status` · `create-link` · `complete-return` · `verify` — the admin side of online payments (the same function serves customers, who authorize with `order_key` instead; see [`api-storefront.md`](./api-storefront.md)).
+Actions: `create-link` · `complete-return` · `verify` — the admin side of online payments (the same function serves customers, who authorize with `order_key` instead; see [`api-storefront.md`](./api-storefront.md)).
 
-- **`status`** (admin) — `{ provider, provider_label, gateway_slug, connected, error? }`.
-- **`create-link`** — `{ order_id }` → `{ provider, session_id, url, expires_at? }`: a provider-hosted payment page for an unpaid order, i.e. the **payment link** to send a customer. Accepts an order with **any** payment method (including none, as admin-created orders start) and switches it onto the online gateway, logging the change — refunds key off `payment_method`, so this keeps the order honest about how it was paid. `409 already_paid`, `400 online_payments_disabled`, `503 payment_provider_unavailable`.
+- **`create-link`** — `{ order_id }` → `{ url, reference }`: a provider-hosted payment page for an unpaid order, i.e. the **payment link** to send a customer. Accepts an order with **any** payment method (including none, as admin-created orders start) and switches it onto the card gateway, logging the change — refunds key off `payment_method`, so this keeps the order honest about how it was paid. `409 already_paid`, `400 card_payments_disabled`, `503 no_card_payment_provider`.
 - **`verify`** — `{ order_id }` → `{ paid, already_confirmed, status, order }`: re-asks the provider and moves the order to `processing` when the money is there. Idempotent.
-- **`complete-return`** — `{ order_id, order_key, payment?, return_url? }` → `{ state, paid, already_confirmed, status, order, payment_link }`: what the storefront's **mandatory** `/order-received` page calls — confirm, progress the order, and hand back a render-ready result plus a fresh payment link while unpaid.
+- **`complete-return`** — `{ order_id, order_key, payment?, return_url? }` → `{ state, paid, already_confirmed, status, order, payment_link, payment_instructions }`: what the storefront's **mandatory** `/order-received` page calls — confirm, progress the order, and hand back a render-ready result plus a fresh payment link while unpaid (card) or the gateway's payment instructions (manual).
 
-`commerce/payment-webhook` is the provider's signed callback (raw body, no `action` envelope) and needs `PAYMENT_WEBHOOK_SECRET`; it refuses every request until that is set. Provider specifics live in `base44/shared/commerce/payments.ts` — see [`../references/online-payments.md`](../references/online-payments.md).
+`commerce/payment-webhook` is the provider's server-to-server callback (raw body, no `action` envelope). Its `parseWebhook` is one of the two files to implement when wiring a provider; until then it answers `400 webhook_not_implemented`. See [`../references/online-payments.md`](../references/online-payments.md).
 
 ## commerce/seed-store
 
-Not action-routed. Body `{ store_name?, currency?, with_sample_data?, products?, coupons?, tax_rates? }`. **`store_name` is required** when the `emails` group doesn't exist yet (**400** `store_name_required` otherwise) — pass the app's name **as the platform shows it** — ask the user or read it from the dashboard. `base44/config.jsonc` → `name` is *not* authoritative: it can still say `New App` for an app the platform calls `Canvas`. A backend function can't read either, its environment being only `BASE44_APP_ID`. It lands in `emails.store_name` — one setting serving as both the store name in email subjects and the sender name on every transactional email; a nameless store renders subjects like `[]: New order #1002`, which is why seeding refuses one. Requires admin. Runs a **canary schema check** first — on any incompatibility returns **422** `{ success:false, code:"schema_incompatible", errors:[{ entity, error }] }` and writes nothing. Otherwise seeds defaults idempotently, then the catalog. On an already-seeded store a passed `store_name` fills a **blank** name and never overwrites one the merchant chose. **`currency`** is an ISO code (validated against the shared currencies table, **400** `invalid_payload` on an unknown one) that sets `general.currency` plus the currency's standard `num_decimals`; unlike `store_name` it **always wins** — there is no blank state to distinguish a merchant's USD from the seeded default, so passing it on a re-run updates the store currency.
+Not action-routed. Body `{ store_name?, currency?, weight_unit?, dimension_unit?, with_sample_data?, products?, coupons?, locations? }`. **`store_name` is required** when the `emails` group doesn't exist yet (**400** `store_name_required` otherwise) — pass the app's name **as the platform shows it** — ask the user or read it from the dashboard. `base44/config.jsonc` → `name` is *not* authoritative: it can still say `New App` for an app the platform calls `Canvas`. A backend function can't read either, its environment being only `BASE44_APP_ID`. It lands in `emails.store_name` — one setting serving as both the store name in email subjects and the sender name on every transactional email; a nameless store renders subjects like `[]: New order #1002`, which is why seeding refuses one. Requires admin. Runs a **canary schema check** first — on any incompatibility returns **422** `{ success:false, code:"schema_incompatible", errors:[{ entity, error }] }` and writes nothing. Otherwise seeds defaults idempotently, then the catalog. On an already-seeded store a passed `store_name` fills a **blank** name and never overwrites one the merchant chose. **`currency`** (ISO code, validated against the shared currencies table) and **`weight_unit`/`dimension_unit`** set the `general` group; unknown values fail as **400** `invalid_payload`. Unlike `store_name` they **always win** — there is no blank state to distinguish a merchant's choice from the seeded default, so passing one on a re-run updates the store. Prices are formatted with `Intl.NumberFormat` — the currency is a value, there are no format settings.
 
-**`products`** is the one-call catalog bootstrap — the worked example and full semantics are in [`../post-installation.md` §2.1](../post-installation.md#21-the-products-payload). Each entry references categories/tags/attributes by **display name** (taxonomy is get-or-created: slugs/codes derived, existing records matched case-insensitively and reused, with the stored casing canonicalized into the product). `attributes: [{ name, options }]` (or `{ <name>: [options] }`) declares the variant axes; `variations: [{ options: { <name>: <option> }, ...overrides }]` lists the stocked combinations — omit it to auto-generate **all** combinations, each inheriting the product-level price/sale fields. A variation with its own `stock_quantity` gets `manage_stock: "yes"`; without one it draws on the parent's pooled stock (`"parent"`). Variation SKUs are synthesized from the parent SKU when absent. Parent `price`/`regular_price`/`on_sale` are rolled up from the cheapest publishable variant, `stock_status` derived, category/tag counts maintained — same helpers as `admin-products` `save`, but **no `product.created` webhooks are dispatched** (bootstrap precedes webhook subscribers; use `admin-products` for webhook-visible creates). Payload problems fail before any write as **400** `invalid_payload` with `errors: [{ path, error }]`; an explicit variation SKU already in use is **409** `duplicate_sku`; a mid-write failure rolls back everything the call created (**500** `catalog_seed_failed`) without touching reused taxonomy. **Re-runs converge**: a product whose `sku` (or, without one, derived slug) already exists is skipped and reported, so retries never duplicate. Limits: ≤100 products, ≤50 variations per product, ≤500 variations per call, ≤50 coupons/tax rates. `coupons`/`tax_rates` are thin passthroughs (coupon `code` lowercased; both skip-if-exists). `with_sample_data: true` seeds the template's demo catalog instead (only when the store has zero products) and cannot be combined with the catalog keys.
+**`products`** is the one-call catalog bootstrap — the worked example and full semantics are in [`../post-installation.md` §2.1](../post-installation.md#21-the-products-payload). Each entry references categories/ribbons/attributes by **display name** (taxonomy is get-or-created: slugs/codes derived, existing records matched case-insensitively and reused, with the stored casing canonicalized into the product). `attributes: [{ name, options }]` (or `{ <name>: [options] }`) declares the variant axes; `variations: [{ options: { <name>: <option> }, ...overrides }]` lists the stocked combinations — omit it to auto-generate **all** combinations, each inheriting the product-level price/sale fields. A variation with its own `stock_quantity` gets `manage_stock: "yes"`; without one it draws on the parent's pooled stock (`"parent"`). Variation SKUs are synthesized from the parent SKU when absent. Parent `price`/`regular_price`/`on_sale` are rolled up from the cheapest publishable variant, `stock_status` derived, category/ribbon counts maintained — same helpers as `admin-products` `save`, but **no `product.created` webhooks are dispatched** (bootstrap precedes webhook subscribers; use `admin-products` for webhook-visible creates). Payload problems fail before any write as **400** `invalid_payload` with `errors: [{ path, error }]`; an explicit variation SKU already in use is **409** `duplicate_sku`; a mid-write failure rolls back everything the call created (**500** `catalog_seed_failed`) without touching reused taxonomy. **Re-runs converge**: a product whose `sku` (or, without one, derived slug) already exists is skipped and reported, so retries never duplicate. Limits: ≤100 products, ≤50 variations per product, ≤500 variations per call, ≤50 coupons/locations. `coupons` is a thin passthrough (code lowercased, skip-if-exists); **`locations`** creates Shipping & Tax Locations (`{ name, countries?: ["IL"], shipping_rates: [{ name, cost, free_over? }], tax_groups?: [{ name, rates: [{ name, rate }] }], shipping_tax?: { type: "percent"|"fixed", value } }` — the default `Products` tax group is added when missing; skip-if-exists by name). Passing any `locations` suppresses the seeded "Rest of the world" fallback — yours become the store's only locations; without them the free-shipping fallback is seeded. `with_sample_data: true` seeds the template's demo catalog instead (only when the store has zero products) and cannot be combined with the catalog keys.
 
-→ `{ seeded: { settings_groups, gateways, tax_classes, zones, zone_methods }, sample_data: {...} | false, catalog: { categories|tags|attributes|terms: { created, reused }, products_created, products_skipped, variations_created, coupons, tax_rates, products: [{ name, id, slug, sku, variation_count } | { name, skipped: true, reason: "sku_exists"|"slug_exists", existing_id }] } | null, store_name: { value, action: "created" | "filled" | "unchanged" | "kept_existing" }, currency: { value, action: "created" | "updated" | "unchanged" } | null }`.
+→ `{ seeded: { settings_groups, gateways, locations }, sample_data: {...} | false, catalog: { categories|ribbons|attributes|terms: { created, reused }, products_created, products_skipped, variations_created, coupons, locations, products: [{ name, id, slug, sku, variation_count } | { name, skipped: true, reason: "sku_exists"|"slug_exists", existing_id }] } | null, store_name: { value, action: "created" | "filled" | "unchanged" | "kept_existing" }, currency: { value, action: "created" | "updated" | "unchanged" } | null }`.

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

@@ -12,7 +12,7 @@ Read this list before writing any of it. Each item is a hard requirement enforce
 | 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 |
+| 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.
 
@@ -22,21 +22,21 @@ The backend is considerably richer than a minimal "grid → cart → pay" shop.
 
 | 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 name / price / **newest** (the default) / **popularity** / **rating**; paging | [`list-products`](#list-products) |
-| **Rich product pages** | galleries, per-variant price/stock/image, categories, tags, **upsells**, **cross-sells** | [`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) |
+| **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) |
+| **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) | [`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) |
+| **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 + formatting, review toggles, catalog/cart price display — read it and honour it instead of hardcoding | [`get-store-info`](#get-store-info) |
+| **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 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.
+Two things that are **not** in the backend and are yours to build: the visitor UI itself, and the payment provider integration — two files to implement (see [`references/online-payments.md`](../references/online-payments.md)). Payment methods and the currency are admin-owned data — always render them from `get-store-info` rather than a hardcoded list, and format prices with `Intl.NumberFormat(undefined, { style: "currency", currency })`.
 
 ## Conventions
 
@@ -62,31 +62,32 @@ Bootstrap data for a storefront. No payload.
 **Response:**
 ```json
 {
-  "settings": { "store_name": "Acme", "currency": "USD", "currency_position": "left",
-                "thousand_sep": ",", "decimal_sep": ".", "num_decimals": 2,
+  "settings": { "store_name": "Acme", "currency": "USD",
                 "weight_unit": "kg", "dimension_unit": "cm",
                 "prices_include_tax": false, "display_prices_shop": "excl", "display_prices_cart": "excl",
-                "enable_reviews": true, "review_rating_required": true, "hide_out_of_stock": false },
+                "hide_out_of_stock": false },
   "payment_gateways": [ { "slug": "offline", "title": "Offline payment", "description": "...", "online": false },
-                        { "slug": "stripe", "title": "Credit card", "description": "...", "online": true } ],
+                        { "slug": "card", "title": "Credit card", "description": "...", "online": true } ],
   "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.
 
+`payment_gateways` is **every gateway the admin has enabled** (sorted by their `order`) — the Payments settings switch is the single source of truth. `online: true` marks the card option (`place-order` answers with a payment page to redirect to; `503 no_card_payment_provider` while the store has no provider implemented); everything else settles manually.
+
 ### `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` (`-created_date`|`name`|`price`|`-price`|`popularity`|`rating`, default `-created_date`), `page` (default 1), `per_page` (default 12, max 100).
+**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).
 
-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.
+Only `status: "publish"` products are returned — the admin's single **Visible** toggle. `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 }]`), so cards can show tags 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 can show their ribbons 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.
+> **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.** `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.
+**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.
 
 ### `get-product`
 **Payload:** `{ id }` **or** `{ slug }`; optional `reviews_page` (1), `reviews_per_page` (10, max 50).
@@ -97,7 +98,7 @@ Each row is the product record (minus paywalled fields) **plus a resolved `tags`
   "product": { Product },
   "variations": [ ProductVariation... ],          // publishable only; [] when the product has no attributes
   "categories": [ ProductCategory... ],
-  "tags": [ ProductTag... ],
+  "ribbons": [ ProductRibbon... ],
   "reviews": { "items": [ { "id", "reviewer", "review", "rating", "verified", "created_date" } ],
                "page": 1, "per_page": 10, "has_next": false,
                "average_rating": 4.5, "rating_count": 12 },
@@ -124,27 +125,27 @@ Each row is the product record (minus paywalled fields) **plus a resolved `tags`
 ### `list-categories`
 No payload. Returns a nested tree: `{ "categories": [ { ...category, "children": [...] } ] }` sorted by `menu_order` then name.
 
-### `list-tags`
+### `list-ribbons`
 **Payload** (optional): `{ with_products_only?: boolean }` (default `true`).
 
-Returns `{ "tags": [ { id, name, 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).
+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, 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.
+`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.
 
-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.
+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.
 
 ### `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.
 
-### `submit-review` — **auth**
+### `submit-review`
 **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`.
+**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.
 
-Requires `products.enable_reviews` — reviews are a store-wide switch, not per product. 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`.
+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.
 
 **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`.
+**Errors:** `404 not_found`, `400 email_required|review_incomplete|invalid_rating`.
 
 ---
 
@@ -169,9 +170,9 @@ Token-scoped cart (guest + member). Every action **except `create`** takes `cart
   "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
+  "chosen_shipping_method": "<shippingRateId>",
+  "available_shipping_methods": [ { "id": "<shippingRateId>", "title": "Standard delivery", "cost": 5 } ],
+  "shipping_status": "chosen",           // not_needed | chosen | auto_selected | choice_required | missing_address | 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 } ] },
@@ -186,15 +187,17 @@ 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? }` | 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 — 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`. |
 | `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 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`). |
+| `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`). |
+
+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.
 
-Common: `400 cart_token_required`, `404 cart_not_found`, `404 cart_expired`.
+> **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.
 
 ### Shipping is not optional — read this before building checkout
 <a id="shipping-is-not-optional--read-this-before-building-checkout"></a>
@@ -209,33 +212,36 @@ rather than assuming:
 | `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 |
+| `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) |
 
 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 re-read it after every cart mutation, not just after setting the address.
+- **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.
 
 ### 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.
 
-**Zones are admin-only data.** `commerce.ShippingZone` and `commerce.ShippingZoneMethod` are `read: {role: "admin"}` like every entity, so a visitor cannot list them — do not try. Two honest sources:
+**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:
 
 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):
+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):
 
 ```js
 import { freeShippingRules, freeShippingThreshold, freeShippingProgress } from "@/commerce/utils";
 
-// zones/methods come from your own storefront action — NOT from a client entity read
-const threshold = freeShippingThreshold(freeShippingRules(zones, methods));
+// 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.
-const progress = freeShippingProgress(threshold, cart.totals.subtotal);  // { threshold, qualifies, remaining }
+const progress = freeShippingProgress(threshold, cart.totals.subtotal - cart.totals.discount_total);
 ```
 
-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.
+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.
 
 ---
 
@@ -247,21 +253,22 @@ Converts a cart into an order. **Payload:**
 { "cart_token": "uuid", "payment_method": "offline",
   "billing":  { "first_name", "last_name", "address_1", "address_2?", "city", "state?", "postcode?", "country", "email", "phone?" },
   "shipping": { ...address without email },
-  "chosen_shipping_method?": "<zoneMethodId>",
+  "chosen_shipping_method?": "<shippingRateId>",
   "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
+  // 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 });
-  } 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
+  // (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;
@@ -271,9 +278,9 @@ Converts a cart into an order. **Payload:**
 
   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 `offline` gateway settles outside the store and returns `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).
+> **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).
 
-**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: **offline → on-hold** (with `payment_instructions`), **stripe → stays pending** until the hosted page is paid, **custom → pending_external**.
+**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`).
 
 > **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.
 
@@ -284,15 +291,14 @@ Converts a cart into an order. **Payload:**
   "status": "on-hold", "currency": "USD",
   "payment_method": "offline", "payment_method_title": "Offline payment",
   "payment_instructions": { "type": "offline", "description": "...", "account_details": [...] },
-  "payment": null,                       // offline. For the online gateway:
-                                         //   { "status": "requires_payment", "provider", "checkout_url", "session_id" }
-                                         // For a custom gateway: { "status": "pending_external" }
+  "payment": null,                       // manual gateways. For the card gateway:
+                                         //   { "status": "requires_payment", "checkout_url", "reference" }
   "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`.
+**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).
 
 ### `commerce/payments` — online payment for an order
 
@@ -300,23 +306,23 @@ Separate function, same guest-bearer rule (`order_id` + `order_key`; an admin ma
 
 | 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 |
+| `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 |
 
 > **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.
+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. Wiring a payment provider means implementing two files; see [`../references/online-payments.md`](../references/online-payments.md).
 
 ### `confirm-payment`
-Post-payment hook for an order on the online gateway. **Payload:** `{ order_id, order_key, session_id? }`.
+Post-payment hook for an order on the card gateway. **Payload:** `{ order_id, order_key }`.
 
-**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.
+**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_an_online_payment`, `404 order_not_found`, `409 invalid_status|payment_not_confirmed|session_order_mismatch`.
+**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`.
@@ -364,7 +370,9 @@ 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. A single option is already applied for you;
+// 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.
 cart = await inv("commerce/storefront-cart", { action: "set-shipping-address",
   cart_token: token, address: { country: "US", state: "CA", postcode: "90210", city: "Los Angeles" } });
@@ -372,8 +380,6 @@ 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 (offline → on-hold; no money has arrived yet)