Purchases API

Create and manage purchase transactions with automatic VSCU submission.

Overview

The Purchases API allows you to record supplier purchases and sync them with KRA eTIMS. All purchases are validated and submitted to VSCU for compliance.

Create Purchase

Submit a purchase transaction to the VSCU system.

POST/api/v1/purchases

Create Purchase

Submit a purchase transaction to the VSCU system. The purchase is validated, stored locally, and synced to KRA.

Authentication

Request BodyJSON

Field Descriptions

Main Fields

Field	Type	Required	Description
`branch_id`	string	Yes	Branch identifier (bhf_id)
`invoice_no`	string	Yes	Your unique purchase invoice number
`purchase_date`	string	Yes	Date in YYYYMMDD format
`purchase_time`	string	Yes	Time in HHMMSS format
`supplier_tin`	string	Yes	Supplier’s TIN number
`supplier_name`	string	Yes	Supplier’s business name
`supplier_bhf_id`	string	No	Supplier’s branch ID
`supplier_invoice_no`	string	Yes	Supplier’s invoice number
`purchase_status`	string	No	Purchase status code
`purchase_type`	string	No	Purchase type (N=Normal, I=Import)
`payment_type`	string	Yes	Payment type code (01=Cash, 02=Card, etc.)

Item Fields

Field	Type	Required	Description
`item_seq`	integer	Yes	Item sequence number (1, 2, 3…)
`item_code`	string	Yes	Item code
`item_class_code`	string	Yes	KRA item classification code (e.g., “5020230201”)
`item_name`	string	Yes	Item name/description
`bcd`	string	No	Barcode (optional)
`pkg_unit_code`	string	Yes	Package unit code (e.g., “NT”, “CT”, “BX”)
`pkg`	number	Yes	Package quantity
`qty_unit_code`	string	Yes	Quantity unit code (e.g., “U”, “KG”, “LT”)
`qty`	number	Yes	Quantity purchased
`unit_price`	number	Yes	Unit price
`supply_amount`	number	Yes	Supply amount (qty × price)
`discount_rate`	number	No	Discount rate percentage (default: 0)
`discount_amount`	number	No	Discount amount (default: 0)
`taxable_amount`	number	Yes	Taxable amount (supply_amount - discount_amount)
`tax_type`	string	Yes	Tax type code (A, B, C, D, E)
`tax_rate`	number	Yes	Tax rate percentage
`tax_amount`	number	Yes	Tax amount
`total_amount`	number	Yes	Total including tax

Important: Tax-Inclusive Pricing

Kenya uses tax-inclusive pricing where prices already include VAT. To calculate amounts:

total_amount = qty × unit_price (what you pay supplier)

supply_amount = total_amount ÷ 1.16 (pre-tax amount)

tax_amount = total_amount - supply_amount (16% VAT extracted)

taxable_amount = supply_amount - discount_amount

Example: Purchasing 10 items at 5,000 KES each (tax inclusive):

unit_price: 5000

qty: 10

total_amount: 50000 (10 × 5000)

supply_amount: 43103.45 (50000 ÷ 1.16)

taxable_amount: 43103.45 (no discount)

tax_amount: 6896.55 (50000 - 43103.45)

Response

Status: 200 OK


{
  "status": "success",
  "data": {
    "transaction_id": "9d3f4b1a-7c8e-4d2f-b5a6-1e3c9f8d2b4a",
    "invoice_no": "PINV-2024-001",
    "receipt_no": "20240115-00-P-00001",
    "receipt_date": "20240115143030",
    "total_amount": 58000,
    "tax_amount": 8000,
    "vscu_receipt_code": "000",
    "vscu_receipt_msg": "SUCCESS"
  },
  "meta": {
    "timestamp": "2024-01-15T14:30:30Z",
    "request_id": "req_123abc"
  }
}

Get Purchase Details

Retrieve details of a specific purchase transaction.

GET/api/v1/purchases/{transaction_id}

Get Purchase Details

Retrieve complete details of a specific purchase transaction.

Authentication

Parameters

transaction_id*

string · path

Purchase transaction UUID

Response

Status: 200 OK


{
  "status": "success",
  "data": {
    "transaction_id": "9d3f4b1a-7c8e-4d2f-b5a6-1e3c9f8d2b4a",
    "branch_id": "00",
    "invoice_no": "PINV-2024-001",
    "receipt_no": "20240115-00-P-00001",
    "purchase_date": "20240115",
    "purchase_time": "143000",
    "supplier_tin": "987654321",
    "supplier_name": "ABC Suppliers Ltd",
    "total_amount": 58000,
    "tax_amount": 8000,
    "status": "success",
    "items": [...],
    "response": {...},
    "created_at": "2024-01-15T14:30:00Z",
    "processed_at": "2024-01-15T14:30:30Z"
  }
}

