🖥️ Dashboard 📚 Support 🗞️ News 🇰🇪 KE Docs
📖 Guides
⚙️ API Reference
📋 Changelog
Documentation · v2.0

Getting Started: ProTax API and KRA eTIMS

ProTax API Hub contains guides and API reference pages for further understanding, equipping you on how to integrate with the KRA eTIMS System.

🧭
Navigation

New here? Learn how to navigate our pages.

💬
Support

Get stuck? Email us or chat via the ProTax chat widget.

📋
KRA eTIMS Integration

Understand how ProTax connects your system to KRA eTIMS effortlessly.

🔌
ProTax API Reference

Interactive API endpoints — get your X-API-Key and start testing now.

Electronic Tax Invoicing in Kenya

African countries are rapidly digitising tax systems by adopting electronic tax invoicing and reporting. Kenya's tax authority, KRA (Kenya Revenue Authority), operates eTIMS — electronic Tax Information Management System — which became mandatory on 1 January 2024 under the Finance Act, 2023.

Introduction to KRA eTIMS & ProTax

What is KRA eTIMS?

eTIMS is KRA's transformative e-invoicing platform. Every sale made by a registered taxpayer must be reported to eTIMS in real-time for digital signing and fiscal stamping before a tax invoice can be issued.

What is ProTax?

ProTax is a licensed eTIMS OSCU integrator — a suite of solutions enabling taxpayers to generate, digitally sign, and transmit compliant invoices directly to KRA eTIMS without manual platform-hopping.

More about ProTax

  • ProTax App — Compatible with Android and Android POS devices
  • ProTax Dashboard — Responsive web-browser desktop application
  • ProTax API — System-to-system integration, fully automated
  • ProTax Plugins — Quickbooks, Sage Online, WooCommerce, Odoo, and more

API Feature Highlights

RESTful API
OpenAPI / Swagger
Signed JWTs
Webhook Callbacks
Offline Mode
Reverse Invoicing

We invite you to use the ProTax API to integrate your system with eTIMS — for automation and elimination of platform-hopping.

ProTax and eTIMS — How it Works

OSCU — Online Sales Control Unit. ProTax is licenced as an eTIMS OSCU integrator. Every invoice is transmitted in real-time to KRA's eTIMS server for digital signing and metadata stamping before delivery to the buyer.

The ProTax team has also developed Offline URLs, Callback URLs, and other resilience features providing VSCU-like reliability without a local device.

🥇 ProTax is a leading KRA & ODPC-approved eTIMS integrator.

✅ ProTax is built with the best industry practices and to the highest security standards.

🕐Updated March 2026
Next PageHow to use this site
→
Documentation

How to use this site

A quick guide to navigating the ProTax API Hub — understanding sections and finding what you need fast.

Site Structure

  • Guides — Conceptual explanations, how-tos, references, and FAQs (you are here)
  • API Reference — Interactive endpoint documentation with live Try-It functionality
  • Changelog — Version history, breaking changes, and new features

Sidebar Navigation

The left sidebar organises all content by category. Click any link to navigate instantly — no page reload needed.

▶Documentation

Getting started and site navigation pages — ideal for first-time visitors.

▶How-To

Step-by-step task guides: create your first eTIMS invoice, authenticate with the API, and configure your environment.

▶Reference

Detailed attribute tables, classification codes, error codes, and data schemas for building accurate API requests.

▶Features

Deep-dives on ProTax-specific capabilities: Callback URLs, Offline URLs, Reverse Invoicing, and Invoice Verification.

▶Plugins

Configuration guides for ProTax plugins: Quickbooks, Sage Online, WooCommerce, and Odoo.

Getting Support

💬 Need help? Visit sandbox.protax.co.ke/support or use the ProTax chat widget on any page.

←
PreviousGetting Started
NextCreate an eTIMS invoice
→
How-To

Create an eTIMS invoice

Learn how to generate a KRA eTIMS-compliant invoice through ProTax — from item setup to signed invoice delivery.

Prerequisites

