Katixo/API DocumentationBeta

Items

Items represent products, services, and composite goods in your Katixo catalog. Each item carries its HSN/SAC code, GST rate, unit of measurement, pricing, and optional pharmacy fields — so invoices and inventory are computed correctly without manual entry at billing time.

Module gate: All item endpoints require the INVENTORY module to be enabled for your organization (@RequiresModule(INVENTORY)).

Endpoints

GET/api/v1/itemsall roles

GET/api/v1/items/{id}all roles

POST/api/v1/items201 Created

PUT/api/v1/items/{id}

DELETE/api/v1/items/{id}

GET/api/v1/items/import/templatetext/csv

POST/api/v1/items/importmultipart

POST/api/v1/items/{id}/bom

DELETE/api/v1/items/bom/{componentId}

Authentication

All requests require a JWT Bearer token in the Authorization header. See the Authentication guide for details on obtaining tokens.

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Response envelope

Every response is wrapped in an ApiResponse<T> envelope:

{
  "success": true,
  "message": "Item created successfully",
  "data": { ... },
  "errors": null
}

ItemType enum

GOODSSERVICECOMPOSITE

COMPOSITE items have a Bill of Materials (BOM) — see the BOM endpoints below.

The ItemResponse object

{
  "id": "d4f7a1b2-9c3e-4f8a-b6d5-1e2f3a4b5c6d",
  "sku": "TD-1KG-001",
  "barcode": "8901234567890",
  "name": "Toor Dal",
  "description": "Premium unpolished toor dal, sourced from Latur, Maharashtra",
  "itemType": "GOODS",
  "category": "Pulses",
  "brand": "Laxmi Bhog",
  "manufacturer": "Laxmi Foods Pvt Ltd",
  "hsnCode": "07139090",
  "unitOfMeasure": "KG",
  "purchasePrice": 110.00,
  "salePrice": 145.00,
  "mrp": 160.00,
  "gstRate": 5.00,
  "trackInventory": true,
  "trackBatches": false,
  "reorderLevel": 50,
  "reorderQuantity": 200,
  "preferredVendorId": "a1b2c3d4-5678-9abc-def0-123456789abc",
  "preferredVendorName": "Maharashtra Pulses Trading Co.",
  "active": true,
  "totalOnHand": 230.00,
  "createdAt": "2026-01-15T03:30:00Z",
  "secondaryUnits": [
    {
      "uomAbbreviation": "BAG",
      "conversionFactor": 25.0,
      "customPrice": 2750.00
    }
  ]
}

Key fields

Field	Type	Description
`id`	UUID	Unique identifier for the item.
`sku`	string	Stock keeping unit. Required, max 50 characters, must be unique.
`itemType`	ItemType	One of `GOODS`, `SERVICE`, or `COMPOSITE`.
`hsnCode`	string	HSN code (goods) or SAC code (services) for GST classification.
`gstRate`	BigDecimal	GST rate as a percentage (e.g., `5.00`, `12.00`, `18.00`). Min 0.00.
`unitOfMeasure`	string	Primary unit of measurement (e.g., KG, PCS, LTR, BOX).
`trackInventory`	boolean	When true, sales and purchases automatically adjust stock levels.
`trackBatches`	boolean	Enable batch-wise stock tracking (required for pharmaceuticals).
`totalOnHand`	BigDecimal	Current total stock on hand across all warehouses.
`secondaryUnits`	List<UnitPriceInfo>	Alternate units with conversion factors and optional custom prices.
`preferredVendorId`	UUID	Preferred supplier for reorder suggestions.

List items

GET/api/v1/items

OWNERADMINACCOUNTANTOPERATORVIEWER

Query parameters

Parameter	Type	Description
`search`	string	Search by name, SKU, or barcode.
`activeOnly`	boolean	When `true`, returns only active items.
`page`	integer	Page number (zero-based). Default: 0.
`size`	integer	Page size. Default: 20.
`sort`	string	Sort field and direction (e.g., `name,asc` or `createdAt,desc`).

curl "https://api.katixo.com/api/v1/items?search=paracetamol&activeOnly=true&page=0&size=10&sort=name,asc" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Paginated response

Returns ApiResponse<PagedResponse<ItemResponse>>:

{
  "success": true,
  "message": "Items retrieved successfully",
  "data": {
    "content": [
      {
        "id": "d4f7a1b2-9c3e-4f8a-b6d5-1e2f3a4b5c6d",
        "sku": "PARA-500-STRIP",
        "name": "Paracetamol 500mg Strip",
        "itemType": "GOODS",
        "hsnCode": "30049099",
        "salePrice": 32.50,
        "gstRate": 12.00,
        "active": true,
        "totalOnHand": 540.00
      }
    ],
    "page": 0,
    "size": 10,
    "totalElements": 47,
    "totalPages": 5,
    "last": false
  },
  "errors": null
}

