SveltyCMS is a headless CMS first. Most installs never run a store. Commerce is therefore opt-in, not part of the boot path:

Do not put shipping, tax, coupons, or carts inside Stripe. Stripe is one payment gateway. PayPal (or others) would implement the same PaymentGateway interface. Catalog + checkout belong in the Commerce plugin so a blog/SaaS/docs site never ships a store pipeline.

Keep the core light (extensions, not a store kernel)

SveltyCMS stays a CMS. Checkout is an add-on graph you enable. That is how a docs site, SaaS admin, or brochure install avoids loading cart cookies, tax tables, Stripe SDK, and order menus.

There is no fifth product type called “API extension”. HTTP is either a plugin { type: "route" } or a catch-all handler that refuses work until the matching plugin is on.

What loads on a blog/SaaS install (Commerce off, no ecommerce preset): kernel + whatever field widgets the content model uses. No carts collection, no /shop, no Stripe SDK, no order dashboard widgets unless someone adds them (they render empty).

What loads on a store: enable Commerce + (optional) Stripe + pick the ecommerce preset. Add dashboard widgets if you want admin snapshots. Add Live Shipping / TaxJar only if table rates are not enough.

That split is the performance rule: unused store code stays out of the boot path and out of the client bundle. Tree-shaken field widgets, disabled plugins, and picker-only dashboard packages are the four surfaces — plus gated handlers so guest HTTP does not invent a fifth.

Why commerce stays opt-in (no fifth “API extension” type)

A headless CMS is often a marketing site, docs hub, or app backend — not a store. Shipping carts, tax, and order menus on every install would add unused collections and checkout code to those sites.

SveltyCMS already has four extension surfaces. HTTP APIs are plugin routes or gated core handlers, not a separate product type:

