eTIMS Items & Stock API

Register, update, and manage items (products/services) in the eTIMS system. Track stock movements and current inventory levels as required by KRA.

Table of Contents

1. Overview
2. Register Item
3. Get Item
4. Update Item
5. Stock Movement
6. Get Current Stock
7. Stock Report
8. Item Classification Codes
9. Status Codes

Overview

Required Scopes

Endpoint Summary

Register Item

Register a new item/product/service with KRA eTIMS.

Endpoint: POST /api/etims/items/register

Required Scope: etims:write

Request Body:

Item Types

Common Package Units

Common Quantity Units

Request:

curl -X POST \
  https://yourtenant.salami.dgl.co.ke/api/etims/items/register \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "item_code": "CHAIR-001",
    "item_name": "Executive Office Chair",
    "item_type": "2",
    "item_class_code": "94017100",
    "origin_country": "CN",
    "taxation_type": "B",
    "unit_price": 15000.00,
    "package_unit": "NT",
    "quantity_unit": "U",
    "description": "Ergonomic executive office chair with lumbar support"
  }'

Response:

{
  "success": true,
  "data": {
    "item_id": 123,
    "item_code": "CHAIR-001",
    "item_name": "Executive Office Chair",
    "item_type": "2",
    "taxation_type": "B",
    "unit_price": 15000.00,
    "status": "registered",
    "registered_at": "2026-03-29T16:20:00Z"
  },
  "message": "Item registered successfully"
}

Get Item

Retrieve item details by item code.

Endpoint: GET /api/etims/items/{item_code}

Required Scope: etims:read

Request:

curl -X GET \
  https://yourtenant.salami.dgl.co.ke/api/etims/items/CHAIR-001 \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Response:

{
  "success": true,
  "data": {
    "id": 123,
    "item_code": "CHAIR-001",
    "item_name": "Executive Office Chair",
    "item_type": "2",
    "item_class_code": "94017100",
    "origin_country": "CN",
    "taxation_type": "B",
    "unit_price": 15000.00,
    "package_unit": "NT",
    "quantity_unit": "U",
    "current_stock": 50,
    "description": "Ergonomic executive office chair with lumbar support",
    "status": "active",
    "created_at": "2026-03-29T16:20:00Z"
  }
}

Update Item

Update item information. The item must already be registered.

Endpoint: PUT /api/etims/items/{item_code}

Required Scope: etims:write

Request Body:

Request:

curl -X PUT \
  https://yourtenant.salami.dgl.co.ke/api/etims/items/CHAIR-001 \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "item_name": "Executive Office Chair - Premium",
    "unit_price": 18000.00,
    "description": "Premium ergonomic chair with adjustable armrests"
  }'

Response:

{
  "success": true,
  "data": {
    "item_code": "CHAIR-001",
    "item_name": "Executive Office Chair - Premium",
    "unit_price": 18000.00,
    "status": "updated",
    "updated_at": "2026-03-29T16:25:00Z"
  },
  "message": "Item updated successfully"
}

Stock Movement

Record stock additions, reductions, adjustments, or transfers.

Endpoint: POST /api/etims/stock/movement

Required Scope: etims:write

Request Body:

Movement Types (Stock Transaction Codes)

Item Fields

Request:

curl -X POST \
  https://yourtenant.salami.dgl.co.ke/api/etims/stock/movement \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "movement_type": "01",
    "movement_date": "2026-03-29",
    "reason": "Received stock from supplier - PO#2026-045",
    "items": [
      {
        "item_code": "CHAIR-001",
        "quantity": 100,
        "unit_price": 12000.00
      },
      {
        "item_code": "DESK-001",
        "quantity": 50,
        "unit_price": 20000.00
      }
    ]
  }'

Response:

{
  "success": true,
  "data": {
    "movement_id": 234,
    "movement_type": "01",
    "movement_date": "2026-03-29",
    "total_items": 2,
    "items": [
      {"item_code": "CHAIR-001", "quantity": 100, "new_stock": 150},
      {"item_code": "DESK-001", "quantity": 50, "new_stock": 75}
    ],
    "status": "submitted",
    "submitted_at": "2026-03-29T16:30:00Z"
  },
  "message": "Stock movement recorded successfully"
}

Get Current Stock

Retrieve current stock levels for all items or a specific item.

Endpoint: GET /api/etims/stock/current

Required Scope: etims:read

Query Parameters:

Request:

curl -X GET \
  'https://yourtenant.salami.dgl.co.ke/api/etims/stock/current?item_code=CHAIR-001' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Response:

{
  "success": true,
  "data": [
    {
      "item_code": "CHAIR-001",
      "item_name": "Executive Office Chair - Premium",
      "quantity": 150,
      "unit_price": 18000.00,
      "total_value": 2700000.00,
      "last_movement": "2026-03-29T16:30:00Z"
    }
  ]
}

Stock Report

Get a summary of current stock levels and values.

Endpoint: GET /api/etims/reports/stock

Required Scope: etims:read

Request:

curl -X GET \
  https://yourtenant.salami.dgl.co.ke/api/etims/reports/stock \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Response:

{
  "success": true,
  "data": {
    "total_items": 85,
    "total_stock_value": 4500000.00,
    "low_stock_items": 5,
    "out_of_stock_items": 2,
    "by_item_type": {
      "raw_material": {"count": 30, "value": 1500000.00},
      "finished_product": {"count": 50, "value": 2800000.00},
      "service": {"count": 5, "value": 200000.00}
    }
  }
}

Item Classification Codes

Item classification codes follow the Harmonized System (HS) coding structure. Common codes for Kenya:

Use the eTIMS Codes API to retrieve the full classification list from KRA.

Status Codes

Best Practices

1. Register items before selling -- Items must exist in eTIMS before they can appear on invoices
2. Use meaningful codes -- Use a consistent item code scheme (e.g., CAT-SKU-VARIANT)
3. Assign correct HS codes -- HS codes determine tax treatment and customs classification
4. Track stock movements -- Record all stock changes within 24 hours
5. Regular stock counts -- Reconcile physical stock with eTIMS records periodically
6. Update prices -- Keep unit prices current to match actual selling prices

Related Documentation

• eTIMS Sales -- Submit sales referencing registered items
• eTIMS Purchases -- Record purchased items
• eTIMS Codes -- Full code reference tables

Back to: eTIMS Sales | eTIMS Codes