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

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

FieldTypeRequiredDescription
branch_idstringYesBranch identifier (bhf_id)
invoice_nostringYesYour unique purchase invoice number
purchase_datestringYesDate in YYYYMMDD format
purchase_timestringYesTime in HHMMSS format
supplier_tinstringYesSupplier’s TIN number
supplier_namestringYesSupplier’s business name
supplier_bhf_idstringNoSupplier’s branch ID
supplier_invoice_nostringYesSupplier’s invoice number
purchase_statusstringNoPurchase status code
purchase_typestringNoPurchase type (N=Normal, I=Import)
payment_typestringYesPayment type code (01=Cash, 02=Card, etc.)

Item Fields

FieldTypeRequiredDescription
item_sequenceintegerYesItem sequence number (1, 2, 3…)
item_codestringYesItem code
item_namestringYesItem name
bcdstringNoBarcode
package_unitstringNoPackage unit code
quantitynumberYesQuantity purchased
unit_pricenumberYesUnit price
supply_amountnumberYesSupply amount (qty × price)
discount_ratenumberNoDiscount rate (%)
discount_amountnumberNoDiscount amount
tax_typestringYesTax type (A, B, C, etc.)
tax_ratenumberYesTax rate (%)
tax_amountnumberYesTax amount
total_amountnumberYesTotal including tax

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

ParameterTypeRequiredDescription
branch_idstringNoFilter by branch
from_datestringNoStart date (YYYY-MM-DD)
to_datestringNoEnd date (YYYY-MM-DD)
invoice_nostringNoSearch by invoice number
supplier_namestringNoSearch by supplier name
statusstringNoFilter by status
per_pageintegerNoResults per page (max 100)
pageintegerNoPage 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
  }
}

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-tax.1809ltd.co.ke/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-tax.1809ltd.co.ke/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-tax.1809ltd.co.ke/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

  1. Validate Supplier Information - Ensure supplier TIN and name are correct
  2. Match Supplier Invoice - Record the exact supplier invoice number
  3. Verify Calculations - Double-check all amounts match supplier invoice
  4. Store Receipts - Keep VSCU receipt numbers for audit trails
  5. Regular Reconciliation - Reconcile purchase records with suppliers regularly
Last updated on
Sales APIStock API