Get item by ID

GET/api/v1/items/{id}

curl https://api.katixo.com/api/v1/items/d4f7a1b2-9c3e-4f8a-b6d5-1e2f3a4b5c6d \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Returns ApiResponse<ItemResponse> with the full item object including secondaryUnits and vendor details.

Create an item

POST/api/v1/items201 Created

OWNERADMINACCOUNTANTOPERATOR

Send a CreateItemRequest body. Returns 201 Created on success.

curl -X POST https://api.katixo.com/api/v1/items \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "BR-5KG-P01",
    "name": "Basmati Rice Premium",
    "itemType": "GOODS",
    "hsnCode": "10063020",
    "category": "Rice",
    "brand": "Daawat",
    "manufacturer": "LT Foods Ltd",
    "barcode": "8901058853100",
    "unitOfMeasure": "KG",
    "purchasePrice": 220.00,
    "salePrice": 285.00,
    "mrp": 320.00,
    "gstRate": 5.00,
    "trackInventory": true,
    "trackBatches": false,
    "reorderLevel": 100,
    "reorderQuantity": 500,
    "preferredVendorId": "b7d2f8a0-1234-4567-89ab-cdef01234567",
    "secondaryUnits": [
      {
        "uomAbbreviation": "BAG",
        "conversionFactor": 25.0,
        "customPrice": 5500.00
      }
    ],
    "openingStock": 150,
    "purchaseUom": "BAG",
    "purchaseUomConversion": 25.0,
    "purchasePricePerUom": 5200.00
  }'

CreateItemRequest fields

Field	Type	Required	Description
`sku`	string	Yes	Max 50 chars. Must be unique within the organization.
`name`	string	Yes	Max 255 chars. Display name for the item.
`itemType`	ItemType	Yes	`GOODS`, `SERVICE`, or `COMPOSITE`.
`hsnCode`	string	No	HSN (goods) or SAC (services) code.
`category`	string	No	Item category (e.g., Pulses, Electronics, Pharmaceuticals).
`brand`	string	No	Brand or label name.
`barcode`	string	No	EAN-13, UPC, or custom barcode.
`manufacturer`	string	No	Manufacturer or producer name.
`unitOfMeasure`	string	No	Primary UOM (e.g., KG, PCS, LTR, BOX, STRIP).
`purchasePrice`	BigDecimal	No	Default purchase price per primary unit.
`salePrice`	BigDecimal	No	Default sale price per primary unit.
`mrp`	BigDecimal	No	Maximum retail price (for labeling compliance).
`gstRate`	BigDecimal	No	GST rate as percentage. Min `0.00`.
`trackInventory`	boolean	No	Auto-adjust stock on sales/purchases.
`trackBatches`	boolean	No	Batch-wise tracking (batch number + expiry).
`reorderLevel`	number	No	Low-stock alert threshold.
`reorderQuantity`	number	No	Suggested quantity for purchase orders.
`preferredVendorId`	UUID	No	Preferred vendor for reorder suggestions.
`secondaryUnits`	List<UnitPriceEntry>	No	Alternate units. Each entry has `uomAbbreviation`, `conversionFactor`, and optional `customPrice`.
`purchaseUom`	string	No	Purchase unit (e.g., BAG, CASE, DRUM).
`purchaseUomConversion`	BigDecimal	No	How many primary units in one purchase unit (e.g., 1 BAG = 25 KG).
`purchasePricePerUom`	BigDecimal	No	Price per purchase unit.
`openingStock`	number	No	Initial stock quantity when creating the item.
`openingBatchNumber`	string	No	Batch number for opening stock (if batch tracking is enabled).
`openingExpiryDate`	date	No	Expiry date for the opening stock batch.

Pharmacy fields

Optional fields for pharmaceutical items:

Field	Type	Description
`drugSchedule`	string	Drug schedule (e.g., H, H1, X, G).
`composition`	string	Active ingredient composition (e.g., "Paracetamol 500mg").
`dosageForm`	string	Form (e.g., Tablet, Syrup, Capsule, Injection).
`packSize`	string	Pack size (e.g., "10 tablets/strip", "100ml bottle").
`prescriptionRequired`	boolean	Whether the item requires a prescription for sale.

Example: Pharmacy item