Step-by-Step: Create an Invoice via the API

  1. 1

    Authenticate

    Include your X-API-Key in every request header: X-API-Key: your_key_here

  2. 2

    Register / verify your items

    Items must be pre-registered in ProTax with a valid item class code and unit of measure. See Item attributes.

  3. 3

    POST your invoice

    Submit a POST /invoices request with your customer details, line items, tax breakdown, and invoice metadata.

  4. 4

    Receive the signed invoice

    ProTax transmits your invoice to KRA eTIMS. On success, you receive a signed invoice with a KRA Control Unit Invoice Number (CUIN) and QR code.

  5. 5

    Deliver to customer

    Print or email the signed invoice. The embedded QR code allows buyers to verify authenticity at sandbox.protax.co.ke/verify.

Invoice Types Supported

TypeDescriptionEndpoint
Sales InvoiceStandard B2B or B2C tax invoicePOST /invoices
Credit NoteReversal/adjustment of a previously issued invoicePOST /invoices/credit-note
Debit NoteSupplementary charge on a prior invoicePOST /invoices/debit-note
Proforma InvoiceQuote/estimate (not fiscally stamped)POST /invoices/proforma

🔗 Use Callback URLs to receive real-time webhooks when KRA processes your invoice. See Callback URLs.

←
PreviousHow to use this site
NextStart using the ProTax API
→
How-To

Start using the ProTax API

Everything you need to authenticate, make your first request, and go live with the ProTax Kenya API.

Prerequisites

  • Active ProTax account at sandbox.protax.co.ke
  • KRA-registered PIN with eTIMS onboarding complete
  • Generated X-API-Key (Test or Live) from the ProTax Dashboard

Base URLs

EnvironmentBase URL
Sandbox / Testhttps://sandbox.protax.co.ke/api/v2
Production / Livehttps://api.protax.co.ke/v2

Authentication

All requests require an X-API-Key header. Keys are environment-specific — your Test key only works against the sandbox URL.

⚠️ Never commit your API key to source control. Store it in environment variables or a secrets manager.

Making Your First Request

curl -X GET \

  https://sandbox.protax.co.ke/api/v2/health \

  -H "X-API-Key: your_test_key"

Rate Limits

PlanRequests / minRequests / day
Sandbox605,000
Starter12050,000
Business300Unlimited
←
PreviousCreate an eTIMS invoice
NextAPI Details
→
Reference

ProTax API Details

Technical overview of the ProTax Kenya API — standards, versioning, error handling, and available endpoints.

API Standards

RESTful architecture
OpenAPI 3.0 spec
JSON payloads
JWT authentication
TLS 1.2+ only
ISO 8601 dates

Endpoint Overview

MethodEndpointDescription
GET/healthAPI health check & version
POST/invoicesSubmit a new eTIMS invoice
GET/invoices/{id}Retrieve invoice by ID
GET/invoicesList all invoices (paginated)
POST/invoices/credit-noteSubmit a credit note
GET/itemsList registered items
POST/itemsRegister a new item
PUT/items/{id}Update an item
GET/stockGet stock balances
POST/stock/adjustmentSubmit a stock adjustment
GET/customersList customers (PIN lookup)
POST/webhooksRegister a callback URL
←
PreviousStart using the API
NextItem attributes
→
Reference

Item attributes

All fields required and optional when registering or updating an item in ProTax for eTIMS invoicing.

Required Fields

FieldTypeDescription
item_namestringName/description of the item or service
item_class_codestringKRA HS classification code (8–10 digits). See Classification Table
packaging_unit_codestringUnit of packaging (e.g. BX, BG, NX)
quantity_unit_codestringUnit of quantity (e.g. KGS, PCS, NX, HUR)
tax_type_codestringVAT type: A=16%, B=8%, C=0%, D=Exempt
unit_pricedecimalDefault selling price (KES, excluding VAT)

Optional Fields

FieldTypeDescription
barcodestringProduct barcode (EAN-13 or custom)
origin_countrystringISO 3166-1 alpha-2 country code of origin
descriptionstringLonger item description
custom_fieldsobjectKey-value pairs for internal metadata

💡 Items must be registered in ProTax before they can be referenced in invoice line items. Registration is instant — no KRA approval required for item setup.

←
PreviousAPI Details
NextItem Classification Table
→
Reference

Items: Item Classification Table

KRA eTIMS uses the Harmonised System (HS) classification for all goods and services.

⚠️ Using an incorrect HS code may result in invoice rejection by KRA eTIMS. When unsure, consult the FAQ or contact ProTax support.

Common Classification Codes

