> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Inventory Lifecycle

> Node.js method signatures for inventory creation, stock reads, reservation confirmation and release, and counted adjustments.

This reference describes **`@stateset/embedded` 1.35.1**. For a complete executable program
with stock assertions, start with the [inventory quickstart](/guides/inventory-quickstart).

## Create an item and read stock

```javascript theme={null}
import { Commerce } from '@stateset/embedded';
const commerce = new Commerce(':memory:');

await commerce.inventory.createItem({
  sku: 'MUG-001',
  name: 'Ceramic mug',
  initialQuantity: 10,
});
const stock = await commerce.inventory.getStock('MUG-001');
console.log(stock.totalOnHand, stock.totalAllocated, stock.totalAvailable);
// 10 0 10 (each value is a string)
```

`getStock(sku)` returns `null` when there is no matching item. Check for that result before
reading quantities in application code.

## Reserve, then confirm or release

The reservation API uses positional arguments:

```javascript theme={null}
const reservation = await commerce.inventory.reserve(
  'MUG-001',       // SKU
  2,               // quantity
  'checkout',      // reference type
  'checkout-001',   // your workflow's reference ID
  300,             // optional expiration in seconds
);
```

Save `reservation.id`. Choose the next action based on the workflow outcome:

| Intent | Call | Stock effect |
| - | - | - |
| Accept the pending hold | `await commerce.inventory.confirmReservation(reservation.id)` | Keeps the allocation and on-hand stock unchanged |
| Abandon the hold | `await commerce.inventory.releaseReservation(reservation.id)` | Releases the allocation, restoring availability |

These are separate outcomes, not two consecutive steps in a successful checkout. Confirmation
records acceptance of a reservation; it is not a stock-consumption operation.

### Expiration and retries

The optional fifth argument sets an expiration timestamp. Omitting it creates a hold without
that timestamp. Expiration is checked by engine operations; do not assume the Node process
runs a background timer that releases every expired hold at the deadline.

Confirm before the deadline and handle an expired-reservation error as a failed confirmation.
Reconcile the current checkout state before attempting another hold. Explicitly release known
abandoned holds instead of relying on elapsed time alone.

A payment-provider timeout leaves the external outcome uncertain. Reconcile that provider's
result before releasing or replacing stock; a generic catch block cannot distinguish a
confirmed decline from a charge whose response was lost.

## Adjustments

For a counted correction or damage, use a signed quantity delta:

```javascript theme={null}
await commerce.inventory.adjust('MUG-001', -1, 'Damaged during stock count');
```

The method takes `(sku, quantityDelta, reason)`. It adjusts on-hand stock; it does not confirm
or release a reservation. Read `getStock` afterward to verify the resulting quantities.

## Order and return integration

| Operation | Observed behavior in the Node 1.35.1 walkthroughs |
| - | - |
| Create an order with `reject_if_insufficient` | Reserves the order's stock, or rejects the request if insufficient |
| Cancel that order | Releases its allocation |
| Confirm a manual reservation | Keeps the allocation; does not consume stock |
| Mark a return received | Records return state; do not assume an automatic restock |

The [orders quickstart](/guides/orders-quickstart) verifies creation and cancellation. Avoid
reserving the same units manually as well. The
[returns workflow](/stateset-icommerce/stateset-icommerce-returns-workflow) explains the
published binding's disposition limitation before completion.

## Related

* [Inventory quickstart](/guides/inventory-quickstart)
* [Order lifecycle](/stateset-icommerce/stateset-icommerce-order-lifecycle)
* [Payment and refund records](/guides/payments-quickstart)
* [Finance and accounting](/stateset-icommerce/stateset-icommerce-finance#cycle-counts)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.