curl -X POST https://api.katixo.com/api/v1/items \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "AMOX-500-10S",
    "name": "Amoxicillin 500mg Capsule (10s)",
    "itemType": "GOODS",
    "hsnCode": "30041090",
    "category": "Antibiotics",
    "brand": "Cipla",
    "manufacturer": "Cipla Ltd",
    "unitOfMeasure": "STRIP",
    "purchasePrice": 42.00,
    "salePrice": 58.50,
    "mrp": 65.00,
    "gstRate": 12.00,
    "trackInventory": true,
    "trackBatches": true,
    "reorderLevel": 30,
    "reorderQuantity": 100,
    "drugSchedule": "H",
    "composition": "Amoxicillin Trihydrate IP 500mg",
    "dosageForm": "Capsule",
    "packSize": "10 capsules/strip",
    "prescriptionRequired": true,
    "openingStock": 75,
    "openingBatchNumber": "CIP-AMX-2607A",
    "openingExpiryDate": "2027-06-30"
  }'

Update an item

PUT/api/v1/items/{id}

OWNERADMINACCOUNTANTOPERATOR

Send an UpdateItemRequest body. Fields not included in the request remain unchanged.

curl -X PUT https://api.katixo.com/api/v1/items/d4f7a1b2-9c3e-4f8a-b6d5-1e2f3a4b5c6d \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "salePrice": 295.00,
    "mrp": 330.00,
    "reorderLevel": 150
  }'

Delete an item

DELETE/api/v1/items/{id}

OWNERADMINACCOUNTANT

Soft-deletes an item. The item becomes inactive and is excluded from default listing.

curl -X DELETE https://api.katixo.com/api/v1/items/d4f7a1b2-9c3e-4f8a-b6d5-1e2f3a4b5c6d \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "success": true,
  "message": "Item deleted successfully",
  "data": null,
  "errors": null
}

CSV import & export

Download CSV template

GET/api/v1/items/import/templatetext/csv

Returns a CSV file with header columns matching the CreateItemRequest fields. Use this as a template to prepare your import file.

curl https://api.katixo.com/api/v1/items/import/template \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -o items_template.csv

Import items from CSV

POST/api/v1/items/importmultipart/form-data

Upload a CSV file as multipart/form-data. Returns an ApiResponse<ItemImportResult>.

curl -X POST https://api.katixo.com/api/v1/items/import \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -F "file=@items_to_import.csv"

{
  "success": true,
  "message": "Import completed",
  "data": {
    "totalRows": 150,
    "created": 142,
    "skipped": 8,
    "successRows": [1, 2, 3, 4, 5],
    "failedRows": [
      { "row": 23, "error": "Duplicate SKU: RCE-BAS-5K" },
      { "row": 87, "error": "Invalid itemType: PRODUCT" }
    ]
  },
  "errors": null
}

Bill of Materials (BOM)

Composite items (itemType: COMPOSITE) can have child components. Use the BOM endpoints to manage the component list for manufacturing or kitting.

Add BOM component

POST/api/v1/items/{id}/bom

Send a BomComponentRequest body:

curl -X POST https://api.katixo.com/api/v1/items/e5a8b3c1-7d2f-4e9a-a1b3-c5d7e9f0a2b4/bom \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "childItemId": "f6b9c4d2-8e3a-5f0b-b2c4-d6e8f0a1b3c5",
    "quantity": 2.50
  }'

Field	Type	Description
`childItemId`	UUID	The ID of the component item to add.
`quantity`	BigDecimal	Quantity of the component required per unit of the composite item.

Delete BOM component

DELETE/api/v1/items/bom/{componentId}

curl -X DELETE https://api.katixo.com/api/v1/items/bom/a1b2c3d4-5678-9abc-def0-112233445566 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Example: Service item

curl -X POST https://api.katixo.com/api/v1/items \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "SVC-AC-INSTALL",
    "name": "AC Installation Service",
    "itemType": "SERVICE",
    "hsnCode": "998719",
    "category": "Services",
    "unitOfMeasure": "NOS",
    "salePrice": 2500.00,
    "gstRate": 18.00,
    "trackInventory": false
  }'

Error responses

Validation errors and business rule violations are returned inside the errors array:

{
  "success": false,
  "message": "Validation failed",
  "data": null,
  "errors": [
    "sku: must not be blank",
    "name: must not be blank",
    "itemType: must not be null",
    "gstRate: must be greater than or equal to 0.00"
  ]
}

Status	Reason
`400`	Validation error (missing required fields, invalid values).
`401`	Missing or invalid JWT Bearer token.
`403`	Insufficient role permissions, or INVENTORY module not enabled.
`404`	Item not found for the given UUID.
`409`	Duplicate SKU or barcode within the organization.