HS CodeCategoryDescriptionVAT Rate
99111001Services – GeneralProfessional / consulting services16%
99111002Services – ITSoftware, SaaS, and IT services16%
99111003Services – TransportFreight and logistics services16%
99111004Services – FinanceFinancial services16%
99111005Services – HealthHealthcare and medical services16%
99111006Services – EducationEducation and training16%
99111007Services – MarketingMarketing, advertising, and media16%
99111008Services – ConstructionConstruction and engineering services16%
99111009Services – Real EstateReal estate and property management16%
04011000DairyMilk and cream (fat ≤ 1%)0%
10011000CerealsDurum wheat0%
30021000PharmaVaccines for human medicineExempt
84713000ElectronicsLaptop/portable computers16%
87032100VehiclesMotor cars (1000cc–1500cc)16%
22021000BeveragesWaters / mineral waters (sweetened)16%
61051000ClothingMen's shirts (cotton)16%

For the full KRA HS Code list, visit sandbox.protax.co.ke/docs/hs-codes or use our HS code lookup FAQ.

←
PreviousItem attributes
NextInvoice attributes
→
Reference

Invoice attributes (Sales / Credit Notes)

All fields for the POST /invoices and POST /invoices/credit-note endpoints.

Invoice Header

FieldTypeRequiredDescription
invoice_numberstring✅Your internal invoice reference
invoice_dateISO 8601✅Date of transaction (YYYY-MM-DD)
customer_pinstringOptionalBuyer's KRA PIN (B2B — enables input tax credit)
customer_namestring✅Buyer's name
customer_addressstringOptionalBuyer's physical or postal address
payment_type_codestring✅01=Cash, 02=Credit, 03=Cheque, 04=Mobile Money
sales_type_codestring✅C=Copy, T=Training (test), N=Normal
currency_codestring✅ISO 4217 code — KES for Kenya Shilling
exchange_ratedecimalIf foreignExchange rate to KES (required when currency ≠ KES)

Line Items Array

FieldTypeDescription
item_idstringProTax item ID (from GET /items)
quantitydecimalNumber of units sold
unit_pricedecimalPrice per unit excluding VAT (KES)
discount_ratedecimalDiscount percentage (0–100)
tax_type_codestringOverrides item default: A, B, C, or D

💡 For Credit Notes, include the original_invoice_id field referencing the ProTax ID of the invoice being reversed.

←
PreviousClassification Table
NextTransaction status
→
Reference

Transaction status

All possible states for a ProTax invoice and what each one means.

Status Codes

SIGNED
Invoice successfully signed by KRA eTIMS. A CUIN and QR code have been assigned.
PROCESSING
Invoice has been submitted and is awaiting a response from KRA eTIMS.
QUEUED
Invoice is in the ProTax queue, pending submission to KRA. Common when using Offline URLs.
PENDING_RETRY
Submission failed but is scheduled for automatic retry.
REJECTED
KRA eTIMS rejected the invoice. Check the rejection_reason field in the response.
FAILED
A system error occurred. Contact ProTax support with the invoice ID.
CANCELLED
Invoice was cancelled before eTIMS submission (only possible from QUEUED state).
REVERSED
Invoice has been reversed via a Credit Note. The original invoice remains in the system.

Polling vs Webhooks

Check invoice status by calling GET /invoices/{id} or configure a Callback URL to receive push notifications when status changes occur.

←
PreviousInvoice attributes
NextErrors
→
Reference

Errors

ProTax uses standard HTTP status codes and descriptive error bodies to help you debug issues quickly.

HTTP Status Codes

CodeMeaning
200Success
201Resource created (invoice submitted)
400Bad Request — invalid payload or missing fields
401Unauthorized — missing or invalid X-API-Key
403Forbidden — key doesn't have permission for this action
404Not Found — resource doesn't exist
422Unprocessable — KRA eTIMS rejected the invoice
429Rate limit exceeded
500Internal server error — contact support

ProTax Error Codes

PTX-001

Invalid item_class_code

The HS code provided does not exist in the KRA classification table. Check the Classification Table.

PTX-002

Duplicate invoice_number

An invoice with this internal reference already exists. Use a unique number per transaction.

PTX-003

KRA eTIMS timeout

KRA's server did not respond in time. The invoice will be retried automatically. Check status via Transaction status.