Search Purchases

Search purchase transactions with filters.

POST/api/v1/purchases/search

Search Purchases

Search and filter purchase transactions by date, invoice number, supplier, or status.

Authentication

Request BodyJSON

Query Parameters

Parameter	Type	Required	Description
`branch_id`	string	No	Filter by branch
`from_date`	string	No	Start date (YYYY-MM-DD)
`to_date`	string	No	End date (YYYY-MM-DD)
`invoice_no`	string	No	Search by invoice number
`supplier_name`	string	No	Search by supplier name
`status`	string	No	Filter by status
`per_page`	integer	No	Results per page (max 100)
`page`	integer	No	Page number

Response

Status: 200 OK


{
  "data": [
    {
      "transaction_id": "...",
      "branch_id": "00",
      "invoice_no": "PINV-2024-001",
      "receipt_no": "20240115-00-P-00001",
      "purchase_date": "20240115",
      "supplier_name": "ABC Suppliers Ltd",
      "total_amount": 58000,
      "status": "success",
      "created_at": "2024-01-15T14:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 87,
    "total_pages": 5
  }
}

Fetch Purchase Sales

Retrieve unregistered sales from VSCU for purchase registration. This endpoint fetches sales transactions that haven’t been registered as purchases yet.

POST/api/v1/purchases/sales

Fetch Purchase Sales

Retrieve unregistered sales from VSCU that are available for purchase registration.

Authentication

Request BodyJSON

Request Body

Field	Type	Required	Description
`branch_id`	string	Yes	Branch identifier (bhf_id)

Response

Status: 200 OK


{
  "status": "success",
  "message": "Fetched pending sales",
  "data": [
    {
      "spplrTin": "P123456789A",
      "spplrBhfId": "00",
      "spplrNm": "ABC Suppliers Ltd",
      "spplrInvcNo": "SUP-INV-001",
      "regDt": "20240115143000",
      "totItemCnt": 3,
      "taxblAmtA": 50000,
      "taxblAmtB": 0,
      "taxblAmtC": 0,
      "taxblAmtD": 0,
      "taxblAmtE": 0,
      "taxRtA": 16,
      "taxAmtA": 8000,
      "taxAmtB": 0,
      "taxAmtC": 0,
      "taxAmtD": 0,
      "taxAmtE": 0,
      "totTaxblAmt": 50000,
      "totTaxAmt": 8000,
      "totAmt": 58000,
      "itemList": [
        {
          "itemSeq": 1,
          "itemCd": "ITEM001",
          "itemClsCd": "5020230201",
          "itemNm": "Product A",
          "qty": 10,
          "prc": 5000,
          "splyAmt": 50000,
          "taxTyCd": "A",
          "taxAmt": 8000,
          "totAmt": 58000
        }
      ]
    }
  ],
  "meta": {
    "timestamp": "2024-01-15T14:30:00Z",
    "request_id": "req_123abc"
  }
}

Response Fields

Field	Type	Description
`spplrTin`	string	Supplier TIN number
`spplrBhfId`	string	Supplier branch ID
`spplrNm`	string	Supplier name
`spplrInvcNo`	string	Supplier invoice number
`regDt`	string	Registration datetime (YYYYMMDDHHmmss)
`totItemCnt`	integer	Total number of items
`taxblAmtA` through `taxblAmtE`	number	Taxable amount per tax type
`taxAmtA` through `taxAmtE`	number	Tax amount per tax type
`totTaxblAmt`	number	Total taxable amount
`totTaxAmt`	number	Total tax amount
`totAmt`	number	Total amount including tax
`itemList`	array	List of items in the sale

Use Case

This endpoint is used to lookup supplier sales that are registered in the KRA system but not yet recorded as purchases on your side. You can:

Call this endpoint periodically to check for new supplier sales
Review the returned sales transactions
Use the data to create purchase transactions via the POST /api/v1/purchases endpoint

Code Example


// Fetch available purchase sales
const response = await axios.post(`${baseURL}/purchases/sales`, {
  branch_id: '00'
}, {
  headers: { Authorization: `Bearer ${apiKey}` }
});
 
const availableSales = response.data.data;
 
// Process and register as purchases
for (const sale of availableSales) {
  const purchaseData = {
    branch_id: '00',
    invoice_no: `PINV-${Date.now()}`,
    purchase_date: sale.regDt.slice(0, 8),
    purchase_time: sale.regDt.slice(8, 14),
    supplier_tin: sale.spplrTin,
    supplier_name: sale.spplrNm,
    supplier_invoice_no: sale.spplrInvcNo,
    items: sale.itemList.map((item, index) => ({
      item_sequence: index + 1,
      item_code: item.itemCd,
      item_name: item.itemNm,
      quantity: item.qty,
      unit_price: item.prc,
      supply_amount: item.splyAmt,
      tax_type: item.taxTyCd,
      tax_amount: item.taxAmt,
      total_amount: item.totAmt
    }))
  };
 
  await axios.post(`${baseURL}/purchases`, purchaseData, {
    headers: { Authorization: `Bearer ${apiKey}` }
  });
}

Error Responses

400 Bad Request


{
  "status": "error",
  "message": "Invalid request data",
  "error": "The supplier_tin field is required."
}

422 Unprocessable Entity


{
  "status": "error",
  "message": "Purchase transaction processing failed",
  "error": "VSCU connection timeout",
  "transaction_id": "..."
}

404 Not Found


{
  "status": "error",
  "message": "Purchase transaction not found"
}

Code Examples

JavaScript


const axios = require('axios');
 
const apiKey = process.env.CTAX_API_KEY;
const baseURL = 'https://c-ushuru.com/api/v1';
 
const purchaseData = {
  branch_id: '00',
  invoice_no: `PINV-${Date.now()}`,
  purchase_date: new Date().toISOString().slice(0,10).replace(/-/g, ''),
  purchase_time: new Date().toTimeString().slice(0,8).replace(/:/g, ''),
  supplier_tin: '987654321',
  supplier_name: 'ABC Suppliers Ltd',
  supplier_invoice_no: 'SUP-INV-2024-001',
  payment_type: '01',
  items: [
    {
      item_sequence: 1,
      item_code: 'ITEM001',
      item_name: 'Product A',
      quantity: 10,
      unit_price: 5000,
      supply_amount: 50000,
      tax_type: 'A',
      tax_rate: 16,
      tax_amount: 8000,
      total_amount: 58000
    }
  ]
};
 
const response = await axios.post(`${baseURL}/purchases`, purchaseData, {
  headers: { Authorization: `Bearer ${apiKey}` }
});

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',
    ],
]);
 
