Inventory Lifecycle

Stock, reservations, and adjustments — the three-step protocol that prevents oversells.

Inventory Lifecycle

Inventory in the embedded engine distinguishes on-hand from available. The gap between them is reservations, and getting that protocol right is what prevents overselling.

Setup

import { Commerce } from '@stateset/embedded';
const commerce = new Commerce('./store.db');

Create an item

await commerce.inventory.createItem({
  sku: 'SHOE-RED-10',
  quantity: 250,
  location: 'WH-1',
});

Read stock

const stock = await commerce.inventory.getStock('SHOE-RED-10');

Reservations: the three-step protocol

This is the part worth understanding properly.

// 1. Hold the stock
const reservation = await commerce.inventory.reserve({
  sku: 'SHOE-RED-10',
  quantity: 1,
  orderId: 'ord_9412',
});

// 2a. The order went through
await commerce.inventory.confirmReservation(reservation.id);

// 2b. Or it didn't
await commerce.inventory.releaseReservation(reservation.id);

A reservation that is never confirmed or released holds stock indefinitely. It will not time out on its own.

Wrap it so both outcomes are covered, including on the error path:

const reservation = await commerce.inventory.reserve({ … });
try {
  await authorizePayment();
  await commerce.inventory.confirmReservation(reservation.id);
} catch (err) {
  await commerce.inventory.releaseReservation(reservation.id);
  throw err;
}

Why reserve at all

Without a reservation, two concurrent checkouts both read available stock as 1 and both succeed. Reserving makes the read-and-hold atomic, so the second checkout sees 0.

Order the calls as reserve → authorise → confirm. Reserving first closes the race; confirming last means a declined card releases the stock rather than stranding it.

Adjustments

For counted corrections, damage, and shrinkage:

await commerce.inventory.adjust({
  sku: 'SHOE-RED-10',
  quantityDelta: -3,
  reason: 'damaged in transit',
});

Adjustments are recorded as movements with an audit trail, not as a silent overwrite of a quantity — so a later discrepancy can be traced to the adjustment that caused it.

Cycle counts

For a systematic recount rather than a one-off correction, use the cycle-count workflow — draft → in-progress → completed, with variance applied transactionally to location inventory and a cycle_count movement record written. See Finance & Accounting.

Where reservations come from

Trigger	Effect
Order created	Reserve against the line items
Payment authorised	Confirm the reservation
Order cancelled	Release the reservation
Return received	Restock, if the disposition allows

Related

• Order Lifecycle
• Returns Workflow
• Finance & Accounting — cycle counts and valuation