This page is the engine: extension surfaces, the totals pipeline, the checkout services, and the HTTP contract. Turning a store on and running orders is the E-commerce guide.

SveltyCMS is a headless CMS first, so commerce ships as an opt-in add-on graph rather than a store kernel. The sections below are how that graph is wired, what each part owns, and what stays out of the boot path.

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.

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.

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.

Service layout

Home: src/plugins/commerce/ (definePlugin, disabled by default).

Totals and pricing engine

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).

computeTotals sorts adjustments by weight and folds them into the subtotal; the same inputs always produce the same breakdown, and a negative result clamps to zero. AdjustmentType is promotion | fee | shipping | tax — today only promotion (coupons at weight 10, gift cards at weight 40), shipping (20), and tax (30) are emitted. Nothing emits fee yet.

quotes.ts resolves each adjustment tenant-scoped, live provider first, then the preset tables:

• Coupon — expiresAt → COUPON_EXPIRED, minSpend → COUPON_MIN_SPEND, usageLimit vs usedCount → COUPON_LIMIT. Types: percentage, fixed_cart, fixed_product (amount × total cart units), free_shipping.
• Shipping — first zone whose countries list is empty or matches the order country; free when freeThreshold is reached or the coupon is free_shipping. Digital-only carts skip shipping entirely.
• Tax — rates for the country, preferring an exact state match, then a row without state; shippingTaxable adds the shipping amount to the base.

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.

Preset number fields (products.price, coupon amount / minSpend, zone rate / freeThreshold, tax rate) hold major units; money.ts converts them (majorToPrice / priceToMajor). The commerce Price type is the service-layer representation (integer minor units + ISO code) used by totals — keep the two aligned when wiring the engine.

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

Order state machine

Preset orders.status values come from ORDER_STATUSES in src/services/commerce/types.ts: pending · processing · shipped · delivered · cancelled · refunded. The ALLOWED map in order-service.ts accepts only these moves; anything else raises 409 INVALID_STATUS:

cancelOrder adds a window on top of the transition table: the order must still be pending and younger than one hour (canCancelOrder, CANCEL_WINDOW_MS = 60 * 60 * 1000), otherwise 409 CANCEL_WINDOW. Cancel and refund both restore stock through restoreStock, and a cancel that used a coupon decrements usedCount again. Checkout also accepts offline methods (cod, bank_transfer via OFFLINE_METHODS) alongside stripe.

Payments and fulfillment ports

payment-gateway.ts defines the PSP port (createIntent / retrieveIntent). Stripe implements it today; a PayPal plugin would implement the same interface, which is why the store never talks to a gateway directly.

• POST /api/commerce/pay takes orderId only. A client-supplied amount is logged and ignored (F1); the PaymentIntent amount is the server’s order.totalCents.
• POST /api/commerce/confirm retrieves the intent, requires intent.amount === order.totalCents (409 AMOUNT_MISMATCH) and succeeded, then moves the order to processing.
• Webhooks: handleStripeWebhook verifies the Stripe signature, takes the tenant from the intent metadata, and upserts on { stripeIntentId, tenantId } in plugin_stripe_payments — duplicate deliveries are safe. GET /api/stripe/config returns the tenant’s publishable key.

fulfillment.ts holds the ShippingRateProvider / TaxProvider registries (registerShippingRateProvider, registerTaxProvider, resetFulfillmentProviders). The first non-null quote wins. A provider that is disabled, unlicensed, or unconfigured reports ready: false through isFulfillmentPluginReady and returns null, so guest checkout quietly falls back to the preset shipping_zones / tax_rates tables instead of failing.

Licensing and enforcement

checkExtensionLicense(type, id) verifies against the marketplace (POST /api/v1/license/verify) with extension: "plugin:commerce" (or "plugin:stripe"). Keys follow LICENSE_KEY_<TYPE>_<ID> — LICENSE_KEY_PLUGIN_COMMERCE, LICENSE_KEY_PLUGIN_STRIPE — or the master LICENSE_KEY. The 14-day key-less trial is keyed off the install’s first user (computeTrialStatus). A verify 404 means “not listed on the marketplace” and is treated as local/free; the only fail-open path is a marketplace outage with a key configured.

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.

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="€79 / year" />

Same pattern as dashboard marketplace and Stripe’s premium-field strip — src/plugins/stripe/index.ts deletes _stripeSubscriptionPlan, _stripeInvoiceSettings, _stripeMultiCurrency, _stripeCustomTheme, and _stripeAnalytics in beforeSave when no licence is active.

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, and every commerce query uses locals.tenantId. requireCommerceTenantId fails closed (400 TENANT_REQUIRED) when multi-tenancy is on and no tenant was resolved, and CommerceStore injects tenantId into every filter and write. Stripe keys are resolved per tenant (getStripe(tenantId)). Unit isolation: tests/unit/plugins/commerce.test.ts. HTTP two-tenant cart→order is still open.

The plugin’s own migration (001_commerce_addresses) creates the tenant-scoped commerce_addresses collection; the address API returns an empty list until that collection exists.

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