API Reference – KRA eTIMS Integration

KEY X-API-Key Header Required on every request ▼

All API requests must include your X-API-Key in the HTTP header. Generate keys from your ProTax Dashboard under Settings → API Keys. Test keys are prefixed ptx_test_ and Live keys ptx_live_.

cURL

curl -X GET \
  https://sandbox.protax.co.ke/api/v2/health \
  -H "X-API-Key: ptx_test_your_key_here"

429 Rate limits by plan Sandbox · Starter · Business ▼

60

Sandbox

req / min · 5,000 / day

120

Starter

req / min · 50,000 / day

300

Business

req / min · Unlimited

When rate-limited, the API returns HTTP 429 with a Retry-After header indicating seconds to wait.

GET /health API health check & version ▼

Returns the current API status and version. Use this endpoint to verify your key is valid and the service is reachable before sending production invoices.

Response

Try it

JSON · 200 OK

{
  "status": "ok",
  "version": "2.0.1",
  "environment": "sandbox",
  "kra_etims_status": "operational",
  "timestamp": "2026-04-12T08:00:00Z"
}

Try it — GET /health

X-API-Key

● 200 OK

Response

POST /invoices Submit a new eTIMS invoice to KRA ▼

Submits a new sales invoice to KRA eTIMS for digital signing and fiscal stamping. Returns a signed invoice with a CUIN and QR code on success.

Body params

Request

Response

Try it

Field	Type	Required	Description
invoice_number	string	Required	Your internal invoice reference. Must be unique per account.
invoice_date	ISO 8601	Required	Transaction date in `YYYY-MM-DD` format.
customer_name	string	Required	Buyer's full name or company name.
customer_pin	string	Optional	Buyer's KRA PIN for B2B invoices. Enables input tax credit.
payment_type_code	string	Required	`01`=Cash · `02`=Credit · `03`=Cheque · `04`=Mobile Money
sales_type_code	string	Required	`N`=Normal · `C`=Copy · `T`=Training (sandbox)
currency_code	string	Required	ISO 4217 code. Use `KES` for Kenya Shilling.
exchange_rate	decimal	If foreign	Rate to KES. Required when `currency_code` ≠ `KES`.
items	array	Required	Array of line items. Each must include `item_id`, `quantity`, `unit_price`.
offline_mode	boolean	Optional	Set `true` to queue invoice if KRA eTIMS is unreachable.

cURL · POST /invoices

curl -X POST \
  "https://sandbox.protax.co.ke/api/v2/invoices" \
  -H "X-API-Key: ptx_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_number": "INV-2026-001",
    "invoice_date": "2026-04-12",
    "customer_name": "Acme Ltd",
    "customer_pin": "P051234567A",
    "payment_type_code": "01",
    "sales_type_code": "N",
    "currency_code": "KES",
    "items": [
      {
        "item_id": "itm_abc123",
        "quantity": 5,
        "unit_price": 10000,
        "tax_type_code": "A"
      }
    ]
  }'

JSON · 201 Created

{
  "id": "inv_xyz789",
  "invoice_number": "INV-2026-001",
  "status": "SIGNED",
  "cuin": "KRA20260412001234",
  "qr_code_url": "https://api.protax.co.ke/qr/inv_xyz789",
  "signed_at": "2026-04-12T08:01:23Z",
  "totals": {
    "subtotal": 50000,
    "tax_amount": 8000,
    "total": 58000
  }
}

201	Invoice signed and returned with CUIN.
400	Invalid payload — missing required fields.
401	Invalid or missing `X-API-Key`.
422	KRA eTIMS rejected the invoice. Check `rejection_reason`.
500	Internal error — contact ProTax support with invoice ID.

Try it — POST /invoices

X-API-Key

Invoice number

Customer name

Customer PIN (optional)

Payment type

Currency

● 201 Created

Response

GET /invoices List all invoices (paginated) ▼

Returns a paginated list of all invoices for your account. Filter by status, date range, or customer PIN.

Query params

Response

Parameter	Type	Description
status	string	Filter: `SIGNED`, `PROCESSING`, `REJECTED`, `QUEUED`
from_date	ISO 8601	Start date `YYYY-MM-DD`
to_date	ISO 8601	End date `YYYY-MM-DD`
customer_pin	string	Filter by buyer KRA PIN
page	integer	Page number (default: 1)
per_page	integer	Results per page (default: 20, max: 100)

JSON · 200 OK

{
  "data": [
    {
      "id": "inv_xyz789",
      "invoice_number": "INV-2026-001",
      "status": "SIGNED",
      "cuin": "KRA20260412001234",
      "total": 58000,
      "invoice_date": "2026-04-12"
    }
  ],
  "meta": {
    "total": 142,
    "page": 1,
    "per_page": 20,
    "total_pages": 8
  }
}

GET /invoices/{id} Retrieve invoice by ID ▼

Returns full details of a single invoice including status, CUIN, line items, and KRA response metadata.

cURL

curl -X GET \
  "https://sandbox.protax.co.ke/api/v2/invoices/inv_xyz789" \
  -H "X-API-Key: ptx_test_your_key"

POST /invoices/credit-note Reverse or partially adjust a signed invoice ▼

Issues a KRA eTIMS-compliant credit note against a previously signed invoice. A signed invoice cannot be edited — use this endpoint to reverse it fully or partially.

Body params

Request

