Katixo/API DocumentationBeta

Stock Counts

Perform physical stock counts to reconcile book quantities against actual stock on hand. When a stock count is posted, the system automatically creates stock adjustment movements for any variances found.

Endpoints

GET/api/v1/stock-counts

GET/api/v1/stock-counts/{id}

POST/api/v1/stock-counts

POST/api/v1/stock-counts/{id}/post

List stock counts

GET/api/v1/stock-counts

Returns a paginated list of stock counts. Use standard page, size, and sort parameters for pagination.

Roles: OWNER, ADMIN, ACCOUNTANT, OPERATOR, VIEWER.

Create a stock count

POST/api/v1/stock-counts

Creates a new stock count in DRAFT status. Returns 201 Created. The system automatically calculates the expected quantity (book stock) and variance for each line item.

curl -X POST https://api.katixo.com/api/v1/stock-counts \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "warehouseId": "d4e5f6a7-b8c9-0123-4567-89abcdef0123",
    "countDate": "2026-06-11",
    "notes": "Monthly physical count — June 2026",
    "lines": [
      {
        "itemId": "550e8400-e29b-41d4-a716-446655440000",
        "countedQuantity": 225,
        "notes": "5 units damaged, set aside"
      },
      {
        "itemId": "661f9500-f3ac-52e5-b827-557766551111",
        "countedQuantity": 48
      }
    ]
  }'

Request body

Field	Type	Required	Description
`warehouseId`	UUID	Yes	Warehouse to count stock in.
`lines`	array	Yes	Line items with counted quantities.
`countDate`	date	No	Date of the physical count. Defaults to today.
`notes`	string	No	Free-text notes about this count session.

Line item fields

Field	Type	Description
`itemId`	UUID	Required. The item being counted.
`countedQuantity`	decimal	Required. Physical count quantity.
`notes`	string	Optional notes for this line (e.g., "damaged").

Post a stock count

POST/api/v1/stock-counts/{id}/post

Finalizes the stock count and applies variance adjustments. For each line where the counted quantity differs from the expected (book) quantity, the system creates a stock adjustment movement to bring book stock in line with the physical count. Requires OWNER, ADMIN, or ACCOUNTANT role.

The StockCount object

{
  "id": "e5f6a7b8-c9d0-1234-5678-9abcdef01234",
  "countNumber": "SC-2026-0012",
  "warehouseId": "d4e5f6a7-b8c9-0123-4567-89abcdef0123",
  "warehouseName": "Main Store",
  "countDate": "2026-06-11",
  "status": "POSTED",
  "notes": "Monthly physical count — June 2026",
  "postedAt": "2026-06-11T15:30:00Z",
  "lineCount": 2,
  "varianceCount": 1,
  "lines": [
    {
      "id": "f6a7b8c9-d0e1-2345-6789-abcdef012345",
      "itemId": "550e8400-e29b-41d4-a716-446655440000",
      "itemName": "Toor Dal 1kg",
      "sku": "TD-1KG-001",
      "expectedQuantity": 230.00,
      "countedQuantity": 225.00,
      "variance": -5.00,
      "notes": "5 units damaged, set aside"
    },
    {
      "id": "a7b8c9d0-e1f2-3456-789a-bcdef0123456",
      "itemId": "661f9500-f3ac-52e5-b827-557766551111",
      "itemName": "Basmati Rice 5kg",
      "sku": "BR-5KG-P01",
      "expectedQuantity": 48.00,
      "countedQuantity": 48.00,
      "variance": 0.00,
      "notes": null
    }
  ],
  "createdAt": "2026-06-11T14:00:00Z"
}