Inventory API

REST API endpoints for viewing and adjusting product stock levels.

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

Response

{
  "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
  }
}

# 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

# 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

{
  "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.