Base44 Commerce Template

A Commerce backend + admin UI for Base44 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, per-location shipping and tax) using Base44-idiomatic primitives (entity JSON schemas, Deno functions, the Base44 SDK).

What's included

• 20 entities — Products (a product sells variants when it carries attributes; no type field), variations, categories, ribbons, attributes + values, reviews, orders (embedded line/shipping/tax/fee/coupon lines), order notes, refunds, coupons, customers, Shipping & Tax Locations (shipping rates + tax groups per location), payment gateways, store settings, webhooks + deliveries, carts, download permissions, email log.
• 16 backend functions — 9 admin (commerce/admin-products, commerce/admin-orders, commerce/admin-refunds, commerce/admin-coupons, commerce/admin-customers, commerce/admin-reviews, commerce/admin-webhooks, commerce/admin-reports, commerce/admin-tools), 4 storefront (commerce/storefront-catalog, commerce/storefront-cart, commerce/storefront-checkout, commerce/storefront-account), 2 payment (commerce/payments, commerce/payment-webhook), and an idempotent commerce/seed-store — one call seeds the business defaults and the whole catalog (products with attributes in, variants/categories/taxonomy created internally).
• Online card payments, order side premade — checkout routing, payment links for unpaid orders, two idempotent confirmation paths (customer return + webhook) 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.
• 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.
• 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/, which holds SKILL.md (the short map agents start from), installation-guidelines.md, post-installation.md, per-topic guides in references/ and the API references in 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/     20 .jsonc entity schemas (commerce.*.jsonc)
│   ├── functions/
│   │   └── commerce/ 16 Deno functions (entry.ts each), invoked as "commerce/<name>"
│   ├── agents/
│   │   └── commerce/ StoreAdmin.jsonc — AI admin copilot ("commerce/StoreAdmin")
│   └── shared/
│       └── commerce/ commerce engine + static data (bundled into every function)
├── src/
│   └── commerce/
│       ├── admin/    React admin UI (copy into your app's src/commerce/)
│       └── utils/    storefront helpers — variant selection, shipping promos
├── scripts/
│   └── install.js         static installer (run from <app>/examples/commerce/scripts/)
├── skills/
│   └── 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,
│       │                  online payments, scheduled work, emails, webhooks, media & downloads,
│       │                  limits, security)
│       └── docs/
│           ├── api-admin.md       admin function/entity reference
│           └── api-storefront.md  storefront function reference (build your own shopfront)
└── README.md

Get it from npm

The template is published as @base44/app-plugin-commerce — a source-only package whose tarball is exactly the base44/, scripts/, skills/ and src/ folders of this repo, with no build or bundling step. Unpack it into your app at examples/commerce/ and the install flow below works unchanged:

npm pack @base44/app-plugin-commerce      # → base44-app-plugin-commerce-<version>.tgz
mkdir -p examples/commerce
tar -xzf base44-app-plugin-commerce-*.tgz --strip-components=1 -C examples/commerce
node examples/commerce/scripts/install.js

scripts/install.js resolves the app root relative to its own location (<app>/examples/commerce/scripts/), so run it from the unpacked copy rather than from inside node_modules/.

Quick start (Base44 CLI)

From your existing Base44 app:

1. Copy the files — either copy this whole repo into your app at examples/commerce/ and run node examples/commerce/scripts/install.js, or merge entities/, functions/, shared/ into your app's base44/ directory by hand (see skills/commerce/installation-guidelines.md). Confirm your base44/config.jsonc entitiesDir/functionsDir point at these folders.
2. Push the schema, functions and agent:

   npx base44 entities push
   npx base44 functions deploy
   npx base44 agents push

3. Copy the UI files: src/commerce/admin/ → src/commerce/admin/ and src/commerce/utils/ → src/commerce/utils/.
4. Confirm UI deps — sonner, recharts and react-markdown all ship with the default Base44 template and are the only ones the admin needs, so usually there is nothing to install. Read your app's package.json first and install only the names missing from it — never re-install a package that is already a dependency:

   grep -E '"(sonner|recharts|react-markdown)"' package.json   # all three listed → skip the install
   npx npq install <only the missing names>   # npq audits the package before npm installs it

   See src/commerce/admin/README.md for the exact shadcn component list.
5. Mount the admin router in your app:

   import AdminApp from "@/commerce/admin";
   // inside your <Routes>:
   <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 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 §2.

Quick start (Base44 MCP / hosted apps)

If you build on Base44's hosted platform, use the Base44 agent/MCP to write the files instead of the CLI:

1. Copy this whole repo into the target app at examples/commerce/ (e.g. download + extract a tarball with run_command), then run node examples/commerce/scripts/install.js via run_command — or use write_file to copy every file under base44/ and src/commerce/ individually (use list_directory/read_file to adapt to the app's actual layout — e.g. the @/api/base44Client path and your router file).
2. Wait for the app to build (get_app_status), then confirm entities exist (list_entity_schemas).
3. Grant your user the admin role, then seed the store's data — one commerce/seed-store call takes the whole catalog via products, or with_sample_data: true for the demo catalog; leave both out for defaults only, or skip the call for the admin's first-run Initialize store defaults screen (skills/commerce/post-installation.md §2).

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. What does ship for the storefront is helper logic: 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 (what to render in a grid vs. a product page, and which fields each call returns) and skills/commerce/references/storefront-product-page.md, the variant rules that go with the helpers.
• 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.

Next steps

• Install into your app: skills/commerce/installation-guidelines.md
• Operate & extend: the commerce skill — skills/commerce/SKILL.md
• Build a storefront: skills/commerce/docs/api-storefront.md
• Admin automation / alternative admin: skills/commerce/docs/api-admin.md

Releasing (maintainers)

Publishing is manual: Actions → Manual Package Publish → Run workflow (.github/workflows/manual-publish.yml).

Inputs: version (patch/minor/major or an explicit 0.2.0), npm_tag (latest, beta, …) and dry_run. The workflow bumps package.json, prints the tarball contents, runs npm publish, then commits the bump, tags v<version> and cuts a GitHub release. A dry run publishes nothing and leaves no tag or commit.

Registry auth uses npm trusted publishing — the workflow holds no npm token. It authenticates over OIDC (id-token: write plus npm install -g npm@latest, which needs npm ≥ 11.5.1), which also signs a provenance attestation for each release. This requires a trusted publisher on the npm package (Settings → Trusted Publisher → GitHub Actions, repository base44/app-plugin-commerce, workflow manual-publish.yml, no environment); if that config is missing or the workflow filename changes, publishing fails with ENEEDAUTH.

Pushing the release commit and tag additionally needs the org's BASE44_GITHUB_ACTIONS_APP_ID variable and BASE44_GITHUB_ACTIONS_APP_PRIVATE_KEY secret.