Inventory API

Overview

The Inventory API provides access to stock levels across all warehouses and supports programmatic inventory adjustments. All endpoints require the inventory:read or inventory:write scope.

Endpoints

List Inventory

GET /api/inventory

Query Parameters:

Parameter	Type	Description
limit	integer	Results per page (default: 50, max: 200)
cursor	string	Pagination cursor
status	string	Filter: `normal`, `low`, `critical`, `out_of_stock`
warehouse_id	string	Filter to a specific warehouse
sku	string	Filter to a specific SKU

Example Response:

{
  "data": [
    {
      "sku": "SKU-001",
      "title": "Blue Widget 500ml",
      "total_on_hand": 487,
      "total_reserved": 23,
      "total_available": 449,
      "safety_stock": 15,
      "status": "normal",
      "warehouses": [
        {
          "warehouse_id": "wh_01HX...",
          "name": "Warehouse A",
          "on_hand": 350,
          "reserved": 18,
          "available": 317
        },
        {
          "warehouse_id": "wh_01HY...",
          "name": "FBA EU",
          "on_hand": 137,
          "reserved": 5,
          "available": 132,
          "type": "FBA"
        }
      ]
    }
  ],
  "meta": {"total": 1248, "limit": 50, "nextCursor": "cursor_abc123"}
}

Get Inventory for SKU

GET /api/inventory/:sku

Returns detailed inventory data for a single SKU.

Update Inventory

PUT /api/inventory/:sku

Required scope: inventory:write

Set the stock level for a SKU in a specific warehouse.

Request Body:

{
  "warehouse_id": "wh_01HX...",
  "quantity": 500,
  "reason": "supplier_receipt",
  "note": "PO-2026-0312 received"
}

Response: HTTP 200 with the updated inventory record.

Bulk Inventory Update

POST /api/inventory/bulk

Required scope: inventory:write

Update stock for multiple SKUs at once. Maximum 500 updates per request.

Request Body:

{
  "updates": [
    {
      "sku": "SKU-001",
      "warehouse_id": "wh_01HX...",
      "quantity": 500,
      "reason": "supplier_receipt"
    },
    {
      "sku": "SKU-002",
      "warehouse_id": "wh_01HX...",
      "quantity": 200,
      "reason": "cycle_count"
    }
  ]
}

List Warehouses

GET /api/inventory/warehouses

Returns all configured warehouses for the tenant.

Example Response:

{
  "data": [
    {
      "id": "wh_01HX...",
      "name": "Warehouse A",
      "address": "Industriestraße 1, 12345 Berlin, DE",
      "type": "own",
      "is_active": true
    },
    {
      "id": "wh_01HY...",
      "name": "FBA EU",
      "type": "FBA",
      "marketplace": "amazon_eu",
      "is_active": true,
      "is_readonly": true
    }
  ]
}

Get Adjustment History

GET /api/inventory/:sku/adjustments

Returns all stock adjustments for a SKU.

Query Parameters: start_date, end_date, warehouse_id, reason

Example Response:

{
  "data": [
    {
      "id": "adj_01HX...",
      "sku": "SKU-001",
      "warehouse_id": "wh_01HX...",
      "before_quantity": 450,
      "after_quantity": 500,
      "delta": 50,
      "reason": "supplier_receipt",
      "note": "PO-2026-0312 received",
      "created_by": "[email protected]",
      "created_at": "2026-03-12T14:00:00.000Z"
    }
  ]
}

Error Codes

Code	HTTP Status	Description
`INVENTORY_NOT_FOUND`	404	SKU has no inventory record
`WAREHOUSE_NOT_FOUND`	404	Warehouse ID does not exist
`READONLY_WAREHOUSE`	403	FBA/FBS warehouses are read-only
`NEGATIVE_QUANTITY`	422	Resulting quantity would be negative

On this page