$data = [
    'branch_id' => '00',
    'invoice_no' => 'PINV-' . time(),
    'purchase_date' => date('Ymd'),
    'purchase_time' => date('His'),
    'supplier_tin' => '987654321',
    'supplier_name' => 'ABC Suppliers Ltd',
    'supplier_invoice_no' => 'SUP-INV-2024-001',
    'payment_type' => '01',
    'items' => [
        [
            'item_sequence' => 1,
            'item_code' => 'ITEM001',
            'item_name' => 'Product A',
            'quantity' => 10,
            'unit_price' => 5000,
            'supply_amount' => 50000,
            'tax_type' => 'A',
            'tax_rate' => 16,
            'tax_amount' => 8000,
            'total_amount' => 58000,
        ],
    ],
];
 
$response = $client->post('purchases', ['json' => $data]);

Python


import requests
from datetime import datetime
import os
 
api_key = os.environ['CTAX_API_KEY']
base_url = 'https://c-ushuru.com/api/v1'
headers = {'Authorization': f'Bearer {api_key}'}
 
now = datetime.now()
purchase_data = {
    'branch_id': '00',
    'invoice_no': f'PINV-{int(datetime.timestamp(now))}',
    'purchase_date': now.strftime('%Y%m%d'),
    'purchase_time': now.strftime('%H%M%S'),
    'supplier_tin': '987654321',
    'supplier_name': 'ABC Suppliers Ltd',
    'supplier_invoice_no': 'SUP-INV-2024-001',
    'payment_type': '01',
    'items': [
        {
            'item_sequence': 1,
            'item_code': 'ITEM001',
            'item_name': 'Product A',
            'quantity': 10,
            'unit_price': 5000,
            'supply_amount': 50000,
            'tax_type': 'A',
            'tax_rate': 16,
            'tax_amount': 8000,
            'total_amount': 58000
        }
    ]
}
 
response = requests.post(f'{base_url}/purchases', json=purchase_data, headers=headers)

Best Practices

Validate Supplier Information - Ensure supplier TIN and name are correct
Match Supplier Invoice - Record the exact supplier invoice number
Verify Calculations - Double-check all amounts match supplier invoice
Store Receipts - Keep VSCU receipt numbers for audit trails
Regular Reconciliation - Reconcile purchase records with suppliers regularly

Transactions API - View and manage transactions
Stock Management - Update stock after purchases
Codes API - Get tax types and payment types

Purchases API

Overview

Create Purchase

Create Purchase

Field Descriptions

Main Fields

Item Fields

Response

Get Purchase Details

Get Purchase Details

Response

Search Purchases

Search Purchases

Query Parameters

Response

Fetch Purchase Sales

Fetch Purchase Sales

Request Body

Response

Response Fields

Use Case

Code Example

Error Responses

400 Bad Request

422 Unprocessable Entity

404 Not Found

Code Examples

JavaScript

PHP

Python

Best Practices

Related Endpoints