Katixo/API DocumentationBeta

Batches & Stock

Query batch-level stock for items with batch tracking enabled. Track expiry dates, find near-expiry stock, and check available quantities per batch. Batch tracking requires the BATCH_EXPIRY module to be enabled for your organization.

Endpoints

GET/api/v1/batches/item/{itemId}

GET/api/v1/batches/item/{itemId}/available

GET/api/v1/batches/near-expiry

Get batches by item

GET/api/v1/batches/item/{itemId}

Returns all batches for a specific item, including batch number, manufacturing date, expiry date, and current quantity on hand.

Path parameters

Parameter	Type	Description
`itemId`	UUID	The item to query batches for.

curl https://api.katixo.com/api/v1/batches/item/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "success": true,
  "message": "Batches retrieved",
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "batchNumber": "PCM-2026-A01",
      "itemId": "550e8400-e29b-41d4-a716-446655440000",
      "itemName": "Paracetamol 500mg",
      "manufacturingDate": "2026-01-15",
      "expiryDate": "2028-01-14",
      "quantityOnHand": 500.00,
      "purchaseRate": 1.20,
      "warehouseId": "d4e5f6a7-b8c9-0123-4567-89abcdef0123",
      "warehouseName": "Main Store"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "batchNumber": "PCM-2025-K12",
      "itemId": "550e8400-e29b-41d4-a716-446655440000",
      "itemName": "Paracetamol 500mg",
      "manufacturingDate": "2025-11-01",
      "expiryDate": "2027-10-31",
      "quantityOnHand": 120.00,
      "purchaseRate": 1.15,
      "warehouseId": "d4e5f6a7-b8c9-0123-4567-89abcdef0123",
      "warehouseName": "Main Store"
    }
  ],
  "errors": null
}

Available batches

GET/api/v1/batches/item/{itemId}/available

Returns only batches with available stock (quantity > 0) and not expired. Useful for billing workflows where you need to select a batch to sell from. Results are sorted by expiry date (FEFO — First Expiry, First Out).

curl https://api.katixo.com/api/v1/batches/item/550e8400-...440000/available \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Near-expiry batches

GET/api/v1/batches/near-expiry

Returns all batches across all items that are approaching their expiry date. The near-expiry threshold is configurable per organization (default: 90 days).

Query parameters

Parameter	Type	Description
`page`	int	Page number (0-indexed). Default: 0.
`size`	int	Page size. Default: 20.
`sort`	string	Sort field and direction (e.g., `expiryDate,asc`).

curl "https://api.katixo.com/api/v1/batches/near-expiry?size=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "success": true,
  "message": "Near-expiry batches retrieved",
  "data": {
    "content": [
      {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "batchNumber": "PCM-2025-K12",
        "itemId": "550e8400-e29b-41d4-a716-446655440000",
        "itemName": "Paracetamol 500mg",
        "expiryDate": "2027-10-31",
        "daysToExpiry": 45,
        "quantityOnHand": 120.00,
        "warehouseName": "Main Store"
      }
    ],
    "page": 0,
    "size": 10,
    "totalElements": 8,
    "totalPages": 1,
    "last": true
  },
  "errors": null
}

Use this endpoint to proactively identify stock that needs to be sold, returned, or written off before expiry. Particularly important for pharmacy and FMCG businesses.

Authorization

All batch endpoints require at minimum the VIEWER role. The BATCH_EXPIRY module must be enabled for the organization, and individual items must have trackBatches: true.