PTX-004

Invalid customer_pin

The buyer's KRA PIN is not registered or is formatted incorrectly. B2C invoices can omit this field.

PTX-005

Tax calculation mismatch

The submitted tax totals don't match the line item calculation. Let the API compute totals automatically.

PTX-006

Item not registered

The referenced item_id does not exist. Register the item first via POST /items.

←
PreviousTransaction status
NextStock: Data Attributes
→
Reference

Stock: Data Attributes

Fields for reporting stock movements and adjustments to KRA eTIMS via ProTax.

📦 KRA eTIMS requires stock balance reporting for VAT-registered traders dealing in goods. ProTax automates this from your invoice line items.

Stock Adjustment Fields

FieldTypeRequiredDescription
item_idstring✅ProTax item ID
adjustment_typestring✅IN=stock in, OUT=stock out, DAMAGE=write-off, RETURN=supplier return
quantitydecimal✅Units adjusted (always positive)
adjustment_dateISO 8601✅Date of the stock movement
referencestringOptionalGRN number, delivery note, or internal reference
unit_costdecimalOptionalPurchase cost per unit (KES, used for stock valuation)
notesstringOptionalReason for adjustment
←
PreviousErrors
NextFAQ
→
FAQ

Frequently Asked Questions

Common questions about ProTax, KRA eTIMS integration, and the ProTax API.

▶Do I need a KRA PIN to use ProTax?

Yes. You must have a valid KRA PIN and have completed eTIMS onboarding with KRA before your ProTax account can go live. You can use the Sandbox environment for testing without full onboarding.

▶What is the difference between OSCU and VSCU?

OSCU (Online Sales Control Unit) requires real-time internet connectivity to KRA's eTIMS server. VSCU (Virtual Sales Control Unit) operates locally and syncs periodically. ProTax is an OSCU provider but offers Offline URLs and Callback URLs to provide resilience similar to VSCU.

▶Can I issue invoices in foreign currency?

Yes — set the currency_code field to the appropriate ISO 4217 code. However, KRA requires the tax amounts to also be reported in KES. Include the exchange_rate field in your payload.

▶How long does KRA take to sign an invoice?

Typically under 3 seconds. During peak periods or KRA maintenance windows, it may take longer. Use Callback URLs to be notified asynchronously rather than polling.

▶What happens if KRA eTIMS is down?

ProTax queues invoices automatically and retries when connectivity is restored. Enable Offline URLs for guaranteed delivery even during extended outages. See Offline URLs.

▶Is ProTax suitable for B2C and B2B invoicing?

Yes — for B2B, include the buyer's customer_pin to enable input tax credit for your customer. For B2C, this field is optional.

▶How do I issue a credit note to reverse an invoice?

Submit a POST /invoices/credit-note with the original_invoice_id of the invoice you want to reverse. See Reverse Invoicing.

←
PreviousStock attributes
NextCallback URLs
→
FAQ

Which item class code should I use?

Guidance on selecting the correct KRA HS classification code for your goods and services.

For Services

All service-based businesses should use the 9911xxxx series. The most common codes are:

  • 99111001 — General professional services (consulting, legal, accounting)
  • 99111002 — IT and software services (SaaS, hosting, support)
  • 99111003 — Transport and logistics
  • 99111004 — Financial services
  • 99111005 — Healthcare and medical services
  • 99111006 — Education and training
  • 99111007 — Marketing, advertising, and media
  • 99111008 — Construction and engineering services
  • 99111009 — Real estate and property management

For Goods

Use the standard WCO Harmonised System (HS) code for your product category. Start from the 2-digit chapter (e.g. Chapter 84 for machinery) and narrow to the 8-digit subheading.

💡 Not sure? Use ProTax's built-in HS code search at sandbox.protax.co.ke/hs-search or contact support.

NextPackaging & quantity units
→
FAQ

Packaging & quantity units for services

Which unit codes to use when registering service-type items in ProTax.

Recommended Codes for Services

FieldRecommended CodeMeaning
packaging_unit_codeNXNo packaging (services)
quantity_unit_codeNXNot applicable (billed as a lump sum)
quantity_unit_codeHURHours (for time-based billing)
quantity_unit_codeDAYDays (for daily-rate services)
quantity_unit_codeMONMonths (for subscriptions)
←
PreviousItem class codes
Features

