StateSet API Docs

Choose the service and execution model before installing a package. The embedded commerce bindings operate a local database; hosted APIs use their own base URLs, credentials and contracts.

Choose a package

You are building	Package or interface	First working example
Local commerce in Node.js	`@stateset/embedded`	Create and read an order
Local commerce in Python	`stateset-embedded`, imported as `stateset_embedded`	Python setup below
Commerce tools for an AI agent	`@stateset/cli` and its `stateset-mcp` executable	MCP connection guide
Customer support automation	ResponseCX REST API	ResponseCX quickstart
Another hosted service	That service’s API or SDK	API directory
An existing `stateset-node` or `stateset-python` integration	Your installed REST client’s resource methods	Existing REST SDK integrations

The Node and Python embedded examples below target 1.35.1, a published release. Pinning the version makes the setup reproducible; keep the project’s lockfile with your code.

Node.js SDK

Check your runtime

@stateset/embedded 1.35.1 requires Node.js 20.20.0+ and npm 10+.

node --version
npm --version

The package includes a native module. Run the engine in a Node.js process with filesystem access, such as your backend or a local script. A browser bundle is a different runtime.

Install

mkdir stateset-node-example
cd stateset-node-example
npm init -y
npm install @stateset/embedded@1.35.1

Keep optional dependencies enabled: npm selects the native binary for your platform through an optional package. Install on the machine or container that will run the application.

Verify the installation

Save this as check-engine.mjs:

import assert from 'node:assert/strict';
import { Commerce } from '@stateset/embedded';

const commerce = new Commerce(':memory:');
const customer = await commerce.customers.create({
  email: 'ada@example.com',
  firstName: 'Ada',
  lastName: 'Lovelace',
});
const saved = await commerce.customers.get(customer.id);
assert.ok(saved);
assert.equal(saved.email, 'ada@example.com');
console.log(`Created and read customer: ${saved.email}`);

node check-engine.mjs

Success: Created and read customer: ada@example.com. The example uses an in-memory database, so each run starts empty. To persist data, use a file path such as ./store.db and follow the embedded quickstart.

The .mjs extension enables the import syntax in this example without changing package.json. Node methods return promises, so keep the await on each operation.

Python SDK

Check your runtime

stateset-embedded 1.35.1 requires Python 3.9+. Its published wheels target CPython 3.9–3.13 on Linux, macOS and Windows, with availability varying by architecture. The Linux wheels require a platform compatible with manylinux_2_34.

python3 --version

On an older Linux distribution, pip may fall back to building from source. That requires a Rust build toolchain and can take substantially longer than installing a wheel.

Create an environment and install

macOS / Linux
Windows PowerShell

mkdir stateset-python-example
cd stateset-python-example
python3 -m venv .venv
.venv/bin/python -m pip install stateset-embedded==1.35.1

mkdir stateset-python-example
cd stateset-python-example
py -m venv .venv
.\.venv\Scripts\python.exe -m pip install stateset-embedded==1.35.1

To require a prebuilt wheel and avoid a source build, add --only-binary=:all: to the pip install command. If pip reports no matching distribution, check the Python version, architecture and operating-system compatibility before choosing a different environment.

Verify the installation

Save this as check_engine.py:

from stateset_embedded import Commerce

commerce = Commerce(":memory:")
customer = commerce.customers.create(
    email="ada@example.com",
    first_name="Ada",
    last_name="Lovelace",
)
saved = commerce.customers.get(customer.id)
assert saved is not None
assert saved.email == "ada@example.com"
print(f"Created and read customer: {saved.email}")

Run it with the same environment’s interpreter:

.venv/bin/python check_engine.py

.\.venv\Scripts\python.exe check_engine.py

Success: Created and read customer: ada@example.com. The Python embedded binding uses synchronous methods here. Its package name is stateset-embedded, while the import is stateset_embedded.

Hosted API integrations

For a hosted service, first choose its base URL, header and credential. A ResponseCX key is not a commerce database credential, and an embedded library does not configure a hosted service. The developer guide contains complete JavaScript, Python and curl requests to read a ResponseCX workspace. It uses standard HTTP libraries, so you can verify access before introducing an SDK.

Existing REST SDK integrations

stateset-node and stateset-python are REST client packages. They are separate from @stateset/embedded and stateset-embedded; replacing the package name alone does not migrate an application between them. Before copying an example into an existing integration:

Check the installed package and version in your lockfile or package metadata.
Check the client’s resource method and request shape against its version’s types or source.
Confirm the API host and authentication in the API directory.
Make one read request before implementing resource creation or retries.

For example, the embedded Node binding uses customerId and items in orders.createExact; a REST API may use different field names. Copy the contract for the interface you are calling.

Troubleshooting

Symptom	What to check
Node engine-version warning	The terminal’s `node --version` and `npm --version` meet the selected release’s requirements
Cannot load the native module	Optional dependencies are enabled, and installation ran on the target OS/architecture
Python install starts compiling Rust	pip could not use a compatible wheel; use `--only-binary=:all:` to check wheel availability explicitly
Python cannot import `stateset_embedded`	Use the same virtual-environment interpreter for pip and for the script
`ensurepip` or `venv` is unavailable	Install virtual-environment support for the selected Python interpreter
Data disappears after exit	`:memory:` is temporary; use a file path for persistent data
Existing data is missing	Relative database paths resolve from the process’s working directory
A REST call returns `401`	Verify the service host, header and key; reinstalling an SDK does not change authentication

Include the package version, runtime version, OS, CPU architecture and full redacted loader or HTTP error when asking for help.

Next steps

The customer quickstart covers identity reuse, profile updates, and addresses. The integration testing guide turns commerce behavior into an executable suite you can run in CI. Continue with the inventory quickstart for explicit stock holds, or the payment and refund quickstart for local financial records and retry behavior. Both contain complete programs with assertions and expected output.

Create a persisted order

Verify customer creation, decimal-string totals and persistence.

Manage stock and cancellation

Reserve stock, reject an oversized order and verify cancellation releases the reservation.

Connect an AI agent

Point an MCP host at your database and verify its first tool call.

Language bindings

Compare language surfaces and money representations.

Overview

Quickstarts

End-to-end

Commerce Workflows

Order Management

Returns & Warranties

Supply Chain

Agent Development

Knowledge & RAG

Response Features

Advanced Features

Integrations

Commerce Network

Self-Hosted

Best Practices

E-commerce Workflows

SDK Installation and Setup

Choose a package

Node.js SDK

Check your runtime

Install

Verify the installation

Python SDK

Check your runtime

Create an environment and install

Verify the installation

Hosted API integrations

Existing REST SDK integrations

Troubleshooting

Next steps

Create a persisted order

Manage stock and cancellation

Connect an AI agent

Language bindings

​Choose a package

​Node.js SDK

​Check your runtime

​Install

​Verify the installation

​Python SDK

​Check your runtime

​Create an environment and install

​Verify the installation

​Hosted API integrations

​Existing REST SDK integrations

​Troubleshooting

​Next steps

Create a persisted order

Manage stock and cancellation

Connect an AI agent

Language bindings

Choose a package

Node.js SDK

Check your runtime

Install

Verify the installation

Python SDK

Check your runtime

Create an environment and install

Verify the installation

Hosted API integrations

Existing REST SDK integrations

Troubleshooting

Next steps