The Inventory API provides stock-level visibility and adjustment for product variants that have SKUs assigned.

## List Inventory

```
GET /api/v1/inventory
```

Returns inventory levels for all variants with SKUs. Uses cursor-based pagination.

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | `number` | 50 | Items per page (1-100) |
| `cursor` | `string` | – | Variant UUID cursor for pagination |
| `lowStock` | `number` | – | Filter variants with stock below this threshold |

### Response

```json
{
  "items": [
    {
      "sku": "CT-SM-BLK",
      "onHand": 42,
      "reserved": 0,
      "available": 42
    },
    {
      "sku": "CT-LG-RED",
      "onHand": 3,
      "reserved": 0,
      "available": 3
    }
  ],
  "pagination": {
    "cursor": "0191abc0-0000-7000-8000-000000000200",
    "hasMore": true
  }
}
```

```bash
# List low stock items (below 10 units)
curl -H "Authorization: Bearer your_api_key" \
  "https://your-store.yns.store/api/v1/inventory?lowStock=10"
```

---

## Adjust Inventory

```
POST /api/v1/inventory/:sku/adjust
```

Adjusts the stock level for a variant by SKU. Use positive `delta` to add stock, negative to subtract.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `delta` | `number` | Yes | Stock change (positive to add, negative to subtract) |
| `reason` | `string` | Yes | `restock`, `correction`, `damaged`, or `return` |

```bash
# Restock 50 units
curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"delta": 50, "reason": "restock"}' \
  https://your-store.yns.store/api/v1/inventory/CT-SM-BLK/adjust

# Remove 3 damaged units
curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"delta": -3, "reason": "damaged"}' \
  https://your-store.yns.store/api/v1/inventory/CT-SM-BLK/adjust
```

### Response

```json
{
  "sku": "CT-SM-BLK",
  "previousStock": 42,
  "newStock": 92,
  "delta": 50,
  "reason": "restock"
}
```

### Side Effects

When an adjustment brings a variant from zero stock to a positive level, back-in-stock notification emails are automatically sent to any customers who subscribed for restock alerts on that variant (if the store has restock notifications enabled). When stock is depleted to zero, notification watches are re-armed so subscribers will be notified again on the next restock.

These side effects are asynchronous and do not affect the API response or status code.