Skip to Content
C-Tax v1.0 is now available
API ReferenceItems API

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:

  • List items from your local database
  • Search KRA-registered items
  • Register new items with KRA
  • Manage item details and pricing

Item Structure

Key Fields

FieldDescription
item_codeUnique item identifier
item_nameItem name/description
item_class_codeKRA classification code
item_type_codeItem type (1=Raw Material, 2=Finished, 3=Service)
tax_type_codeTax type (A, B, C, D, E)
tax_rateTax rate percentage
default_priceDefault selling price
pkg_unit_codePackaging unit code
qty_unit_codeQuantity unit code

Tax Types

CodeNameRate
AStandard Rate16%
BExempt0%
CSpecial0%
DZero-rated0%
ESpecial Exemption0%

Search Items

Search for items in your local database or KRA registry.

POST/api/v1/items/search

Search Items

Search for items by code, name, or barcode. Searches both local database and KRA registry.

Authentication
Request BodyJSON

Query/Body Parameters

ParameterTypeRequiredDescription
branch_idstringNoBranch ID (default: “00”)
searchstringNoSearch term
limitintegerNoMax results (default: 20, max: 100)

Response

Status: 200 OK

{
  "status": "success",
  "data": [
    {
      "item_code": "ITEM001",
      "item_name": "Product A",
      "item_class_code": "5101",
      "item_type": "2",
      "tax_type": "A",
      "tax_rate": 16,
      "default_price": 1000.00,
      "is_active": true,
      "source": "kra_registry"
    }
  ],
  "meta": {
    "total": 5,
    "search": "laptop",
    "limit": 20,
    "source": "kra_registry",
    "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 from local database or KRA registry.

Authentication
Parameters
itemCode*
string · path

Item code

branch_id
string · query

Branch ID (default: '00')

Response

Status: 200 OK

{
  "status": "success",
  "data": {
    "item_code": "ITEM001",
    "item_name": "Product A",
    "item_class_code": "5101",
    "item_type": "2",
    "tax_type": "A",
    "tax_rate": 16,
    "default_price": 1000.00,
    "barcode": "1234567890123",
    "pkg_unit_code": "NT",
    "qty_unit_code": "U",
    "origin_country": "KE",
    "safety_qty": 10,
    "is_active": true,
    "is_insurance_applicable": false
  },
  "meta": {
    "source": "kra_registry",
    "timestamp": "2025-01-15T14:30:00Z"
  }
}

Status: 404 Not Found

{
  "status": "error",
  "message": "Item not found in KRA registry"
}

Create Item

Register a new item with KRA and save to local database.

POST/api/v1/items

Create Item

Register a new item with KRA. The item is saved locally and synced to KRA.

Authentication
Request BodyJSON

Field Descriptions

FieldTypeRequiredDescription
branch_idstringNoBranch ID (default: “00”)
item_namestringYesItem name (max 200 chars)
item_class_codestringYesKRA classification code (max 20 chars)
item_codestringNoItem code (auto-generated if not provided)
item_type_codestringNoItem type: 1=Raw, 2=Finished, 3=Service (default: “2”)
unit_pricenumberNoDefault price (min 0)
tax_typestringYesTax type: A, B, C, D, or E
pkg_unit_codestringNoPackaging unit code (default: “NT”)
qty_unit_codestringNoQuantity unit code (default: “U”)
barcodestringNoBarcode (max 100 chars)
origin_nation_codestringNoOrigin country code (default: “KE”)
safety_qtynumberNoSafety stock quantity (min 0)
additional_infostringNoAdditional information
is_insurance_applicablebooleanNoInsurance applicable flag

Response

Status: 201 Created

{
  "status": "success",
  "message": "Item registered successfully with KRA",
  "data": {
    "id": 123,
    "item_code": "NEWITEM001",
    "item_name": "New Product",
    "item_class_code": "5101",
    "default_price": 1500.00,
    "synced_to_kra": true
  },
  "meta": {
    "source": "local_database",
    "timestamp": "2025-01-15T14:30:00Z"
  }
}

Note: If KRA sync fails, the item is still saved locally with synced_to_kra: false.

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:

KE + [First 3 digits of TIN] + [8-digit sequence]

Example: KE12300000001

Code Examples

JavaScript

const axios = require('axios');
 
const apiKey = process.env.CTAX_API_KEY;
const baseURL = 'https://c-tax.1809ltd.co.ke/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
const newItem = await axios.post(`${baseURL}/items`, {
  branch_id: '00',
  item_name: 'Premium Laptop',
  item_class_code: '8471',
  unit_price: 85000.00,
  tax_type: 'A',
  barcode: '1234567890123'
}, {
  headers: { Authorization: `Bearer ${apiKey}` }
});
 
console.log(`Item created: ${newItem.data.data.item_code}`);

PHP

use GuzzleHttp\Client;
 
$client = new Client([
    'base_uri' => 'https://c-tax.1809ltd.co.ke/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
$response = $client->post('items', [
    'json' => [
        'branch_id' => '00',
        'item_name' => 'Premium Laptop',
        'item_class_code' => '8471',
        'unit_price' => 85000.00,
        'tax_type' => 'A',
    ],
]);

Python

import requests
import os
 
api_key = os.environ['CTAX_API_KEY']
base_url = 'https://c-tax.1809ltd.co.ke/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
response = requests.post(
    f'{base_url}/items',
    json={
        'branch_id': '00',
        'item_name': 'Premium Laptop',
        'item_class_code': '8471',
        'unit_price': 85000.00,
        'tax_type': 'A',
    },
    headers=headers
)

Item Classification Codes

Use the Codes API to get valid classification codes:

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

Packaging and Quantity Units

Common Packaging Units

CodeDescription
NTNo Package
BXBox
CTCarton
PKPack
BGBag
BTBottle

Common Quantity Units

CodeDescription
UUnit/Piece
KGKilogram
LTLiter
MMeter
M2Square Meter
M3Cubic Meter

Get full list from Codes API:

// Get packaging units
const pkgUnits = await axios.get('/api/v1/codes/packaging-units', {
  headers: { Authorization: `Bearer ${apiKey}` }
});
 
// Get quantity units
const qtyUnits = await axios.get('/api/v1/codes/quantity-units', {
  headers: { Authorization: `Bearer ${apiKey}` }
});

Best Practices

  1. Use Local Database - Prefer /items/search with cached results for better performance
  2. Sync Regularly - Keep local items synced with KRA
  3. Unique Codes - Use meaningful, unique item codes
  4. Correct Tax Types - Verify tax classification for each item
  5. Valid Classifications - Use valid KRA item class codes
  6. Handle Sync Failures - Items saved locally can be synced later
Last updated on
Devices APISales API