Items API

Manage inventory items and register them with KRA. Items are the products and services you sell, purchase, or stock.

Overview

The Items API allows you to:

Search KRA-registered items
Register new items with KRA
Manage item details and pricing

Item Structure

Key Fields

Field	Description	Example
`item_code`	Unique item identifier	`KE2NTU0000001`
`item_name`	Item name/description	`Laptop Computer`
`item_class_code`	KRA classification code (10 digits)	`5020230201`
`item_type_code`	Item type (1=Raw Material, 2=Finished, 3=Service)	`2`
`tax_type_code`	Tax type (A, B, C, D, E)	`A`
`tax_rate`	Tax rate percentage	`16.00`
`default_price`	Default selling price (KES)	`85000.00`
`pkg_unit_code`	Packaging unit code	`BX` (Box)
`qty_unit_code`	Quantity unit code	`U` (Unit)
`origin_nation_code`	Country of origin (ISO 2-letter)	`CN` (China)

Tax Types

Tax types are defined by KRA. Use the Codes API to get the current list:


const response = await axios.get('/api/v1/codes/tax-types', {
  headers: { Authorization: `Bearer ${apiKey}` }
});
// Returns: [{ code: 'A', name: '16% VAT', ... }, { code: 'B', name: 'Exempt', ... }, ...]

Common tax types include:

A - Exempt
B - 16.00% (Standard VAT)
C - 0%
D - Non-VAT
E - 8%

Item Code Format

Item codes follow the KRA specification 4.17 format:

Format: CountryCode + ProductType + PackagingUnit + QuantityUnit + Sequence

Example: KE2NTBA0000012

KE = Country of Origin (Kenya)
2 = Product Type (Finished Product)
NT = Packaging Unit (No Package/NET)
BA = Quantity Unit (Barrel)
0000012 = Sequential number (7 digits, from 0000001 to N)

Product Types:

1 = Raw Material
2 = Finished Product
3 = Service

The system auto-generates codes if not provided based on item attributes (origin country, product type, packaging unit, quantity unit).

Search Items

Search for items registered with KRA.

POST/api/v1/items/search

Search Items

Search for items by code, name, or barcode. Only returns items synced to KRA.

Authentication

Request BodyJSON

Not finding what you’re looking for? If you search for “laptop” and get no results, it means that item hasn’t been registered with KRA yet. Try searching for items you’ve already registered, like “coffee” or “tea”. To add a new item, use the Create Item endpoint below.

Query/Body Parameters

Parameter	Type	Required	Description
`branch_id`	string	No	Branch ID (default: “00”)
`search`	string	No	Search term
`limit`	integer	No	Max results (default: 20, max: 100)

Response

Status: 200 OK


{
  "status": "success",
  "data": [
    {
      "item_code": "KE2BXU0000001",
      "item_name": "Laptop Computer - HP ProBook 450",
      "item_class_code": "5020230201",
      "item_type": "2",
      "tax_type": "B",
      "tax_rate": 16.00,
      "default_price": 85000.00,
      "barcode": "8471000001234",
      "pkg_unit_code": "BX",
      "qty_unit_code": "U",
      "origin_country": "CN",
      "is_active": true
    },
    {
      "item_code": "KE2BXU0000015",
      "item_name": "Desktop Computer - Dell OptiPlex",
      "item_class_code": "5020230201",
      "item_type": "2",
      "tax_type": "B",
      "tax_rate": 16.00,
      "default_price": 65000.00,
      "barcode": "8471000001567",
      "pkg_unit_code": "BX",
      "qty_unit_code": "U",
      "origin_country": "CN",
      "is_active": true
    }
  ],
  "meta": {
    "total": 2,
    "search": "coffee",
    "limit": 20,
    "timestamp": "2025-01-15T14:30:00Z"
  }
}

Get Item Details

Retrieve details of a specific item.

GET/api/v1/items/{itemCode}

Get Item Details

Retrieve detailed information about a specific item registered with KRA.

Authentication

Parameters

itemCode*

string · path

Item code (KRA format: Country + Type + Pkg + Qty + Sequence)

branch_id