Callback URLs

Receive real-time webhook notifications from ProTax when your invoices are processed, signed, or rejected by KRA eTIMS.

How Callbacks Work

When you register a Callback URL, ProTax sends an HTTP POST request to your endpoint whenever an invoice status changes. This eliminates the need to poll GET /invoices/{id} repeatedly.

  1. 1

    Register your URL

    Submit a POST /webhooks request with your endpoint URL and the events you want to subscribe to.

  2. 2

    Receive the webhook

    ProTax POSTs a JSON payload to your URL within seconds of the status change.

  3. 3

    Verify the signature

    Each webhook includes an X-ProTax-Signature header. Verify it using your webhook secret to ensure authenticity.

  4. 4

    Respond with 200

    Your endpoint must return a 200 OK within 10 seconds. Failed deliveries are retried up to 5 times with exponential backoff.

Available Events

EventTriggered when
invoice.signedKRA eTIMS successfully signs the invoice
invoice.rejectedKRA eTIMS rejects the invoice
invoice.failedA system error prevents submission
invoice.queuedInvoice is queued (offline mode)
credit_note.signedCredit note successfully processed
←
PreviousFAQ
NextOffline URLs
→
Features

Offline URLs

Issue invoices even when internet connectivity is unavailable — ProTax queues them and transmits to KRA eTIMS automatically when connectivity is restored.

What are Offline URLs?

Offline URLs allow ProTax to accept invoice submissions and return a provisional response even when KRA eTIMS is unreachable. The invoice is stored securely in ProTax's queue and submitted to KRA as soon as connectivity is restored.

✅ Your customer receives a provisional receipt immediately. Once KRA signs the invoice, the receipt is automatically upgraded to a full fiscal invoice.

Enabling Offline Mode

Set the offline_mode flag to true in your POST /invoices request body, or enable it globally in your ProTax Dashboard settings.

Online vs Offline Mode

FeatureOnline ModeOffline Mode
Requires internet✅ Yes❌ No (queue locally)
KRA sign time~1–3 secondsOn reconnection
CUIN returnedImmediatelyAfter reconnection
Provisional receipt—✅ Yes
Risk of rejectionImmediate feedbackDeferred feedback
←
PreviousCallback URLs
NextReverse Invoicing
→
Features

Reverse Invoicing

Issue KRA eTIMS-compliant credit notes to reverse or partially adjust previously signed invoices.

When to use a Credit Note

  • Goods returned by the buyer
  • Overcharge correction on a prior invoice
  • Service cancellation post-invoicing
  • Pricing dispute resolution

⚠️ Once an invoice is signed by KRA eTIMS, it cannot be deleted or edited. You must issue a Credit Note to reverse it. KRA tracks the link between the original invoice and the credit note.

Submitting a Credit Note

POST /invoices/credit-note

{

  "original_invoice_id": "inv_abc123",

  "reason": "Goods returned",

  "items": [...]

}

A full reversal credits all line items. A partial reversal only credits the specified items and quantities.

←
PreviousOffline URLs
NextInvoice Verification
→
Features

Invoice Verification

Allow buyers and auditors to verify the authenticity of ProTax-issued eTIMS invoices using the embedded QR code.

How Verification Works

Every signed ProTax invoice contains a KRA-issued QR code. Scanning this code or entering the CUIN at the verification portal confirms that the invoice was legitimately stamped by KRA eTIMS.

Verification Methods

📱
QR Code Scan

Scan the QR code on the printed or PDF invoice using any QR reader. Redirects to the KRA eTIMS verification page.

🔍
Online Portal

Enter the CUIN at sandbox.protax.co.ke/verify to look up any invoice by number.

⚙️
API Verification

Call GET /invoices/{id}/verify to programmatically check invoice validity in your own system.

🏛️
KRA Portal

KRA's own eTIMS portal also supports CUIN lookup for taxpayers and auditors.

←
PreviousReverse Invoicing
NextQuickbooks Plugin
→
Plugins

ProTax Quickbooks Plugin

Automatically sync Quickbooks Online invoices to KRA eTIMS via ProTax — zero manual effort.

How it works

