@base44/app-plugin-commerce 0.1.5 → 0.1.7

package/README.md

@@ -2,25 +2,25 @@
 
 A **Commerce backend + admin UI** for [Base44](https://base44.com) apps, delivered as a copyable file set. Drop `base44/` and `src/commerce/` into an existing Base44 app to add a full store: catalog, orders, coupons, customers, reviews, tax, shipping, webhooks, reports and transactional emails — plus a public storefront API for building your own shopfront.
 
-It provides a full-featured **commerce data model and behavior** (variant-driven products, order lifecycle, coupon rules, tax priority/compound math, shipping zones) using Base44-idiomatic primitives (entity JSON schemas, Deno functions, the Base44 SDK).
+It provides a full-featured **commerce data model and behavior** (variant-driven products, order lifecycle, coupon rules, per-location shipping and tax) using Base44-idiomatic primitives (entity JSON schemas, Deno functions, the Base44 SDK).
 
 ## What's included
 
-- **24 entities** — Products (a product sells variants when it carries attributes; no type field), variations, categories, tags, attributes + values, reviews, orders (embedded line/shipping/tax/fee/coupon lines), order notes, refunds, coupons, customers, tax classes/rates, shipping zones/methods, payment gateways, store settings, webhooks + deliveries, carts, download permissions, email log.
+- **20 entities** — Products (a product sells variants when it carries attributes; no type field), variations, categories, ribbons, attributes + values, reviews, orders (embedded line/shipping/tax/fee/coupon lines), order notes, refunds, coupons, customers, Shipping & Tax Locations (shipping rates + tax groups per location), payment gateways, store settings, webhooks + deliveries, carts, download permissions, email log.
 - **16 backend functions** — 9 admin (`commerce/admin-products`, `commerce/admin-orders`, `commerce/admin-refunds`, `commerce/admin-coupons`, `commerce/admin-customers`, `commerce/admin-reviews`, `commerce/admin-webhooks`, `commerce/admin-reports`, `commerce/admin-tools`), 4 storefront (`commerce/storefront-catalog`, `commerce/storefront-cart`, `commerce/storefront-checkout`, `commerce/storefront-account`), 2 payment (`commerce/payments`, `commerce/payment-webhook`), and an idempotent `commerce/seed-store` — one call seeds the business defaults **and the whole catalog** (products with attributes in, variants/categories/taxonomy created internally).
-- **Online card payments, implemented** — hosted payment page, payment links for unpaid orders, two idempotent confirmation paths (customer return + signed webhook) and refunds through the provider. Wired to **Stripe** out of the box behind a provider-neutral payment utility, so the store takes cards as soon as the connector is connected — no charge flow to write — and moving to another provider means implementing one adapter. See [`skills/commerce/references/online-payments.md`](./skills/commerce/references/online-payments.md).
-- **Shared commerce engine** (`base44/shared/commerce/`) — totals, tax, shipping, coupons, stock, order lifecycle, webhook dispatch (HMAC-signed), emails, payments utility + Stripe adapter, plus static country/currency/continent data.
+- **Online card payments, order side premade** — checkout routing, payment links for unpaid orders, two idempotent confirmation paths (customer return + webhook) and refund records are all built. Wiring a provider (Stripe, PayPal, a local PSP…) means implementing **exactly two files** — `base44/shared/commerce/card-payment.ts` and the payment webhook — and nothing else. Every other payment option is manual (on-hold + instructions) and needs no code; the admin can add more in Settings → Payments. See [`skills/commerce/references/online-payments.md`](./skills/commerce/references/online-payments.md).
+- **Shared commerce engine** (`base44/shared/commerce/`) — totals, tax, shipping, coupons, stock, order lifecycle, webhook dispatch (HMAC-signed), emails, card-payment plumbing, plus static country/currency/continent data.
 - **Admin UI** (`src/commerce/admin/`) — a React/Tailwind/shadcn admin with a familiar store back-office information architecture: dashboard, orders, products, coupons, customers, reports, and full settings including webhooks. Admin-role gated.
 - **Storefront helpers** (`src/commerce/utils/`) — framework-free, dependency-free functions for the shopfront you build: `variants.js` maps an attribute selection (Size, Color) onto a `ProductVariation` and back, plus per-option availability and variant price ranges; `shipping-promos.js` reads the store's real free-shipping configuration so "Free shipping over €150" copy states a configured rule rather than an invented number. See [`skills/commerce/references/storefront-product-page.md`](./skills/commerce/references/storefront-product-page.md).
 - **StoreAdmin agent + bot** — an AI copilot (`base44/agents/commerce/StoreAdmin.jsonc`, registered as `commerce/StoreAdmin`) with the `commerce/*` functions attached directly as tools (calls run as the chatting user → `requireAdmin()` still applies), variant-aware order editing, plus a chat panel in the admin sidebar with GFM markdown-table rendering.
-- **Docs** — this README plus the commerce skill folder [`skills/commerce/`](./skills/commerce/), which holds [`SKILL.md`](./skills/commerce/SKILL.md) (the short map agents start from), [`installation-guidelines.md`](./skills/commerce/installation-guidelines.md), [`post-installation.md`](./skills/commerce/post-installation.md), per-topic guides in [`references/`](./skills/commerce/references/) and the API references in [`docs/`](./skills/commerce/docs/) — the whole folder is installed into the app so agents pick it up natively.
+- **Docs** — this README plus the commerce skill folder [`skills/commerce/`](./skills/commerce/), which holds [`SKILL.md`](./skills/commerce/SKILL.md) (the short map agents start from), [`installation-guidelines.md`](./skills/commerce/installation-guidelines.md), [`post-installation.md`](./skills/commerce/post-installation.md), per-topic guides in [`references/`](./skills/commerce/references/) and the API references in [`docs/`](./skills/commerce/docs/) — the whole folder is installed into the app at `.agents/skills/commerce/` so agents pick it up natively.
 
 ## Repo map
 
 ```
 base44-commerce-template/
 ├── base44/
-│   ├── entities/     24 .jsonc entity schemas (commerce.*.jsonc)
+│   ├── entities/     20 .jsonc entity schemas (commerce.*.jsonc)
 │   ├── functions/
 │   │   └── commerce/ 16 Deno functions (entry.ts each), invoked as "commerce/<name>"
 │   ├── agents/
@@ -34,13 +34,13 @@ base44-commerce-template/
 ├── scripts/
 │   └── install.js         static installer (run from <app>/examples/commerce/scripts/)
 ├── skills/
-│   └── commerce/          commerce skill — copied into the app's skills/ so agents
-│       │                  know the store natively
+│   └── commerce/          commerce skill — copied into the app's .agents/skills/
+│       │                  so agents know the store natively
 │       ├── SKILL.md       the map: short overview + links to everything below
 │       ├── installation-guidelines.md   installing into an app (scripted or manual)
 │       ├── post-installation.md         embedding the admin pages, seeding, storefront quick start
 │       ├── references/    per-topic guides (product rendering, product page & variants,
-│       │                  Stripe, scheduled work, emails, webhooks, media & downloads,
+│       │                  online payments, scheduled work, emails, webhooks, media & downloads,
 │       │                  limits, security)
 │       └── docs/
 │           ├── api-admin.md       admin function/entity reference
@@ -86,7 +86,7 @@ From your existing Base44 app:
    <Route path="/store-admin/*" element={<AdminApp />} />
    ```
 6. **Grant yourself the `admin` role** (Base44 dashboard → users, or `users.inviteUser(email, "admin")`). The admin UI refuses non-admins.
-7. **Seed the store.** Either open `/store-admin` and click **Initialize store defaults** on the first-run setup screen, or call `commerce/seed-store` directly — it creates the settings groups, gateways, tax classes and a fallback shipping zone, plus the catalog: pass `products` (whole products with attributes — variants, categories and taxonomy are created internally) or `with_sample_data: true` for the generic demo. Either way pass `store_name` (the app's name) — it is required on a first seed and becomes both the email subject prefix and the sender name. Once the `general` settings group exists the store counts as ready and the first-run screen stops appearing. Payload reference and a worked example: [`skills/commerce/post-installation.md`](./skills/commerce/post-installation.md) §2.
+7. **Seed the store.** Either open `/store-admin` and click **Initialize store defaults** on the first-run setup screen, or call `commerce/seed-store` directly — it creates the settings groups, gateways and — unless you pass your own `locations` — a fallback Shipping & Tax Location, plus the catalog: pass `products` (whole products with attributes — variants, categories, ribbons and taxonomy are created internally) or `with_sample_data: true` for the generic demo. Either way pass `store_name` (the app's name) — it is required on a first seed and becomes both the email subject prefix and the sender name. Once the `general` settings group exists the store counts as ready and the first-run screen stops appearing. Payload reference and a worked example: [`skills/commerce/post-installation.md`](./skills/commerce/post-installation.md) §2.
 
 ## Quick start (Base44 MCP / hosted apps)
 
@@ -99,7 +99,7 @@ If you build on Base44's hosted platform, use the Base44 agent/MCP to write the
 ## What's NOT included
 
 - **No visitor/storefront UI.** The storefront **API** is complete (`commerce/storefront-*` functions); building the shopfront is up to you — see [`skills/commerce/docs/api-storefront.md`](./skills/commerce/docs/api-storefront.md). What *does* ship for the storefront is **helper logic**: [`src/commerce/utils/`](./src/commerce/utils/) — framework-free variant-selection functions (map a Size/Color selection to a `ProductVariation` and back, per-option availability, variant price ranges) — plus [`skills/commerce/references/product-render.md`](./skills/commerce/references/product-render.md) (what to render in a grid vs. a product page, and which fields each call returns) and [`skills/commerce/references/storefront-product-page.md`](./skills/commerce/references/storefront-product-page.md), the variant rules that go with the helpers.
-- **No payment credentials** — the card integration itself *is* included (see above), but a store can only charge once someone connects a payment provider's connector for the app. Until then the card option stays hidden from customers and the offline gateway (bank transfer, cash on delivery) carries checkout.
+- **No payment provider** — the order side of card payments is premade (see above), but charging a card needs a provider: implement the two payment files to wire one. Until then the card option answers "card payments are not available yet" at checkout (or switch it off in Settings → Payments), and the manual gateways (bank transfer, cash on delivery, anything the admin adds) carry checkout.
 - **No scheduled workflows shipped.** Base44 *does* have a scheduler, but this template ships no workflow files — time-based jobs (stock-hold release, cart expiry, webhook-log pruning) run **opportunistically** where possible, and for the rest you (or the Base44 agent) create scheduled workflows that call `commerce/admin-tools`/`commerce/admin-orders` actions — see *Scheduled work* in [`skills/commerce/SKILL.md`](./skills/commerce/SKILL.md).
 
 ## Next steps

package/base44/agents/commerce/StoreAdmin.jsonc

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

package/base44/entities/commerce.Cart.jsonc

@@ -50,7 +50,7 @@
     },
     "chosen_shipping_method": {
       "type": "string",
-      "description": "ShippingZoneMethod id"
+      "description": "The chosen shipping rate id (ShippingTaxLocation.shipping_rates[].id)"
     },
     "status": {
       "type": "string",

package/base44/entities/commerce.Coupon.jsonc

@@ -8,6 +8,11 @@
       "minLength": 1,
       "description": "Coupon code, stored lowercase, unique (enforced in commerce/admin-coupons)"
     },
+    "enabled": {
+      "type": "boolean",
+      "default": true,
+      "description": "A disabled coupon cannot be applied and stops validating on carts that hold it"
+    },
     "discount_type": {
       "type": "string",
       "enum": ["percent", "fixed_cart", "fixed_product"],

package/base44/entities/commerce.Order.jsonc

@@ -117,7 +117,7 @@
           "sku": { "type": "string" },
           "quantity": { "type": "integer" },
           "price": { "type": "number", "description": "Per-unit price after discounts, ex tax" },
-          "tax_class": { "type": "string" },
+          "tax_group": { "type": "string" },
           "subtotal": { "type": "number", "description": "Line total before discounts, ex tax" },
           "subtotal_tax": { "type": "number" },
           "total": { "type": "number", "description": "Line total after discounts, ex tax" },
@@ -127,7 +127,7 @@
             "items": {
               "type": "object",
               "properties": {
-                "rate_id": { "type": "string" },
+                "label": { "type": "string" },
                 "total": { "type": "number" },
                 "subtotal": { "type": "number" }
               }
@@ -164,8 +164,8 @@
         "type": "object",
         "properties": {
           "line_id": { "type": "string" },
-          "method_id": { "type": "string", "description": "flat_rate|free_shipping|local_pickup" },
-          "instance_id": { "type": "string", "description": "ShippingZoneMethod id" },
+          "method_id": { "type": "string", "description": "Always \"rate\" — kept for shape stability" },
+          "instance_id": { "type": "string", "description": "The chosen shipping rate id (ShippingTaxLocation.shipping_rates[].id)" },
           "method_title": { "type": "string" },
           "total": { "type": "number" },
           "total_tax": { "type": "number" },
@@ -174,7 +174,7 @@
             "items": {
               "type": "object",
               "properties": {
-                "rate_id": { "type": "string" },
+                "label": { "type": "string" },
                 "total": { "type": "number" }
               }
             }
@@ -192,7 +192,6 @@
           "rate_code": { "type": "string" },
           "label": { "type": "string" },
           "rate_percent": { "type": "number" },
-          "compound": { "type": "boolean" },
           "tax_total": { "type": "number" },
           "shipping_tax_total": { "type": "number" }
         }
@@ -206,7 +205,7 @@
         "properties": {
           "line_id": { "type": "string" },
           "name": { "type": "string" },
-          "tax_class": { "type": "string" },
+          "tax_group": { "type": "string" },
           "tax_status": { "type": "string", "enum": ["taxable", "none"] },
           "total": { "type": "number" },
           "total_tax": { "type": "number" }

package/base44/entities/commerce.OrderRefund.jsonc

@@ -21,7 +21,7 @@
     "refunded_payment": {
       "type": "boolean",
       "default": false,
-      "description": "True when a real gateway refund was made (Stripe wiring placeholder — see skills/commerce/references/online-payments.md)"
+      "description": "True when a real gateway refund was made (Stripe wiring placeholder — see .agents/skills/commerce/references/online-payments.md)"
     },
     "restock_items": {
       "type": "boolean",

package/base44/entities/commerce.PaymentGateway.jsonc

@@ -35,7 +35,7 @@
     },
     "settings": {
       "type": "object",
-      "description": "Per-gateway settings. offline: {account_details: [{account_name, account_number, bank_name, sort_code, iban, bic}]}; stripe: {connector: \"stripe\"} — see skills/commerce/references/online-payments.md"
+      "description": "Per-gateway settings. offline: {account_details: [{account_name, account_number, bank_name, sort_code, iban, bic}]}; stripe: {connector: \"stripe\"} — see .agents/skills/commerce/references/online-payments.md"
     }
   },
   "required": ["slug"],

package/base44/entities/commerce.Product.jsonc

@@ -23,12 +23,6 @@
       "default": false,
       "description": "Featured product flag"
     },
-    "catalog_visibility": {
-      "type": "string",
-      "enum": ["visible", "catalog", "search", "hidden"],
-      "default": "visible",
-      "description": "Where the product is visible in the catalog"
-    },
     "description": {
       "type": "string",
       "format": "richtext",
@@ -104,14 +98,14 @@
     },
     "tax_status": {
       "type": "string",
-      "enum": ["taxable", "shipping", "none"],
+      "enum": ["taxable", "none"],
       "default": "taxable",
       "description": "Tax status"
     },
-    "tax_class": {
+    "tax_group": {
       "type": "string",
-      "default": "standard",
-      "description": "TaxClass slug"
+      "default": "Products",
+      "description": "Tax group name from the matched Shipping & Tax Location; 'Products' is the default group"
     },
     "manage_stock": {
       "type": "boolean",
@@ -156,10 +150,6 @@
         "height": { "type": "number" }
       }
     },
-    "shipping_class_id": {
-      "type": "string",
-      "description": "ShippingClass id"
-    },
     "average_rating": {
       "type": "number",
       "default": 0,
@@ -185,10 +175,10 @@
       "items": { "type": "string" },
       "description": "ProductCategory ids"
     },
-    "tag_ids": {
+    "ribbon_ids": {
       "type": "array",
       "items": { "type": "string" },
-      "description": "ProductTag ids"
+      "description": "ProductRibbon ids"
     },
     "images": {
       "type": "array",

package/base44/entities/{commerce.ProductTag.jsonc → commerce.ProductRibbon.jsonc}

@@ -1,7 +1,7 @@
 {
-  "name": "commerce.ProductTag",
+  "name": "commerce.ProductRibbon",
   "type": "object",
-  "description": "Product tag. Created and picked from the product form; storefronts filter by id (list-products tag_id).",
+  "description": "Product ribbon — a label like 'Best Seller' shown on product cards. Created and picked from the product form; storefronts filter by id (list-products ribbon_id).",
   "properties": {
     "name": {
       "type": "string",

package/base44/entities/commerce.ProductVariation.jsonc

@@ -85,14 +85,10 @@
     },
     "tax_status": {
       "type": "string",
-      "enum": ["taxable", "shipping", "none", "parent"],
+      "enum": ["taxable", "none", "parent"],
       "default": "parent",
       "description": "Tax status; parent = inherit from parent product"
     },
-    "tax_class": {
-      "type": "string",
-      "description": "TaxClass slug; empty = inherit from parent"
-    },
     "manage_stock": {
       "type": "string",
       "enum": ["yes", "no", "parent"],
@@ -126,10 +122,6 @@
         "height": { "type": "number" }
       }
     },
-    "shipping_class_id": {
-      "type": "string",
-      "description": "ShippingClass id; empty = inherit from parent"
-    },
     "image": {
       "type": "object",
       "description": "Variation image",

package/base44/entities/commerce.ShippingTaxLocation.jsonc

@@ -0,0 +1,85 @@
+{
+  "name": "commerce.ShippingTaxLocation",
+  "type": "object",
+  "description": "A sales location: the regions it covers plus everything charged there — shipping rates, tax groups (default group 'Products'; products pick a group by name via tax_group) and an optional shipping tax (% or fixed). Matched by 'order' ascending; a location with no regions is the 'Rest of the world' fallback. Replaces the former zone/method/class model.",
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 1
+    },
+    "order": {
+      "type": "integer",
+      "default": 0,
+      "description": "Match priority, ascending"
+    },
+    "regions": {
+      "type": "array",
+      "description": "Regions this location covers; empty = matches everything (fallback location)",
+      "items": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["country", "state", "continent"],
+            "description": "Region type"
+          },
+          "code": {
+            "type": "string",
+            "description": "Country code (US), state code (US:CA), or continent code (EU)"
+          }
+        }
+      }
+    },
+    "shipping_rates": {
+      "type": "array",
+      "description": "Shipping options offered at this location; each is a checkout choice",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "string", "description": "Stable id — carts/orders reference the chosen rate by it" },
+          "name": { "type": "string", "description": "Customer-facing label, e.g. Standard delivery" },
+          "cost": { "type": "number", "default": 0 },
+          "free_over": {
+            "type": ["number", "null"],
+            "description": "Items subtotal (after discounts) at which this rate becomes free; null = never"
+          }
+        }
+      }
+    },
+    "tax_groups": {
+      "type": "array",
+      "description": "Named tax groups; 'Products' is the default group every product uses unless its tax_group says otherwise. Group tax = sum of its rates.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": { "type": "string", "description": "Group name, e.g. Products" },
+          "rates": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "name": { "type": "string", "description": "Rate label shown at checkout, e.g. VAT" },
+                "rate": { "type": "number", "description": "Percentage, e.g. 18 for 18%" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "shipping_tax": {
+      "type": ["object", "null"],
+      "description": "Tax applied to the shipping cost at this location; null = shipping is not taxed",
+      "properties": {
+        "type": { "type": "string", "enum": ["percent", "fixed"], "description": "percent of the shipping cost, or a fixed amount" },
+        "value": { "type": "number" }
+      }
+    }
+  },
+  "required": ["name"],
+  "rls": {
+    "read": { "user_condition": { "role": "admin" } },
+    "create": { "user_condition": { "role": "admin" } },
+    "update": { "user_condition": { "role": "admin" } },
+    "delete": { "user_condition": { "role": "admin" } }
+  }
+}

package/base44/entities/commerce.Webhook.jsonc

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

package/base44/functions/commerce/admin-orders/helpers.ts

@@ -12,20 +12,16 @@ import { uuid } from "../../../shared/commerce/sequence.ts";
 
 export interface PricingContext {
   settings: Record<string, any>;
-  taxRates: any[];
-  zones: any[];
-  zoneMethods: any[];
+  locations: any[];
 }
 
 /** Everything calculateTotals needs from the catalog, in one fetch. */
 export async function loadPricingContext(sr: any): Promise<PricingContext> {
-  const [settings, taxRates, zones, zoneMethods] = await Promise.all([
+  const [settings, locations] = await Promise.all([
     getSettings(sr),
-    scanAll(sr.entities["commerce.TaxRate"], null, "menu_order"),
-    scanAll(sr.entities["commerce.ShippingZone"], null, "order"),
-    scanAll(sr.entities["commerce.ShippingZoneMethod"], null, "order"),
+    scanAll(sr.entities["commerce.ShippingTaxLocation"], null, "order"),
   ]);
-  return { settings, taxRates, zones, zoneMethods };
+  return { settings, locations };
 }
 
 export interface ItemSpec {
@@ -112,7 +108,7 @@ export interface RepriceOpts {
   /** Coupon codes; defaults to the order's current coupon_lines codes. */
   couponCodes?: string[];
   /** Fees; defaults to the order's current fee_lines. */
-  fees?: Array<{ name: string; amount: number; tax_class?: string; tax_status?: string }>;
+  fees?: Array<{ name: string; amount: number; tax_group?: string; tax_status?: string }>;
   billing?: any;
   shipping?: any;
   chosenShippingMethodId?: string;
@@ -158,7 +154,7 @@ export async function repriceOrder(sr: any, order: any, opts: RepriceOpts = {}):
   const fees = opts.fees ?? (order.fee_lines ?? []).map((f: any) => ({
     name: f.name,
     amount: f.total,
-    tax_class: f.tax_class,
+    tax_group: f.tax_group,
     tax_status: f.tax_status,
   }));
 
@@ -175,9 +171,7 @@ export async function repriceOrder(sr: any, order: any, opts: RepriceOpts = {}):
     shipping_address: opts.shipping ?? order.shipping ?? order.billing,
     chosenShippingMethodId: chosen,
     settings: ctx.settings,
-    taxRates: ctx.taxRates,
-    zones: ctx.zones,
-    zoneMethods: ctx.zoneMethods,
+    locations: ctx.locations,
   });
 
   if (manualMode) {

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

@@ -4,7 +4,7 @@
  *
  * Actions: save | delete | batch | duplicate | set-stock | search |
  * save-term | delete-term | list-terms
- * Body: { action, ...payload } — see skills/commerce/docs/api-admin.md.
+ * Body: { action, ...payload } — see .agents/skills/commerce/docs/api-admin.md.
  */
 import { createClientFromRequest } from "npm:@base44/sdk";
 import { HttpError, requireAdmin } from "../../../shared/commerce/auth.ts";
@@ -97,11 +97,7 @@ async function save(sr: any, payload: any): Promise<any> {
   }
 
   await adjustTermCounts(sr, "commerce.ProductCategory", prev?.category_ids ?? [], saved.category_ids ?? []);
-  await adjustTermCounts(sr, "commerce.ProductTag", prev?.tag_ids ?? [], saved.tag_ids ?? []);
-  if ((prev?.shipping_class_id ?? "") !== (saved.shipping_class_id ?? "")) {
-    if (prev?.shipping_class_id) await bumpCount(sr, "commerce.ShippingClass", prev.shipping_class_id, -1);
-    if (saved.shipping_class_id) await bumpCount(sr, "commerce.ShippingClass", saved.shipping_class_id, +1);
-  }
+  await adjustTermCounts(sr, "commerce.ProductRibbon", prev?.ribbon_ids ?? [], saved.ribbon_ids ?? []);
 
   // variations diff — only when the caller sends a variations array
   let savedVariations: any[] | undefined;
@@ -153,8 +149,7 @@ async function remove(sr: any, id: string): Promise<any> {
   for (const v of variations) await sr.entities["commerce.ProductVariation"].delete(v.id);
 
   await adjustTermCounts(sr, "commerce.ProductCategory", product.category_ids ?? [], []);
-  await adjustTermCounts(sr, "commerce.ProductTag", product.tag_ids ?? [], []);
-  if (product.shipping_class_id) await bumpCount(sr, "commerce.ShippingClass", product.shipping_class_id, -1);
+  await adjustTermCounts(sr, "commerce.ProductRibbon", product.ribbon_ids ?? [], []);
 
   await sr.entities["commerce.Product"].delete(id);
   await dispatch(sr, "product.deleted", product);
@@ -212,8 +207,7 @@ async function duplicate(sr: any, id: string): Promise<any> {
 
   // duplicated product participates in taxonomy counts too
   await adjustTermCounts(sr, "commerce.ProductCategory", [], created.category_ids ?? []);
-  await adjustTermCounts(sr, "commerce.ProductTag", [], created.tag_ids ?? []);
-  if (created.shipping_class_id) await bumpCount(sr, "commerce.ShippingClass", created.shipping_class_id, +1);
+  await adjustTermCounts(sr, "commerce.ProductRibbon", [], created.ribbon_ids ?? []);
 
   await dispatch(sr, "product.created", created);
   return { product: created, variations_copied: copied };
@@ -295,7 +289,7 @@ async function search(sr: any, payload: any): Promise<any> {
 
 const TAXONOMIES: Record<string, string> = {
   category: "commerce.ProductCategory",
-  tag: "commerce.ProductTag",
+  ribbon: "commerce.ProductRibbon",
   attribute: "commerce.ProductAttribute",
   "attribute-term": "commerce.ProductAttributeTerm",
 };
@@ -309,7 +303,7 @@ function taxonomyEntity(taxonomy: string): string {
 }
 
 /**
- * Upsert a category, tag, attribute or attribute value. Exists so an agent (or
+ * Upsert a category, ribbon, attribute or attribute value. Exists so an agent (or
  * any API caller) can create these — referencing one from a product is useless
  * while the record itself can only be made in the admin UI. An attribute plus
  * its values is what a product's `attributes[].options` draws on.
@@ -341,8 +335,8 @@ async function saveTerm(sr: any, payload: any): Promise<any> {
     if (term.image !== undefined) fields.image = term.image;
     if (term.menu_order !== undefined) fields.menu_order = Number(term.menu_order) || 0;
   } else if (!term.id) {
-    // Tags are created by typing a name on the product form, so "create" has to
-    // mean get-or-create: a second Best Seller would split the tag in two.
+    // Ribbons are created by typing a name on the product form, so "create" has
+    // to mean get-or-create: a second Best Seller would split the ribbon in two.
     const existing = (await scanAll(sr.entities[entity], null, "name"))
       .find((t: any) => String(t.name ?? "").toLowerCase() === name.toLowerCase());
     if (existing) return existing;
@@ -396,8 +390,8 @@ async function renameAttributeValue(sr: any, attributeId: string, from: string,
 }
 
 /**
- * Delete a term. For a category or tag, products keep the id in
- * category_ids/tag_ids — same as the admin UI, and the storefront skips ids that
+ * Delete a term. For a category or ribbon, products keep the id in
+ * category_ids/ribbon_ids — same as the admin UI, and the storefront skips ids that
  * no longer resolve; detach: true strips it from every product instead.
  * Deleting an attribute always takes its terms with it: a term outliving its
  * attribute is unreachable.
@@ -426,7 +420,7 @@ async function deleteTerm(sr: any, payload: any): Promise<any> {
       }
     }
   } else if (entity !== "commerce.ProductAttributeTerm" && payload.detach) {
-    const field = entity === "commerce.ProductCategory" ? "category_ids" : "tag_ids";
+    const field = entity === "commerce.ProductCategory" ? "category_ids" : "ribbon_ids";
     for (const p of await scanAll(sr.entities["commerce.Product"], null, "-created_date")) {
       if ((p[field] ?? []).includes(id)) {
         await sr.entities["commerce.Product"].update(p.id, {

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

@@ -6,7 +6,7 @@
  */
 import { createClientFromRequest } from "npm:@base44/sdk";
 import { HttpError, requireAdmin } from "../../../shared/commerce/auth.ts";
-import { refundOnlinePayment } from "../../../shared/commerce/payments.ts";
+import { refundCardOrder } from "../../../shared/commerce/payments.ts";
 import { round2 } from "../../../shared/commerce/money.ts";
 import { restockLine } from "../../../shared/commerce/stock.ts";
 import { transitionOrder } from "../../../shared/commerce/orders.ts";
@@ -57,20 +57,21 @@ async function create(sr: any, payload: any, actor: string): Promise<any> {
 
   // Refund the money first: a provider refund that fails must not leave a
   // recorded refund behind, so nothing local is written until this succeeds.
-  // Returns null when the order wasn't paid online (manual gateways settle
-  // outside the store, so the record alone is the refund).
-  let gatewayRefund: Awaited<ReturnType<typeof refundOnlinePayment>> = null;
+  // Returns null when the order wasn't paid by card (manual gateways settle
+  // outside the store, so the record alone is the refund). While the store's
+  // card-payment.ts refund stub is unimplemented, this throws 501 —
+  // record the refund without `refund_payment` instead.
+  let gatewayRefund: Awaited<ReturnType<typeof refundCardOrder>> = null;
   if (payload.refund_payment) {
-    gatewayRefund = await refundOnlinePayment(sr, order, {
+    gatewayRefund = await refundCardOrder(sr, order, {
       amount,
       reason: payload.reason,
-      idempotencyKey: `refund-${order.id}-${amount}-${alreadyRefunded}`,
     });
     if (!gatewayRefund) {
       throw new HttpError(
         400,
-        "This order has no online payment to refund — record the refund without `refund_payment`, and return the money the way it was taken.",
-        "no_online_payment",
+        "This order has no card payment to refund — record the refund without `refund_payment`, and return the money the way it was taken.",
+        "no_card_payment",
         { payment_method: order.payment_method ?? "" },
       );
     }
@@ -128,7 +129,7 @@ async function create(sr: any, payload: any, actor: string): Promise<any> {
   if (gatewayRefund) {
     await sr.entities["commerce.OrderNote"].create({
       order_id: order.id,
-      note: `Refunded ${amount} through ${gatewayRefund.provider} (${gatewayRefund.id}, ${gatewayRefund.status}).`,
+      note: `Refunded ${amount} through the payment provider (${gatewayRefund.refund_id}).`,
       is_customer_note: false,
       added_by: actor,
     });