string · query

Branch ID (default: '00')

Response

Status: 200 OK


{
  "status": "success",
  "data": {
    "item_code": "KE2BXU0000001",
    "item_name": "Laptop Computer - HP ProBook 450",
    "item_class_code": "5020230201",
    "item_type": "2",
    "tax_type": "B",
    "tax_rate": 16.00,
    "default_price": 85000.00,
    "barcode": "8471000001234",
    "pkg_unit_code": "BX",
    "qty_unit_code": "U",
    "origin_country": "CN",
    "safety_qty": 5,
    "is_active": true,
    "is_insurance_applicable": false
  },
  "meta": {
    "timestamp": "2025-01-15T14:30:00Z"
  }
}

Status: 404 Not Found


{
  "status": "error",
  "message": "Item not found"
}

Create Item

POST/api/v1/items

Create Item

Authentication

Request BodyJSON

Field Descriptions

Field	Type	Required	Description
`branch_id`	string	No	Branch ID (default: “00”)
`item_name`	string	Yes	Item name (max 200 chars)
`item_class_code`	string	Yes	KRA classification code (max 20 chars)
`item_code`	string	No	Item code (auto-generated if not provided)
`item_type_code`	string	No	Item type: 1=Raw, 2=Finished, 3=Service (default: “2”)
`unit_price`	number	No	Default price (min 0)
`tax_type`	string	Yes	Tax type: A, B, C, D, or E
`pkg_unit_code`	string	No	Packaging unit code (default: “NT”)
`qty_unit_code`	string	No	Quantity unit code (default: “U”)
`barcode`	string	No	Barcode (max 100 chars)
`origin_nation_code`	string	No	Origin country code (default: “KE”)
`safety_qty`	number	No	Safety stock quantity (min 0)
`additional_info`	string	No	Additional information
`is_insurance_applicable`	boolean	No	Insurance applicable flag

Response

Status: 201 Created


{
  "status": "success",
  "message": "Item registered successfully with KRA",
  "data": {
    "id": 123,
    "item_code": "KE2BXU0000042",
    "item_name": "Office Chair - Executive Leather",
    "item_class_code": "9401",
    "default_price": 12500.00,
    "synced_to_kra": true
  },
  "meta": {
    "timestamp": "2025-01-15T14:30:00Z"
  }
}

Validation Errors

Status: 422 Unprocessable Entity


{
  "status": "error",
  "message": "Validation failed",
  "errors": {
    "item_name": ["The item name field is required."],
    "tax_type": ["The selected tax type is invalid."]
  }
}

Item Code Generation

If item_code is not provided, it’s auto-generated using the format:


Country + ProductType + PackagingUnit + QuantityUnit + 7-digit sequence

Example: KE2NTU0000001

Realistic Item Examples

Here are realistic examples for all tax types that you can use when testing:

Tax Type B (16% VAT) - Standard Taxable Items


{
  "item_code": "KE2BXU0000001",
  "item_name": "Laptop Computer - HP ProBook 450",
  "item_class_code": "5020230201",
  "item_type_code": "2",
  "unit_price": 85000.00,
  "tax_type": "B",
  "pkg_unit_code": "BX",
  "qty_unit_code": "U",
  "barcode": "8471000001234",
  "origin_nation_code": "CN"
}


{
  "item_code": "KE2CTU0000008",
  "item_name": "Office Desk - 1.5m Executive",
  "item_class_code": "9403",
  "item_type_code": "2",
  "unit_price": 18500.00,
  "tax_type": "B",
  "pkg_unit_code": "CT",
  "qty_unit_code": "U",
  "origin_nation_code": "KE"
}

Tax Type A (Exempt) - Essential Unprocessed Goods


{
  "item_code": "KE1BGKG0000002",
  "item_name": "Maize Grain - White",
  "item_class_code": "1005",
  "item_type_code": "1",
  "unit_price": 50.00,
  "tax_type": "A",
  "pkg_unit_code": "BG",
  "qty_unit_code": "KG",
  "barcode": "1005000012345",
  "origin_nation_code": "KE"
}


