Inventory API

Manage inventory levels, products, and stock movements.

Endpoints

List Inventory

Get inventory for all locations.

GET /api/v1/inventory
Authorization: Bearer {token}

Query Parameters:

Parameter	Type	Description
location_id	string	Filter by location
room_type	string	Filter by room (sales_floor, vault, etc.)
category	string	Filter by product category
low_stock	boolean	Only show low stock items
page	integer	Page number (default: 1)
limit	integer	Items per page (default: 50)

Response:

{
  "data": [
    {
      "id": "inv-uuid",
      "product_id": "prod-uuid",
      "product_name": "Blue Dream 1/8",
      "sku": "BD-EIGHTH-001",
      "location_id": "loc-uuid",
      "room_type": "sales_floor",
      "quantity": 45,
      "reserved_quantity": 5,
      "available_quantity": 40,
      "unit_cost": 25.00,
      "unit_price": 45.00,
      "last_sync": "2026-01-27T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 234
  }
}

Get Inventory Item

GET /api/v1/inventory/{id}

Update Inventory

Adjust inventory levels with reason tracking.

PATCH /api/v1/inventory/{id}
Authorization: Bearer {token}

{
  "quantity_change": -5,
  "reason_code": "SALE",
  "notes": "Regular sale transaction"
}

Reason Codes:

Code	Description
SALE	Retail sale
RETURN	Customer return
ADJUSTMENT	Manual adjustment
DAMAGE	Damaged goods
THEFT	Theft/shrinkage
TRANSFER	Inter-location transfer
AUDIT	Audit correction

Bulk Update

Update multiple inventory items at once.

POST /api/v1/inventory/bulk-update
Authorization: Bearer {token}

{
  "updates": [
    {"id": "inv-uuid-1", "quantity_change": -2, "reason_code": "SALE"},
    {"id": "inv-uuid-2", "quantity_change": 10, "reason_code": "TRANSFER"}
  ]
}

Inventory Sync

Trigger a sync with connected POS system.

POST /api/v1/inventory/sync
Authorization: Bearer {token}

{
  "location_id": "loc-uuid",
  "sync_type": "full"  // or "incremental"
}

Inventory Snapshot

Get a point-in-time inventory snapshot.

GET /api/v1/inventory/snapshot
Authorization: Bearer {token}

Query: ?date=2026-01-27&location_id=loc-uuid

Room Types

Type	Description
sales_floor	Customer-facing inventory
vault	Secure storage
quarantine	Pending inspection
secret_menu	Special/unreleased items

Webhooks

Subscribe to inventory events:

• inventory.updated - When quantity changes
• inventory.low_stock - When below threshold
• inventory.sync.completed - When sync finishes