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

Stock Management API

Record and manage inventory movements with VSCU integration.

Overview

The Stock API allows you to record stock movements (stock in, stock out, adjustments) and sync them with KRA eTIMS. All stock movements are submitted to VSCU for compliance tracking.

Create Stock Movement

Record a stock movement (stock in, stock out, or adjustment).

POST/api/v1/stock

Create Stock Movement

Record a stock movement and sync to VSCU. Supports stock in (11), stock out (12), and adjustments (13).

Authentication
Request BodyJSON

Field Descriptions

Main Fields

FieldTypeRequiredDescription
branch_idstringYesBranch identifier (bhf_id)
sar_nostringYesStock adjustment/receipt number
sar_ty_cdstringYesSAR type code (11=Receive, 12=Out, 13=Adjustment)
sar_dtstringYesSAR date in YYYYMMDD format
sar_rcv_dtstringNoReceipt date in YYYYMMDD format
tot_item_cntintegerYesTotal number of items
tot_taxbl_amtnumberYesTotal taxable amount
tot_tax_amtnumberYesTotal tax amount
tot_amtnumberYesTotal amount including tax
remarkstringNoRemarks/notes

Item Fields

FieldTypeRequiredDescription
item_seqintegerYesItem sequence number
item_cdstringYesItem code
item_clss_cdstringYesItem classification code
item_nmstringYesItem name
bcdstringNoBarcode
pkg_unit_cdstringYesPackage unit code
pkgnumberYesNumber of packages
qty_unit_cdstringYesQuantity unit code
qtynumberYesQuantity
item_expr_dtstringNoExpiry date (YYYYMMDD)
prcnumberYesUnit price
sply_amtnumberYesSupply amount
tot_dcamtnumberNoTotal discount amount
taxbl_amtnumberYesTaxable amount
tax_ty_cdstringYesTax type code
tax_amtnumberYesTax amount
tot_amtnumberYesTotal amount

SAR Type Codes

CodeDescription
11Stock In (Receipt)
12Stock Out
13Stock Adjustment

Response

Status: 200 OK

{
  "status": "success",
  "data": {
    "transaction_id": "9d3f4b1a-7c8e-4d2f-b5a6-1e3c9f8d2b4a",
    "sar_no": "SAR-2024-001",
    "sar_type": "11",
    "item_count": 1,
    "total_amount": 116000,
    "vscu_receipt_code": "000",
    "vscu_receipt_msg": "SUCCESS"
  },
  "meta": {
    "timestamp": "2024-01-15T14:30:30Z",
    "request_id": "req_123abc"
  }
}

List Stock Movements

Get all stock movements for a branch.

GET/api/v1/stock

List Stock Movements

Retrieve stock movements with optional filters by item, date range, and pagination.

Authentication
Parameters
item_code
string · query

Filter by item code

from_date
string · query

Start date (YYYY-MM-DD)

to_date
string · query

End date (YYYY-MM-DD)

per_page
number · query

Results per page (max 100)

Response

Status: 200 OK

{
  "data": [
    {
      "transaction_id": "...",
      "item_code": "ITEM001",
      "item_name": "Product A",
      "movement_type": "11",
      "qty": 50,
      "movement_date": "20240115",
      "created_at": "2024-01-15T14:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 50,
    "total": 234,
    "total_pages": 5
  }
}

Get Item Stock Level

Get current stock level for a specific item.

GET/api/v1/stock/{item_code}

Get Item Stock Level

Retrieve current stock level and last movement for a specific item.

Authentication
Parameters
item_code*
string · path

Item code

Response

Status: 200 OK

{
  "status": "success",
  "data": {
    "item_code": "ITEM001",
    "item_name": "Product A",
    "current_stock": 150.5,
    "last_movement": {
      "type": "11",
      "qty": 50,
      "date": "2024-01-15T14:30:00Z"
    },
    "total_movements": 45
  }
}

Code Examples

JavaScript

const axios = require('axios');
 
const apiKey = process.env.CTAX_API_KEY;
const baseURL = 'https://c-tax.1809ltd.co.ke/api/v1';
 
const stockData = {
  branch_id: '00',
  sar_no: `SAR-${Date.now()}`,
  sar_ty_cd: '11', // Stock In
  sar_dt: new Date().toISOString().slice(0,10).replace(/-/g, ''),
  tot_item_cnt: 1,
  tot_taxbl_amt: 100000,
  tot_tax_amt: 16000,
  tot_amt: 116000,
  remark: 'Stock received',
  items: [
    {
      item_seq: 1,
      item_cd: 'ITEM001',
      item_clss_cd: '5020230201',
      item_nm: 'Product A',
      pkg_unit_cd: 'CT',
      pkg: 1,
      qty_unit_cd: 'U',
      qty: 50,
      prc: 2000,
      sply_amt: 100000,
      taxbl_amt: 100000,
      tax_ty_cd: 'A',
      tax_amt: 16000,
      tot_amt: 116000
    }
  ]
};
 
const response = await axios.post(`${baseURL}/stock`, stockData, {
  headers: { Authorization: `Bearer ${apiKey}` }
});

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',
    ],
]);
 
$data = [
    'branch_id' => '00',
    'sar_no' => 'SAR-' . time(),
    'sar_ty_cd' => '11',
    'sar_dt' => date('Ymd'),
    'tot_item_cnt' => 1,
    'tot_taxbl_amt' => 100000,
    'tot_tax_amt' => 16000,
    'tot_amt' => 116000,
    'items' => [
        [
            'item_seq' => 1,
            'item_cd' => 'ITEM001',
            'item_clss_cd' => '5020230201',
            'item_nm' => 'Product A',
            'pkg_unit_cd' => 'CT',
            'pkg' => 1,
            'qty_unit_cd' => 'U',
            'qty' => 50,
            'prc' => 2000,
            'sply_amt' => 100000,
            'taxbl_amt' => 100000,
            'tax_ty_cd' => 'A',
            'tax_amt' => 16000,
            'tot_amt' => 116000,
        ],
    ],
];
 
$response = $client->post('stock', ['json' => $data]);

Python

import requests
from datetime import datetime
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}'}
 
stock_data = {
    'branch_id': '00',
    'sar_no': f'SAR-{int(datetime.now().timestamp())}',
    'sar_ty_cd': '11',
    'sar_dt': datetime.now().strftime('%Y%m%d'),
    'tot_item_cnt': 1,
    'tot_taxbl_amt': 100000,
    'tot_tax_amt': 16000,
    'tot_amt': 116000,
    'items': [
        {
            'item_seq': 1,
            'item_cd': 'ITEM001',
            'item_clss_cd': '5020230201',
            'item_nm': 'Product A',
            'pkg_unit_cd': 'CT',
            'pkg': 1,
            'qty_unit_cd': 'U',
            'qty': 50,
            'prc': 2000,
            'sply_amt': 100000,
            'taxbl_amt': 100000,
            'tax_ty_cd': 'A',
            'tax_amt': 16000,
            'tot_amt': 116000
        }
    ]
}
 
response = requests.post(f'{base_url}/stock', json=stock_data, headers=headers)

Best Practices

  1. Track All Movements - Record every stock in, out, and adjustment
  2. Match with Transactions - Link stock movements to sales/purchases
  3. Regular Reconciliation - Perform physical counts and adjustments
  4. Unique SAR Numbers - Use unique identifiers for each movement
  5. Document Reasons - Always include remarks explaining the movement
  6. Monitor Stock Levels - Regularly check stock levels via API
Last updated on
Purchases APIImports API