{ type: "route" } on a plugin is registered in pluginRouteRegistry and dispatched by the catch-all API when the path is not a core namespace. Guest commerce stays on /api/commerce/* (dedicated handler) because CSRF, tenant, and public cart rules are domain-specific — still off until the Commerce plugin is enabled.

Setup Wizard E-commerce preset is independent: it only creates collections if that template is chosen. A blog install that never picks it never sees products / orders in the admin list.

Plugin vs widget vs preset

A cart widget is not a substitute for a Commerce plugin.

In this CMS a widget is a field type (definition + Input + Display): Price, Currency, relation, repeater. It cannot own a guest session, HTTP routes, inventory decrement, or tax quotes.

If Commerce is not a plugin, it still must not be “just a cart widget”. The remaining honest options are: (1) Commerce plugin (recommended — off unless enabled), or (2) core services that every install loads (rejected: this CMS is not always a store). There is no third option where a widget replaces checkout.

Storefront may still render a cart with widgets/blocks; those call /api/commerce/cart from the plugin.

Status (August 2026): ecommerce preset, Price + computeTotals, Commerce plugin (guest cart, quotes, inventory, checkout — tenant-scoped), Stripe PaymentIntent from server grandTotal, Smart Importer Woo/Shopify catalog import, and two freemium dashboard widgets. Storefront /shop, /cart, /checkout, /account/orders, /account/addresses. Transactional mail via nodemailer + better-svelte-email. Commerce Pro (gift cards, bundles, custom panes, analytics) is license-gated.

Honest read: guest checkout exists when the Commerce plugin is enabled. Enable it in Extensions; pick the ecommerce preset for collections. Every commerce query uses locals.tenantId.

Still open (not a separate plan file)

Remaining work lives on the 2026 roadmap, not in a parallel plan MDX.

Progress vs like-for-like (public docs, August 2026)

Not a ranking. Like-for-like = self-hosted CMS that can run a store. Shopify is listed as a packaging reference (SaaS, not the same product class). Sources: Payload ecommerce overview and RFC #14239; Drupal Commerce 2.x developer guide; WooCommerce.com feature list. Re-check those pages before a purchase decision.

Where this puts us: a guest can complete a priced checkout when Commerce + the ecommerce preset are enabled. Account order history, addresses, and transactional mail are in this tree. Still behind Drupal Commerce / WooCommerce on ConditionPlugin/BOGO promotions, Stripe Billing, and Schema.org Product/Offer markup. Like-for-like notes only — not a ranking.

Architecture

A site that never enables Commerce or Stripe behaves like any other CMS. Enabling Stripe alone is enough for “paywall this entry”. Enabling Commerce + Stripe is a store. Enabling Commerce + a future PayPal plugin is the same checkout with a different PSP.

What Drupal Commerce does when you “enable ecommerce”

Drupal core is also not a store. Drupal Commerce (public docs, Commerce 2.x) is a set of Drupal modules you enable on top of core — the same idea as our optional Commerce plugin. Enabling it does not replace nodes/users; it registers extra entity types (Product, Variation, Order, Order item, Store, Payment) and plugin managers (Drupal’s small strategy plugins, not Drupal modules).

Take from Drupal: optional module, payment as a gateway plugin (not the store), adjustments with weight, conditions on both promotions and gateways, checkout as flow + panes, shipping as an extra adjustment contributor.

Do not copy: Drupal’s PHP module + YAML + cache-rebuild cycle, or folding the store into core. SveltyCMS already has definePlugin parts (routes, schemas, capabilities, settings) — Commerce should use those so a non-store CMS never boots checkout.

Public sources: Adjustments, Conditions, Payments, Checkout. Date-stamped August 2026.

Lookups (tax rates, zones, coupons) happen before computeTotals. The engine is a pure function so it can stay under the < 5 ms budget (plan E2).

What is in the product today

Ecommerce preset

Enable E-commerce in the Setup Wizard. Collections (verified db_fieldName values in src/routes/setup/presets.ts):

Headless storefronts already read catalog via /api/collections/products (auth + publication policy apply). Checkout services are not on that path yet.

Catalog import — Smart Importer (shipped)

The Smart Importer plugin maps an existing store catalog into the ecommerce preset. It does not run checkout.

Enable the plugin (Admin → Config → Migration tile), then import into products. Mixed WordPress dumps (posts + products) still use --format=wordpress; product items also get an ecommerce block from _sku / _price / _stock meta. Platform guide: WordPress migration (WooCommerce section). Editorial path: Migration & Data Operations.

After import, add the Commerce Orders / Inventory dashboard widgets to watch stock and recent orders (empty until you have those collections and data).

Admin dashboard widgets (shipped)

Two marketplace-portable packages under src/routes/(app)/dashboard/widgets/. Freemium — 14-day key-less trial, then checkExtensionLicense("dashboard", id). Not a cart widget.

Add them from the dashboard widget picker. Missing preset collections → empty state, not 404. After trial without a key: <UpgradePrompt> on the client and 403 LICENSE_REQUIRED on the API. Details: Dashboard widgets, Dashboard API.

Order status

Preset options (do not invent paid / fulfilled):

pending · processing · shipped · delivered · cancelled · refunded

Mapping when integrating gateways: paid → processing, fulfilled → shipped. Guards in order-service.ts: cancelled only from pending or processing.

Price calculator (shipped)

src/services/commerce/types.ts + price.ts — integer minor units, CurrencyMismatchError, rounding (JPY 0 decimal places; EUR/USD/CHF 2). Tests: tests/unit/services/commerce/price.test.ts.

This helper is not a reason to boot commerce on every CMS. Checkout imports it from the Commerce plugin path so unused installs do not run cart HTTP.

import { money, add, roundForCurrency } from "@src/services/commerce/price";

const subtotal = money(1999, "EUR"); // €19.99
const shipping = roundForCurrency(4.5, "EUR"); // 450
const total = add(subtotal, shipping); // 2449

Stripe plugin (payments only)

Stripe stays a payment plugin. It must not grow into a store: no shipping tables, no tax engine, no cart.

When Commerce is enabled, Stripe receives server grandTotal. When Commerce is off, Stripe can still charge a single amount (membership, donation, paywalled entry). Plugin docs: stripe.mdx.

Field widgets

Price and Currency store money on entries. The commerce Price type is the service-layer representation (cents + ISO code) used by totals — keep them aligned when wiring the engine. Admin dashboard widgets (Orders / Inventory) are a separate package type — see above.

Commerce plugin (shipped, disabled by default)

Home: src/plugins/commerce/ (definePlugin, disabled by default). Enable in Extensions. Core CMS does not register checkout unless the plugin is on. Guest HTTP is /api/commerce/* — not /api/plugins/commerce (plugins:execute is never required).

PaymentIntent amount is the server grandTotal (POST /api/commerce/pay with orderId only). Confirm compares Stripe amount to order.totalCents (F1). Webhooks are tenant-scoped (stripeIntentId + tenantId).

Monetization (marketplace, same as widgets/plugins)

Commerce is not a paid cart widget. It uses the existing license manager and the three marketplace tiers already documented for widgets: Free, Freemium (14-day key-less trial), Paid.

checkExtensionLicense(type, id) → marketplace POST /api/v1/license/verify with extension: "plugin:commerce" (or "plugin:stripe"). Keys: LICENSE_KEY_PLUGIN_COMMERCE or master LICENSE_KEY. 14-day trial is keyed off the first admin’s createdAt (same as widgets). Fail-open only when a key is configured and the marketplace is down.

Recommended SKU split (four streams, one license system)

Keep one plugin id plugin:commerce (do not ship a second plugin:commerce-pro toggle). Free checkout stays on; Pro is requireCommercePro() / field strip. Payment PSPs and live carriers are separate plugins so a membership site can buy Stripe without a store, and a store can add UPS later without a Commerce Pro bundle rewrite.

Live UPS / FedEx / DHL and TaxJar are paid plugins (plugin:shipping-live, plugin:taxjar) on the Commerce ShippingRateProvider / TaxProvider ports — same idea as Stripe on PaymentGateway. They are not field widgets and not Commerce Pro. Unlicensed or disabled: guest checkout keeps free shipping_zones / tax_rates (no guest 403). A tracking or tax-report dashboard widget would be a later SKU; it would not replace the quote plugins.

What to sell vs what stays free

Give away a working store so people adopt the CMS; charge for extras that other ecosystems often sell as paid add-ons (subscriptions, gift cards, live carriers — verify current third-party pricing before any public comparison).

Do not license-gate: enabling the Commerce plugin, adding to cart, coupon validate, tax/shipping quote, or placing an order with the four preset coupon types. That would make “CMS that is not always a store” painful and would hide the free core. Do license-gate admin extras: the Commerce Orders and Commerce Inventory dashboard widgets (14-day key-less trial, then checkExtensionLicense("dashboard", id)). They never load a store into a blog install — if the ecommerce preset collections are missing, the widgets render an empty state.

Dashboard widget SKUs (dashboard:commerce-orders, dashboard:commerce-inventory) use the same 14-day trial as dashboard marketplace. Listing them on marketplace.sveltycms.com is what turns verify-404 (local/free) into a paid SKU after the trial. See Admin dashboard widgets above.

Indicative list prices: Commerce Pro ~€79 / year (or a lifetime SKU on the marketplace); Stripe plugin ~€4.99; dashboard widgets €12.99. Stripe stays its own SKU so a membership site can pay for Stripe Pro without buying a store. List the packages on marketplace.sveltycms.com or verify-404 treats them as local/free.

Enforcement (must match widgets)

Server (source of truth) — plugin routes and beforeSave / order hooks:

import { checkExtensionLicense } from "@src/utils/license-manager";

const status = await checkExtensionLicense("plugin", "commerce");
if (!status.active) {
  // 403 LICENSE_REQUIRED on Pro endpoints (gift cards, subscriptions, …)
  // Strip Pro fields on save — never persist unlicensed data
}

Client — admin Commerce settings / pane builder:

<UpgradePrompt extensionId="plugin:commerce" price="€24.99" />

Same pattern as dashboard marketplace and Stripe’s premium-field strip. Listing the package on marketplace.sveltycms.com as plugin:commerce is what makes verify return 404 (treated as free/local) vs a paid SKU.

Security

Multi-tenancy

Core CMS already scopes collections by tenantId. Commerce uses the same filter on carts, orders, coupons, tax rates, shipping zones, and inventory (CommerceStore / requireCommerceTenantId). Stripe keys are resolved per tenant (getStripe()). Unit isolation: tests/unit/plugins/commerce.test.ts. HTTP two-tenant cart→order is still open.

Tests

HTTP /api/commerce cart→order→refund (two tenants) is not in the integration suite yet. Collection mutations are a separate contract (content entries, not checkout).

Related