StateSet API Docs

This reference describes the @stateset/embedded 1.35.1 Node binding. For a complete program with setup and assertions, use the orders quickstart. REST APIs and other language bindings have their own signatures.

Setup

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

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

The file path determines which local database you operate. Use :memory: for a disposable example, or the same absolute file path across processes for persistent data.

Create an order with actual IDs

orders.createExact takes a customer ID and an items array. Each item needs a SKU, name, quantity and decimal-string price. In this snippet, customer is the result of commerce.customers.create or findOrCreate, and inventory for MUG-001 already exists:

const order = await commerce.orders.createExact({
  customerId: customer.id,
  currency: 'USD',
  stockPolicy: 'reject_if_insufficient',
  items: [
    { sku: 'MUG-001', name: 'Ceramic mug', quantity: 2, unitPrice: '12.50' },
  ],
});

The result includes id, status, items and totalAmountExact. New orders begin in pending. Store the returned order ID rather than a sample identifier from documentation.

Stock reservations

Order creation reserves available inventory for its lines. With reject_if_insufficient, an order that cannot be fully reserved is rejected. The orders quickstart checks ten units on hand → two allocated → eight available, then verifies that cancellation releases the allocation.

const stock = await commerce.inventory.getStock('MUG-001');
console.log(stock.totalOnHand, stock.totalAllocated, stock.totalAvailable);

Do not add a second manual reservation for quantities already reserved by order creation. Explicit inventory reservations are a separate API; its Node signature is reserve(sku, quantity, referenceType, referenceId, expiresInSeconds?).

State changes

Operation	Node method	What to inspect
Confirm	`orders.updateStatus(id, 'confirmed')`	Returned `status`
Begin processing	`orders.updateStatus(id, 'processing')`	Returned `status`
Record shipping	`orders.ship(id, trackingNumber)`	Returned `status` and `trackingNumber`
Cancel an eligible order	`orders.cancel(id)`	Returned `status` and released stock allocations
Read current state	`orders.get(id)`	The current record, or `null` if absent

For example, while order is still pending:

const confirmed = await commerce.orders.updateStatus(order.id, 'confirmed');
const shipped = await commerce.orders.ship(confirmed.id, 'DEMO-TRACK-001');
console.log(shipped.status, shipped.trackingNumber);

ship takes a tracking-number string, not an object containing carrier settings. In a real integration, pass the tracking number returned by your carrier workflow. The demonstration string above only labels a local record.

In a check against version 1.35.1, orders.ship changed the order to shipped while the inventory allocation remained unchanged. Do not assume the status helper consumes a reservation or implements the full warehouse fulfillment flow. Verify stock and shipment records through the fulfillment integration you use.

Cancellation and returns

The orders quickstart demonstrates pending → confirmed → cancelled and checks that the reserved stock becomes available again. State guards can reject a cancellation based on the current order and payment state. For shipped goods, follow the returns quickstart. A return refers to the order’s line-item IDs and has its own approval, receipt and disposition process.

Reading state

const current = await commerce.orders.get(order.id);
const orders = await commerce.orders.list();
const count = await commerce.orders.count();

In this binding, list() takes no pagination options. A REST list endpoint can have a different pagination contract; consult that endpoint instead of transferring its parameters to the embedded method.

External effects

Track commerce records and external operations separately:

A local payment record does not prove that a payment provider captured funds.
A tracking number stored on an order does not buy a shipping label.
A shipped status does not prove warehouse stock was consumed.
A return status does not prove a customer refund succeeded.

Use the external system’s identifiers and results when reconciling the workflow. For a multi-service integration, start with Sync and durable workflows.

Orders quickstart — complete local reservation and cancellation example
Embedded quickstart — persistence and exact-money setup
Returns workflow — RMA methods and limits
Inventory lifecycle — inventory concepts

Last modified on September 20, 2026

Get started

Build your first integration

Operate and improve

Resources and support

Platform

Using the APIs

StateSet Response

StateSet ResponseCX

Temporal Engine

StateSet iCommerce Engine

StateSet iCommerce EDI Engine

StateSet Mail

StateSet iCommerce Voice Engine

StateSet iCommerce NSR Engine

AI Agents

StateSet Agents

StateSet iCommerce Sandbox Engine

StateSet ACP

StateSet UCP

StateSet ICP

StateSet Sequencer

StateSet Set L2

StateSet Cloud

Apps & Consoles

Tools

Order Lifecycle

Setup

Create an order with actual IDs

Stock reservations

State changes

Cancellation and returns

Reading state

External effects

​Setup

​Create an order with actual IDs

​Stock reservations

​State changes

​Cancellation and returns

​Reading state

​External effects

​Related

Setup

Create an order with actual IDs

Stock reservations

State changes

Cancellation and returns

Reading state

External effects

Related