Commerce Inventory Skill

Domain knowledge for inventory management, stock tracking, and reservation systems.

Inventory Concepts

Stock Quantities

Key Formula

Available = On-Hand - Allocated

Example

On-Hand:    100 units (physical inventory)
Allocated:   25 units (reserved for orders)
Available:   75 units (can be sold)

Inventory Item Structure

{
  id: "uuid",
  sku: "WIDGET-001",
  name: "Premium Widget",
  description: "High quality widget",

  // Quantities
  totalOnHand: 100,
  totalAllocated: 25,
  totalAvailable: 75,

  // Thresholds
  reorderPoint: 20,
  reorderQuantity: 50,

  // Location breakdown
  locations: [
    { locationId: "warehouse-1", onHand: 60, allocated: 15 },
    { locationId: "warehouse-2", onHand: 40, allocated: 10 }
  ],

  createdAt: "2024-01-15T10:30:00Z",
  updatedAt: "2024-01-15T12:00:00Z"
}

Inventory Operations

Adjustments

Always document reason:

• "Received shipment PO-12345"
• "Damaged in warehouse - 3 units"
• "Cycle count correction"
• "Promotional giveaway"

Reservations

Reservation lifecycle:

[Available] ──► [Reserved] ──► [Confirmed] (deducted)
                    │
                    └──────────► [Released] (returned)

Reservation Structure

{
  id: "uuid",
  sku: "WIDGET-001",
  quantity: 5,

  referenceType: "order",
  referenceId: "order-uuid",

  status: "pending",  // pending, confirmed, released, expired

  expiresAt: "2024-01-15T11:00:00Z",
  createdAt: "2024-01-15T10:45:00Z"
}

Transaction Types

Stock Level Alerts

Common Workflows

Receive Inventory

1. get_stock(sku) - Check current levels
2. adjust_inventory(sku, +quantity, "Received PO-12345")
3. Verify new levels

Order Fulfillment

1. reserve_inventory(sku, qty, "order", orderId)
2. [Process order...]
3. confirm_reservation(reservationId)
   OR
   release_reservation(reservationId) if cancelled

Cycle Count

1. get_stock(sku) - Get system count
2. Physical count
3. If different:
   adjust_inventory(sku, difference, "Cycle count correction")

Write Off Damaged

1. get_stock(sku) - Check current
2. adjust_inventory(sku, -damaged, "Damaged - [details]")
3. Document with photos (external)

Multi-Location Inventory

When using multiple warehouses:

// Total stock
totalOnHand: 100

// By location
locations: [
  { locationId: "east", onHand: 60 },
  { locationId: "west", onHand: 40 }
]

Operations can specify location:

• Reserve from specific location
• Adjust specific location
• Transfer between locations

Reservation Expiration

Default: 15 minutes (900 seconds)

Expired reservations:

• Automatically released
• Stock returns to available
• Associated order may need attention

Custom expiration:

reserve_inventory({
  sku: "WIDGET-001",
  quantity: 5,
  referenceType: "order",
  referenceId: "uuid",
  expiresInSeconds: 3600  // 1 hour
})

Common Errors

Best Practices

1. Always check before adjust - View current levels first
2. Document all changes - Include reason in every adjustment
3. Use reservations - Don't directly deduct for orders
4. Monitor reorder points - Set appropriate thresholds
5. Regular cycle counts - Verify physical vs system
6. Handle expiration - Clean up expired reservations