The ProTax Quickbooks plugin connects your Quickbooks Online account to ProTax. Every time you create and approve an invoice in Quickbooks, it is automatically submitted to KRA eTIMS through ProTax and the signed CUIN is written back to your Quickbooks invoice as a memo.

  1. 1

    Install from Quickbooks App Store

    Search "ProTax eTIMS" in the Quickbooks App Store and click Connect.

  2. 2

    Authorise ProTax

    Log in to your ProTax account and grant access. Your X-API-Key is configured automatically.

  3. 3

    Map your products

    Map each Quickbooks product/service to its ProTax item (HS code, tax type, unit). This only needs to be done once.

  4. 4

    Go live

    Approve an invoice in Quickbooks — ProTax handles the rest.

✅ Quickbooks invoices approved in Quickbooks Online are signed by KRA eTIMS within seconds via ProTax.

←
PreviousInvoice Verification
NextSage Online Plugin
→
Plugins

ProTax Sage Online Plugin

Connect Sage Business Cloud Accounting to KRA eTIMS through ProTax for automated fiscal compliance.

Supported Sage Products

  • Sage Business Cloud Accounting
  • Sage 50cloud (via API bridge)
  • Sage 200 (Enterprise — contact support)
  1. 1

    Download the ProTax Sage plugin

    Available at sandbox.protax.co.ke/plugins/sage.

  2. 2

    Configure your API credentials

    Enter your ProTax X-API-Key in the plugin settings page within Sage.

  3. 3

    Map products and tax codes

    Align Sage tax codes with ProTax tax type codes (A=16%, B=8%, C=0%, D=Exempt).

  4. 4

    Test in Sandbox

    Use the Sandbox environment to verify invoices are being signed correctly before switching to Live.

←
PreviousQuickbooks Plugin
NextWooCommerce Plugin
→
Plugins

ProTax WooCommerce Plugin

Automatically issue KRA eTIMS invoices for every WooCommerce order — seamlessly integrated into your checkout flow.

How it works

When a WooCommerce order is marked "Processing" or "Completed", the plugin automatically submits a fiscal invoice to KRA eTIMS via ProTax. The signed invoice PDF and QR code are attached to the WooCommerce order confirmation email.

Requirements

  • WordPress 6.0+ and WooCommerce 8.0+
  • Active ProTax account with a Live X-API-Key
  • WooCommerce products mapped to ProTax items (HS codes required)
  1. 1

    Install the plugin

    Download from sandbox.protax.co.ke/plugins/woocommerce and upload to WordPress Plugins.

  2. 2

    Configure

    Go to WooCommerce → ProTax Settings and enter your X-API-Key.

  3. 3

    Map products

    Add HS codes and unit codes to each WooCommerce product under the "ProTax eTIMS" tab in the product editor.

🛒 For high-volume stores, enable async invoice generation to avoid checkout delays. Invoices are queued and signed within seconds.

←
PreviousSage Plugin
NextMCP Integration
→
MCP Server

MCP Integration

Connect AI agents and tools to ProTax via the Model Context Protocol (MCP) — issue invoices, look up items, and check status using natural language.

What is MCP?

Model Context Protocol (MCP) is an open standard that allows AI assistants (Claude, Copilot, etc.) to securely connect to external services. The ProTax MCP server exposes ProTax API capabilities as MCP tools that AI agents can invoke directly.

✅ The ProTax MCP server is approved for use with Claude (Anthropic), GitHub Copilot, and other MCP-compatible AI assistants.

Available MCP Tools

ToolDescription
create_invoiceSubmit a new eTIMS invoice to KRA
get_invoiceRetrieve invoice details and signing status
list_invoicesList invoices with filters (date, status, customer)
create_credit_noteIssue a credit note against a prior invoice
get_itemsList registered items and their HS codes
lookup_hs_codeSearch for the correct HS code by description
get_stockGet current stock balances for an item
verify_invoiceCheck if a CUIN is valid and KRA-signed

Quick Setup

  1. 1

    Add ProTax MCP to your AI tool

    In Claude or your MCP-compatible client, add the server URL: https://mcp.protax.co.ke

  2. 2

    Authenticate

    Provide your ProTax X-API-Key when prompted by the MCP client.

  3. 3

    Start invoicing with AI

    Ask your AI assistant: "Create an eTIMS invoice for ABC Ltd for 5 hours of consulting at KES 10,000/hr."

←
PreviousWooCommerce Plugin