Search docs...⌘K

Catalogue & Product Master Guide

Item Master, HSN Directory & Pricing

The foundational master dataset for your enterprise. Manage physical goods, services, Bill of Materials (BOM) composites, universal HSN/SAC classifications, GST rates, barcode scanning, and multi-tier price lists in Katixo.

1. Module Overview: The Core Product Catalog

Every transaction across Sales, Procurement, POS, and Warehousing references the Item Master. Configuring accurate item metadata guarantees that GST rates, batch controls, and inventory cost calculations operate without manual intervention:

Universal HSN Resolution

Auto-resolves statutory 4, 6, or 8-digit HSN codes and applies correct GST 2.0 rates (0%, 5%, 12%, 18%, 28%).

BOM & Composite Items

Define multi-component assemblies (e.g. Gift Hampers, Manufacturing kits) with automatic component explosion upon sale.

Barcode & Scanner Ready

Supports EAN-13, UPC, and custom internal barcodes for lightning-fast point-of-sale and warehouse picking.

2. How to Create an Item (Step-by-Step UI Guide)

1
Go to Inventory > Items > Click "Add Item":Choose Item Type: Goods (physical stock), Service (consulting, labor), or Composite (BOM).
2
Enter SKU, Barcode & Name:Input your internal SKU code or scan the retail barcode. Name the product with clear pack size (e.g. "Basmati Rice 5kg").
3
Select HSN Code & Tax:Search the national HSN directory. Selecting the HSN code auto-fills the statutory GST rate.
4
Set Pricing, UoM & Reorder Level:Define standard Purchase Price, Selling Price (MRP), primary Unit of Measurement (e.g. BOX, PCS, KGS), and warehouse Reorder Level for automated shortage alerts.

Developer & REST API Reference

Programmatically query, create, update, and bulk-import catalogue items via REST:

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.