Skip to main content
Run the embedded commerce engine in a Node.js application. By the end, you will have a customer, a persisted order for two mugs, and a read-back check that verifies the order total is 25.00 USD. This walkthrough uses @stateset/embedded 1.35.1, a published release. The core engine runs against a local SQLite file. It does not require a StateSet account, a hosted API key, or a model provider. Downloading the package requires network access; the example runs locally after installation.
Looking for a customer support agent? Use the ResponseCX quickstart. Want an AI agent to operate commerce tools? Complete this walkthrough, then connect the MCP server to the same database.

Prerequisites

  • Node.js 20.20.0 or later and npm 10 or later.
  • A writable project directory for your database and example files.
  • A supported native package for your operating system and architecture; npm selects it during installation.

Step 1 — Create a project

Use a new directory so the example has its own database:
The package includes a native binding. Keep optional dependencies enabled: npm uses them to install the binary for your platform.

Step 2 — Create and verify an order

Save this complete program as quickstart.mjs:
Run it from the project directory:
The program uses findOrCreate to reuse the example customer by email, then creates an order with the customer’s actual ID. createExact accepts decimal strings for prices; the returned totalAmountExact keeps the order total as a decimal string. Success: the assertions pass and the output looks like this. Your IDs will differ:
This creates an order record. It does not charge a payment method or send a shipment. Continue with the order lifecycle guide for the next operations.
Re-running quickstart.mjs reuses the customer and creates another order. It replaces order-id.txt with the newest ID. For a read-only check, run the next program instead.

Step 3 — Read the order from a new process

Save this as inspect-order.mjs:
Success: the same order ID and 25.00 USD are returned after the creating process has exited. Both programs open ./quickstart.db; run them from the same project directory. Using :memory: instead creates a temporary database that does not survive the process.

What you created

Troubleshooting

For another language, use the binding reference. For installation problems, share your OS, CPU architecture, Node version, package version and redacted error in the support checklist.

Next steps

The restart test builds on this persistence check by verifying that payment replay reuses its original record after the creating process exits.

Connect an AI agent

Expose commerce tools over MCP against the database you just created.

Follow an order's lifecycle

Continue with payment, inventory and fulfillment operations.

Use the CLI

Explore terminal workflows and model-backed commands.

Back up your database

Understand backup and restore before building on persistent data.
Last modified on September 20, 2026