eTIMS Purchases API

Submit purchase transactions to KRA eTIMS, track supplier invoices, and maintain purchase records for tax compliance.

Table of Contents

1. Overview
2. Submit Purchase
3. Get Purchase
4. List Purchases
5. Purchases Report
6. Status Codes

Overview

Required Scopes

Endpoint Summary

Submit Purchase

Submit a purchase transaction to KRA eTIMS. Records supplier invoice data for input VAT claims and compliance.

Endpoint: POST /api/etims/purchases/submit

Required Scope: etims:write

Request Body:

Purchase Types

Item Fields

Request:

curl -X POST \
  https://yourtenant.salami.dgl.co.ke/api/etims/purchases/submit \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "invoice_number": "SUP-INV-2026-001",
    "invoice_date": "2026-03-25",
    "supplier_tin": "P051234567B",
    "supplier_name": "Supplier Ltd",
    "purchase_type": "N",
    "payment_type": "02",
    "items": [
      {
        "item_seq": 1,
        "item_code": "RAW001",
        "item_name": "Raw Material A",
        "item_class_code": "72081000",
        "quantity": 100,
        "unit_price": 800.00,
        "tax_type": "B",
        "tax_rate": 16
      },
      {
        "item_seq": 2,
        "item_code": "RAW002",
        "item_name": "Raw Material B",
        "quantity": 50,
        "unit_price": 1200.00,
        "tax_type": "B",
        "tax_rate": 16
      }
    ]
  }'

Response:

{
  "success": true,
  "data": {
    "purchase_id": 456,
    "invoice_number": "SUP-INV-2026-001",
    "supplier_tin": "P051234567B",
    "supplier_name": "Supplier Ltd",
    "total_amount": 140000.00,
    "total_taxable_amount": 120689.66,
    "total_tax_amount": 19310.34,
    "tax_breakdown": {
      "B": {"taxable": 120689.66, "tax": 19310.34, "rate": 16}
    },
    "status": "submitted",
    "submitted_at": "2026-03-29T16:30:00Z"
  },
  "message": "Purchase submitted successfully"
}

Get Purchase

Retrieve details of a specific purchase.

Endpoint: GET /api/etims/purchases/{invoice_number}

Required Scope: etims:read

Request:

curl -X GET \
  https://yourtenant.salami.dgl.co.ke/api/etims/purchases/SUP-INV-2026-001 \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Response:

{
  "success": true,
  "data": {
    "id": 456,
    "invoice_number": "SUP-INV-2026-001",
    "invoice_date": "2026-03-25",
    "supplier_tin": "P051234567B",
    "supplier_name": "Supplier Ltd",
    "supplier_id": 12,
    "total_amount": 140000.00,
    "total_taxable_amount": 120689.66,
    "total_tax_amount": 19310.34,
    "purchase_type": "N",
    "payment_type": "02",
    "status": "approved",
    "items": [
      {
        "item_seq": 1,
        "item_code": "RAW001",
        "item_name": "Raw Material A",
        "quantity": 100,
        "unit_price": 800.00,
        "total": 80000.00,
        "tax_type": "B",
        "tax_amount": 11034.48
      },
      {
        "item_seq": 2,
        "item_code": "RAW002",
        "item_name": "Raw Material B",
        "quantity": 50,
        "unit_price": 1200.00,
        "total": 60000.00,
        "tax_type": "B",
        "tax_amount": 8275.86
      }
    ],
    "submitted_at": "2026-03-29T16:30:00Z"
  }
}

List Purchases

Retrieve all purchase transactions.

Endpoint: GET /api/etims/purchases

Required Scope: etims:read

Query Parameters:

Request:

curl -X GET \
  'https://yourtenant.salami.dgl.co.ke/api/etims/purchases?start_date=2026-03-01&supplier_tin=P051234567B' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Response:

{
  "success": true,
  "data": [
    {
      "id": 456,
      "invoice_number": "SUP-INV-2026-001",
      "supplier_tin": "P051234567B",
      "supplier_name": "Supplier Ltd",
      "total_amount": 140000.00,
      "total_tax_amount": 19310.34,
      "status": "approved",
      "submitted_at": "2026-03-29T16:30:00Z"
    }
  ],
  "pagination": {
    "total": 15,
    "per_page": 50,
    "current_page": 1,
    "last_page": 1
  }
}

Purchases Report

Get aggregated purchases summary for a date range.

Endpoint: GET /api/etims/reports/purchases

Required Scope: etims:read

Query Parameters:

Request:

curl -X GET \
  'https://yourtenant.salami.dgl.co.ke/api/etims/reports/purchases?start_date=2026-03-01&end_date=2026-03-31' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Response:

{
  "success": true,
  "data": {
    "period": {
      "start_date": "2026-03-01",
      "end_date": "2026-03-31"
    },
    "summary": {
      "total_purchases": 15,
      "total_amount": 850000.00,
      "total_taxable_amount": 732758.62,
      "total_tax_amount": 117241.38,
      "unique_suppliers": 8
    }
  }
}

Status Codes

Best Practices

1. Verify supplier TIN -- Use PIN Validation to verify supplier PINs
2. Match supplier invoices -- Ensure the invoice number matches the supplier's actual invoice
3. Record all purchases -- Submit all taxable purchases for accurate input VAT claims
4. Supplier management -- Use the Suppliers API to maintain a supplier directory
5. Reconcile regularly -- Compare eTIMS purchase records with your accounting system

Related Documentation

• eTIMS Sales -- Submit sales
• eTIMS Items -- Register purchased items
• eTIMS Customers & Suppliers -- Manage supplier records

Back to: eTIMS Sales | eTIMS Items