Field	Type	Required	Description
original_invoice_id	string	Required	ProTax ID of the signed invoice to reverse.
reason	string	Required	Reason for reversal, e.g. `"Goods returned"`
items	array	Optional	Omit for full reversal. Include specific items for partial credit.

cURL · POST /invoices/credit-note

curl -X POST \
  "https://sandbox.protax.co.ke/api/v2/invoices/credit-note" \
  -H "X-API-Key: ptx_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "original_invoice_id": "inv_xyz789",
    "reason": "Goods returned by customer"
  }'

GET /items List all registered items ▼

Returns all items registered in your ProTax account including HS codes, tax types, and unit codes.

cURL

curl -X GET \
  "https://sandbox.protax.co.ke/api/v2/items" \
  -H "X-API-Key: ptx_test_your_key"

POST /items Register a new item ▼

Registers a new product or service in ProTax. Items must be registered before they can be referenced in invoice line items.

Body params

Request

Field	Type	Required	Description
item_name	string	Required	Name or description of the item or service.
item_class_code	string	Required	KRA HS classification code (8–10 digits).
packaging_unit_code	string	Required	e.g. `NX`, `BX`, `BG`
quantity_unit_code	string	Required	e.g. `NX`, `KGS`, `PCS`, `HUR`
tax_type_code	string	Required	`A`=16% · `B`=8% · `C`=0% · `D`=Exempt
unit_price	decimal	Required	Default price per unit in KES excluding VAT.

cURL · POST /items

curl -X POST \
  "https://sandbox.protax.co.ke/api/v2/items" \
  -H "X-API-Key: ptx_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "item_name": "IT Consulting Services",
    "item_class_code": "99111002",
    "packaging_unit_code": "NX",
    "quantity_unit_code": "HUR",
    "tax_type_code": "A",
    "unit_price": 10000
  }'

PUT /items/{id} Update an existing item ▼

Updates any field on a registered item. Pass only the fields you want to change — all others remain unchanged.

cURL · PUT /items/{id}

curl -X PUT \
  "https://sandbox.protax.co.ke/api/v2/items/itm_abc123" \
  -H "X-API-Key: ptx_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "unit_price": 12000 }'

GET /stock Get current stock balances ▼

Returns current stock balances for all items. Use the item_id query parameter to filter to a single item.

cURL

curl -X GET \
  "https://sandbox.protax.co.ke/api/v2/stock?item_id=itm_abc123" \
  -H "X-API-Key: ptx_test_your_key"

POST /stock/adjustment Submit a stock movement ▼

Records a stock movement. KRA eTIMS requires stock reporting for VAT-registered goods traders. Invoices auto-create OUT adjustments — use this for manual corrections and goods received.

Body params

Request

Field	Type	Required	Description
item_id	string	Required	ProTax item ID.
adjustment_type	string	Required	`IN` · `OUT` · `DAMAGE` · `RETURN`
quantity	decimal	Required	Units to adjust. Always positive.
adjustment_date	ISO 8601	Required	Date of the stock movement.
reference	string	Optional	GRN number, delivery note reference.
unit_cost	decimal	Optional	Purchase cost per unit in KES.

cURL · POST /stock/adjustment

curl -X POST \
  "https://sandbox.protax.co.ke/api/v2/stock/adjustment" \
  -H "X-API-Key: ptx_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "item_id": "itm_abc123",
    "adjustment_type": "IN",
    "quantity": 100,
    "adjustment_date": "2026-04-12",
    "unit_cost": 4500
  }'

GET /customers KRA PIN lookup & customer list ▼

Look up a buyer's KRA PIN to validate it before submitting a B2B invoice. Returns the registered business name associated with the PIN.

cURL

curl -X GET \
  "https://sandbox.protax.co.ke/api/v2/customers?pin=P051234567A" \
  -H "X-API-Key: ptx_test_your_key"

POST /webhooks Register a callback URL ▼

Registers a URL to receive webhook events when invoice status changes. ProTax retries failed deliveries up to 5 times with exponential backoff. Verify the X-ProTax-Signature header on your endpoint.

Body params

Events

Request

Field	Type	Required	Description
url	string	Required	HTTPS endpoint to receive webhook payloads.
events	array	Required	Array of event names to subscribe to.
secret	string	Optional	Secret used to sign the `X-ProTax-Signature` header.

Event	Triggered when
invoice.signed	KRA eTIMS successfully signs the invoice
invoice.rejected	KRA eTIMS rejects the invoice
invoice.failed	A system error prevents submission
invoice.queued	Invoice queued in offline mode
credit_note.signed	Credit note successfully processed

cURL · POST /webhooks

curl -X POST \
  "https://sandbox.protax.co.ke/api/v2/webhooks" \
  -H "X-API-Key: ptx_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.co.ke/webhooks/protax",
    "events": ["invoice.signed", "invoice.rejected"],
    "secret": "your_webhook_secret"
  }'

Plan	Mins	Price	/min
Starter	30	$3.00	$0.100
BasicBest	100	$8.00$10	$0.080
Pro	250	$17.50$22	$0.070
Business	600	$36.00$45	$0.060

Plan	Messages	Price	/msg
Starter	500	$5.00	$0.010
GrowthBest	2,000	$16.00$20	$0.008
Scale	10,000	$60.00$80	$0.006

Plan	Messages	Price	/msg
Basic	300	$4.50	$0.015
ProBest	1,500	$18.00$22	$0.012
Enterprise	5,000	$50.00$70	$0.010

ProTax Kenya API

Save Contact

Add to Conference