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 (product types, order lifecycle, coupon rules, tax priority/compound math, shipping zones) using Base44-idiomatic primitives (entity JSON schemas, Deno functions, the Base44 SDK).

What's included

• 24 entities — Products (simple/grouped/external/variable), variations, categories, tags, attributes + terms, 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.
• 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.
• 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.
• 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.
• Admin UI (src/commerce/admin/) — a React/Tailwind/shadcn admin with a familiar store back-office information architecture: dashboard, orders, products, coupons, customers, reports, full settings, 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 variable-product 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 so agents pick it up natively.

Repo map

base44-commerce-template/
├── base44/
│   ├── entities/     24 .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 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 + AGENTS.md registration
│       ├── references/    per-topic guides (product rendering, product page & variants,
│       │                  Stripe, 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
   npm i <only the missing names>

   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="/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 /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 a sample catalog when with_sample_data: true and the store is empty. Once the general settings group exists the store counts as ready and the first-run screen stops appearing. If an agent is installing this, it should ask which data the user wants first — a generated catalog for their actual business, the generic demo data, or nothing: see 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 settle the store's data with the user — generate a real starter catalog via commerce/seed-store + commerce/admin-products, seed the demo catalog, or leave it to 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, variable-product 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 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 manual gateways (bank transfer / cheque / COD) 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.