{
  "item_code": "KE2BTLT0000009",
  "item_name": "Fresh Milk - Pasteurized",
  "item_class_code": "0401",
  "item_type_code": "2",
  "unit_price": 60.00,
  "tax_type": "A",
  "pkg_unit_code": "BT",
  "qty_unit_code": "LT",
  "origin_nation_code": "KE"
}

Tax Type C (0%) - Special Items


{
  "item_code": "KE2BXU0000003",
  "item_name": "Blood Pressure Monitor - Digital",
  "item_class_code": "9018",
  "item_type_code": "2",
  "unit_price": 8500.00,
  "tax_type": "C",
  "pkg_unit_code": "BX",
  "qty_unit_code": "U",
  "barcode": "9018000012345",
  "origin_nation_code": "CN"
}

Tax Type D (Non-VAT) - Export Goods


{
  "item_code": "KE1BGKG0000004",
  "item_name": "Coffee Beans - AA Grade Export",
  "item_class_code": "0901",
  "item_type_code": "1",
  "unit_price": 750.00,
  "tax_type": "D",
  "pkg_unit_code": "BG",
  "qty_unit_code": "KG",
  "barcode": "0901000012345",
  "origin_nation_code": "KE"
}


{
  "item_code": "KE1BGKG0000010",
  "item_name": "Tea Leaves - Export Grade",
  "item_class_code": "0902",
  "item_type_code": "1",
  "unit_price": 450.00,
  "tax_type": "D",
  "pkg_unit_code": "BG",
  "qty_unit_code": "KG",
  "origin_nation_code": "KE"
}

Tax Type E (8% VAT) - Educational Items


{
  "item_code": "KE2NTU0000005",
  "item_name": "Mathematics Textbook - Form 1",
  "item_class_code": "4901",
  "item_type_code": "2",
  "unit_price": 850.00,
  "tax_type": "E",
  "pkg_unit_code": "NT",
  "qty_unit_code": "U",
  "barcode": "4901000012345",
  "origin_nation_code": "KE"
}

Code Examples

JavaScript


const axios = require('axios');
 
const apiKey = process.env.CTAX_API_KEY;
const baseURL = 'https://c-ushuru.com/api/v1';
 
// Search items
const searchResults = await axios.post(`${baseURL}/items/search`, {
  branch_id: '00',
  search: 'laptop',
  limit: 20
}, {
  headers: { Authorization: `Bearer ${apiKey}` }
});
 
// Create item with Tax Type A (16% VAT)
const newItem = await axios.post(`${baseURL}/items`, {
  branch_id: '00',
  item_name: 'Laptop Computer - HP ProBook 450',
  item_class_code: '5020230201',
  item_type_code: '2',
  unit_price: 85000.00,
  tax_type: 'B',
  pkg_unit_code: 'BX',
  qty_unit_code: 'U',
  barcode: '8471000001234',
  origin_nation_code: 'CN'
}, {
  headers: { Authorization: `Bearer ${apiKey}` }
});
 
console.log(`Item created: ${newItem.data.data.item_code}`); // e.g., KE2BXU0000042

PHP


use GuzzleHttp\Client;
 
$client = new Client([
    'base_uri' => 'https://c-ushuru.com/api/v1/',
    'headers' => [
        'Authorization' => 'Bearer ' . env('CTAX_API_KEY'),
        'Content-Type' => 'application/json',
    ],
]);
 
// Search items
$response = $client->post('items/search', [
    'json' => [
        'branch_id' => '00',
        'search' => 'laptop'
    ],
]);
 
$items = json_decode($response->getBody(), true)['data'];
 
// Create item with Tax Type A (16% VAT)
$response = $client->post('items', [
    'json' => [
        'branch_id' => '00',
        'item_name' => 'Laptop Computer - HP ProBook 450',
        'item_class_code' => '5020230201',
        'item_type_code' => '2',
        'unit_price' => 85000.00,
        'tax_type' => 'B',
        'pkg_unit_code' => 'BX',
        'qty_unit_code' => 'U',
        'barcode' => '8471000001234',
        'origin_nation_code' => 'CN',
    ],
]);
 
