Inventory Module

The Inventory module tracks stock levels across multiple locations with automatic reservation on order confirmation and release on cancellation.

Key Concepts

Inventory Item -- a stock record for a specific variant at a specific location

Location -- a physical warehouse or fulfillment center

Reservation -- a hold placed on stock when an order is confirmed, preventing overselling

Stock Level -- the available quantity after accounting for reservations

Data Model

{
  "variantId": "var_abc",
  "locationId": "loc_sf",
  "quantity": 100,
  "reserved": 12,
  "available": 88,
  "trackInventory": true,
  "allowBackorder": false,
  "lowStockThreshold": 10
}

API Examples

Get Stock for a Variant

curl "https://api.hanzo.ai/inventory/var_abc" \
  -H "Authorization: Bearer $TOKEN"

const stock = await commerce.inventory.get('var_abc')
console.log(`Available: ${stock.available}`)

stock, err := client.Inventory.Get(ctx, "var_abc")
fmt.Printf("Available: %d\n", stock.Available)

Adjust Stock

curl -X POST https://api.hanzo.ai/inventory/var_abc/adjust \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "locationId": "loc_sf",
    "adjustment": 50,
    "reason": "restock"
  }'

Manage Locations

# Create a location
curl -X POST https://api.hanzo.ai/inventory/location \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "SF Warehouse",
    "code": "loc_sf",
    "address": {
      "line1": "100 Industrial Way",
      "city": "San Francisco",
      "state": "CA",
      "country": "US"
    }
  }'

Bulk Stock Update

curl -X POST https://api.hanzo.ai/inventory/bulk \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"variantId": "var_abc", "locationId": "loc_sf", "quantity": 100},
      {"variantId": "var_def", "locationId": "loc_sf", "quantity": 50},
      {"variantId": "var_ghi", "locationId": "loc_ny", "quantity": 200}
    ]
  }'

Reservation Flow

Order confirmed ──► Reserve stock (available - reserved)
    │
    ├── Order shipped ──► Deduct quantity, release reservation
    │
    └── Order cancelled ──► Release reservation (available + reserved)

Reservations are automatic. When an order is confirmed, the Inventory module listens for the order.confirmed event and creates reservations for each line item.

Configuration

inventory:
  track_by_default: true
  allow_backorder_by_default: false
  low_stock_threshold: 10
  reservation_timeout_hours: 48  # release reservations if order not paid
  multi_location: true
  allocation_strategy: "nearest"  # nearest | priority | round_robin

Events

Event	Description
`inventory.adjusted`	Stock manually adjusted
`inventory.reserved`	Stock reserved for an order
`inventory.released`	Reservation released
`inventory.low`	Stock fell below threshold
`inventory.out_of_stock`	Available quantity reached zero

Use the inventory.low event to trigger automatic reorder notifications or supplier alerts.

On this page