The Embedded Engine

SQLite for commerce — a full commerce engine that runs inside your process, not behind a network call.

iCommerce is the engine inside the agent. You don’t call it over a network; you compile it into your runtime.

The analogy is SQLite. Postgres is a server you connect to. SQLite is a library you embed — and that single difference changes latency, offline behaviour, and how you reason about failure. iCommerce is that, for commerce.

What “embedded” buys you

Property	API-first (Stripe, Shopify)	iCommerce
Where it runs	Their servers	Your process
Latency per call	Network round-trip	In-memory
Works offline	No	Yes
Type safety	Whatever your client generates	Native, across 10 bindings
Failure mode	Their outage is your outage	Local

For an agent doing dozens of reads to decide one action, in-process calls are the difference between a coherent turn and a timeout.

Start

import { Commerce } from '@stateset/embedded';

const commerce = new Commerce('./store.db');   // or ':memory:'

That’s the whole setup — no server to run, no connection string, no control plane.

use stateset_sdk::prelude::*;
use rust_decimal_macros::dec;

let commerce = Commerce::new("./store.db")?;

A complete flow

const cart = await commerce.carts.create({
  customerEmail: '[e-mail]',
  customerName: 'Alice Smith',
});

await commerce.carts.addItem(cart.id, {
  sku: 'SKU-001',
  name: 'Widget',
  quantity: 2,
  unitPrice: 29.99,
});

const result = await commerce.carts.complete(cart.id);
console.log(`Order created: ${result.orderNumber}`);

Same thing in Rust, with exact decimals:

let customer = commerce.customers().create(CreateCustomer {
    email: "[e-mail]".into(),
    first_name: "Alice".into(),
    last_name: "Smith".into(),
    ..Default::default()
})?;

let order = commerce.orders().create(CreateOrder {
    customer_id: customer.id,
    items: vec![CreateOrderItem {
        sku: "SKU-001".into(),
        quantity: 2,
        unit_price: dec!(29.99),
        ..Default::default()
    }],
    ..Default::default()
})?;

commerce.orders().ship(order.id, Some("FEDEX123456".into()))?;

Storage

Backend	Use for
:memory:	Tests, ephemeral agents
SQLite file	Local-first, edge, single-node
PostgreSQL	Shared state across replicas

The API is identical across all three, so you can develop against :memory: and deploy against Postgres without changing call sites.

Two domains historically reported isSupported() == true on SQLite while every call failed — that gap is closed, but it’s worth calling isSupported() rather than assuming parity when you’re relying on a less common domain.

Determinism and explicit write intent

Operations are deterministic, and writes require explicit intent rather than being inferred. That’s what makes an agent holding the engine safe to reason about: a read cannot mutate, and a mutation is a decision someone made. See the CLI safety model for the same principle at the command line.

Money is never a float

const order = await commerce.orders.get(id);
order.totalAmount;   // "149.99"  ← string, exact

Every monetary value crosses as an exact decimal string. 0.1 + 0.2 !== 0.3 in binary floating point, and a commerce engine that sells exact settlement cannot afford that drift.

Some older binding fields still convert to f64 — roughly 50 fields on the Node and Python surfaces, including PaymentOutput.amount and OrderResponse.total_amount. See the money precision note for which to avoid until that lands.

When to embed

Situation	Why embedding fits
Agent workflows	Dozens of local reads per decision, no round-trips
Edge deployments	Works with no connectivity to a central service
High throughput	In-process calls, minimal overhead
Deterministic tests	:memory: gives a real engine with no fixtures

Related

• Quickstart
• Architecture
• Bindings — 11 languages, and their caveats
• MCP Server — 938 tools over this engine