$itemData = json_decode($response->getBody(), true)['data'];
echo "Item created: " . $itemData['item_code']; // e.g., KE2BXU0000042

Python


import requests
import os
 
api_key = os.environ['CTAX_API_KEY']
base_url = 'https://c-ushuru.com/api/v1'
headers = {'Authorization': f'Bearer {api_key}'}
 
# Search for item
response = requests.post(
    f'{base_url}/items/search',
    json={'branch_id': '00', 'search': 'laptop'},
    headers=headers
)
items = response.json()['data']
 
# Create item with Tax Type A (16% VAT)
response = requests.post(
    f'{base_url}/items',
    json={
        'branch_id': '00',
        'item_name': 'Laptop Computer - HP ProBook 450',
        'item_class_code': '8471',
        'item_type_code': '2',
        'unit_price': 85000.00,
        'tax_type': 'B',
        'pkg_unit_code': 'BX',
        'qty_unit_code': 'U',
        'barcode': '8471000001234',
        'origin_nation_code': 'CN',
    },
    headers=headers
)
 
item_data = response.json()['data']
print(f"Item created: {item_data['item_code']}")  # e.g., KE2BXU0000042

Item Classification Codes

Item classification codes (HS Codes) are standardized codes provided by KRA. To find the correct classification code for your items, use the Codes API:


// Search for item classification codes
const response = await axios.get('/api/v1/codes/item-classes/select', {
  params: { search: 'computer' },
  headers: { Authorization: `Bearer ${apiKey}` }
});
 
const itemClasses = response.data.data;
// Returns: [{ value: '5020230201', label: '5020230201 - Computers', code: '5020230201', name: 'Computers' }]


// Get all item types (product types)
const itemTypes = await axios.get('/api/v1/codes/item-types', {
  headers: { Authorization: `Bearer ${apiKey}` }
});
// Returns: [{ code: '1', name: 'Raw Material', ... }, { code: '2', name: 'Finished Product', ... }, ...]

Packaging and Quantity Units

Packaging and quantity units are defined by KRA. Use the Codes API to get the current list:


// Get all packaging units from KRA
const pkgUnits = await axios.get('/api/v1/codes/packaging-units', {
  headers: { Authorization: `Bearer ${apiKey}` }
});
// Returns: [{ code: 'NT', name: 'No Package', ... }, { code: 'BX', name: 'Box', ... }, ...]
 
// Get all quantity units from KRA
const qtyUnits = await axios.get('/api/v1/codes/quantity-units', {
  headers: { Authorization: `Bearer ${apiKey}` }
});
// Returns: [{ code: 'U', name: 'Unit', ... }, { code: 'KG', name: 'Kilogram', ... }, ...]

Common codes include:

Packaging: NT (No Package), BX (Box), CT (Carton), BG (Bag), BT (Bottle), PK (Pack)
Quantity: U (Unit), KG (Kilogram), LT (Liter), M (Meter), M2 (Square Meter), M3 (Cubic Meter)

Best Practices

Unique Codes - Ensure each item has a unique item code following KRA format
Correct Tax Types - Verify tax classification for each item (A, B, C, D, or E)
Valid Classifications - Use valid KRA item class codes (HS codes)
Accurate Attributes - Provide correct packaging units, quantity units, and origin country codes

Sales API - Use items in sales
Purchases API - Use items in purchases
Stock API - Stock movements for items
Codes API - Item classifications and units

Items API

Overview

Item Structure

Key Fields

Tax Types

Item Code Format

Search Items

Search Items

Query/Body Parameters

Response

Get Item Details

Get Item Details

Response

Create Item

Create Item

Field Descriptions

Response

Validation Errors

Item Code Generation

Realistic Item Examples

Tax Type B (16% VAT) - Standard Taxable Items

Tax Type A (Exempt) - Essential Unprocessed Goods

Tax Type C (0%) - Special Items

Tax Type D (Non-VAT) - Export Goods

Tax Type E (8% VAT) - Educational Items

Code Examples

JavaScript

PHP

Python

Item Classification Codes

Packaging and Quantity Units

Best Practices

Related Endpoints