How to use this site

A quick guide to navigating the ProTax API Hub documentation.

Navigation

Use the sidebar on the left to jump between sections. Each section is organised into logical categories: Documentation, How-To guides, Reference pages, FAQ, Features, Plugins, and MCP.

Sidebar sections

• Documentation — Start here. Overviews and onboarding guides.
• How-To — Step-by-step task guides for common integrations.
• Reference — Detailed technical specs for API fields, statuses, and errors.
• FAQ — Answers to the most common questions from integrators.
• Features — Deep-dives on Callbacks, Offline mode, Reverse Invoicing, and Verification.
• Plugins — Ready-made integrations for popular accounting and e-commerce platforms.
• MCP Server — AI-native integration via the Model Context Protocol.

API Reference

For an interactive, try-it-now API explorer, visit the ProTax API Reference at sandbox.protax.co.ke/reference. You will need your X-API-Key from the dashboard.

Create an eTIMS Invoice

Walk through the full lifecycle of a KRA eTIMS invoice using the ProTax API.

Overview

Every taxable sale in Kenya must be reported to KRA eTIMS. ProTax handles the signing, stamping, and transmission — your system just needs to POST a structured invoice payload.

Step-by-step

1. 1

   Authenticate

   Include your X-API-Key header in every request. Obtain your key from the ProTax Dashboard.

2. 2

   Build the invoice payload

   Construct a JSON body with the required invoice and line-item fields. See Invoice attributes and Item attributes for the full field reference.

3. 3

   POST to /invoice

   Submit your payload to the POST /invoice endpoint. ProTax validates, signs, and forwards to KRA eTIMS synchronously.

4. 4

   Handle the response

   A successful response returns a transaction_id and cu_invoice_no (KRA fiscal number). Store both for your records.

5. 5

   Issue the tax invoice

   Print or email the invoice to the customer. It must include the KRA QR code and cu_invoice_no.

Start using the ProTax API

Get your API key, make your first request, and explore the sandbox environment.

Prerequisites

• A ProTax account — register free
• Your KRA PIN and eTIMS credentials
• An HTTP client (cURL, Postman, or your own application)

Get your API key

1. 1

   Log in to the Dashboard

   Visit sandbox.protax.co.ke and sign in.

2. 2

   Navigate to API Keys

   Go to Settings → API Keys and click Generate new key.

3. 3

   Copy the key

   Your X-API-Key is shown once. Copy it immediately and store it securely.

Make your first request

Test your key with a simple GET to the status endpoint:

ProTax API Details

Technical overview of the ProTax REST API — base URLs, authentication, versioning, and rate limits.

Base URL

All API requests are made to: https://api.protax.co.ke/v2

Sandbox (testing): https://sandbox-api.protax.co.ke/v2

Authentication

Every request must include your API key as a header:

Content type

All request and response bodies use JSON. Set Content-Type: application/json on all POST and PUT requests.

Versioning

The current API version is v2. Breaking changes will be released under a new version prefix. Previous versions are supported for a minimum of 12 months after a new version launches.

Rate limits

Endpoints summary

Item Attributes

Field-by-field reference for stock items used in invoice line items.

Required fields

Item Classification Table

KRA eTIMS item class codes used in the item_class_code field.

Invoice Attributes

Complete field reference for the invoice payload submitted to POST /invoice.

Header fields

Line item fields

Each invoice must contain at least one item in the items array. Each item shares the same fields as the Item attributes reference, plus:

Transaction Status

All possible status values returned in invoice and transaction responses.

Errors

HTTP status codes and error codes returned by the ProTax API.

HTTP status codes

Stock: Data Attributes

Fields for registering and managing stock items via the ProTax API.

Stock item fields

Frequently Asked Questions

Common questions from developers and businesses integrating with ProTax and KRA eTIMS.

Which item class code?

A practical guide to selecting the right KRA item_class_code for your products and services.

Goods vs Services

The first digit of the code tells you the category: 5xxx = Goods, 6xxx = Services. Start there.

Decision guide

• Selling physical products for consumption (food, drinks)? → 5010
• Selling electronics or appliances? → 5020
• Selling clothing, uniforms, fabric? → 5030
• Selling medicines, medical equipment? → 5040
• Selling fuel, oils, lubricants? → 5060
• Providing professional services (legal, consulting, accounting)? → 6010
• Transport, delivery, courier? → 6020
• Hotel, restaurant, events? → 6030
• Software, hosting, telecoms? → 6050
• Anything else (general goods)? → 5000
• Anything else (general services)? → 6000

Packaging & Quantity Units

Accepted values for pkg_unit_code and qty_unit_code fields.

Callback URLs

Receive real-time invoice status updates via webhooks instead of polling.

How it works

Register a publicly accessible HTTPS endpoint in your ProTax Dashboard. When an invoice status changes (e.g. PROCESSING → SUCCESS), ProTax will POST a JSON payload to your URL.

Callback payload

Retry policy

If your endpoint returns a non-2xx response, ProTax retries up to 5 times with exponential back-off: 1 min, 5 min, 15 min, 1 hr, 6 hr.

Offline URLs

Keep invoicing when KRA eTIMS is temporarily unreachable.

Overview

ProTax maintains an offline queue. When KRA eTIMS returns errors or is unreachable, invoices are queued locally (in ProTax's infrastructure) and automatically retransmitted when connectivity is restored. No changes to your integration code are required.

Offline invoice status

Queued invoices have status PENDING. Your system can poll GET /invoice/{id} or use Callback URLs to be notified when the status changes to SUCCESS.

Reverse Invoicing

Issue credit notes and debit notes against previously submitted eTIMS invoices.

When to reverse

• Customer returns goods after a sale
• Pricing error on an issued invoice
• Full or partial cancellation of a service

How to reverse

1. 1

   Locate the original invoice

   You need the original invoice's cu_invoice_no (KRA fiscal number) and your invoice_no.

2. 2

   Build the reversal payload

   Set invoice_type to CREDIT (return) or DEBIT (additional charge). Include original_cu_invoice_no in the payload.

3. 3

   POST to /invoice/reverse

   Submit to POST /invoice/reverse. A new cu_invoice_no is issued for the credit/debit note.

Invoice Verification

Allow buyers and auditors to verify the authenticity of any KRA eTIMS invoice.

QR code verification

Every stamped invoice includes a KRA-generated QR code. Scanning the QR code redirects to the KRA eTIMS verification portal, confirming the invoice's authenticity and fiscal details.

API verification

You can also verify programmatically via GET /invoice/verify/{cu_invoice_no}. The response confirms the invoice status, taxpayer PIN, and totals as recorded by KRA.

ProTax QuickBooks Plugin

Connect QuickBooks Online to KRA eTIMS with zero code changes.

Overview

The ProTax QuickBooks plugin automatically intercepts every invoice created in QuickBooks Online, submits it to KRA eTIMS via ProTax, and writes the KRA fiscal number back to the QuickBooks invoice as a custom field.

Installation

1. 1

   Install from the QuickBooks App Store

   Search for ProTax eTIMS in the Intuit App Store and click Get app now.

2. 2

   Connect your ProTax account

   Enter your ProTax API key and KRA PIN when prompted.

3. 3

   Map your products

   Assign KRA item class codes and tax types to your QuickBooks products/services.

ProTax Sage Online Plugin

Integrate Sage Business Cloud Accounting with KRA eTIMS seamlessly.

Overview

The ProTax Sage Online plugin syncs invoices from Sage Business Cloud to KRA eTIMS in real-time. Fiscal numbers are written back to Sage invoice notes automatically.

Requirements

• Sage Business Cloud Accounting subscription (Accounting or Accounting Plus)
• Active ProTax account with a valid API key
• KRA eTIMS credentials (PIN, branch)

ProTax WooCommerce Plugin

Automatically issue KRA eTIMS invoices for every WooCommerce order.

Overview

The ProTax WooCommerce plugin hooks into WooCommerce order processing. When an order moves to Processing or Completed, an eTIMS invoice is automatically submitted via ProTax and the fiscal number is attached to the order.

Installation

1. 1

   Download the plugin

   Download the ProTax WooCommerce plugin ZIP from your ProTax Dashboard under Plugins.

2. 2

   Install in WordPress

   Go to Plugins → Add New → Upload Plugin and upload the ZIP file.

3. 3

   Configure

   Navigate to WooCommerce → Settings → ProTax eTIMS and enter your API key.

MCP Integration

Use the ProTax MCP Server to issue eTIMS invoices directly from AI assistants like Claude.

What is MCP?

Model Context Protocol (MCP) is an open standard that allows AI assistants to call external tools and services. The ProTax MCP Server exposes ProTax API actions as MCP tools, enabling AI-native invoicing workflows.

Available tools

• create_invoice — Submit a new eTIMS invoice
• get_invoice — Retrieve invoice status and fiscal details
• list_stock — List registered stock items
• create_stock_item — Register a new product
• reverse_invoice — Issue a credit or debit note

Setup

1. 1

   Get your API key

   Obtain your X-API-Key from the ProTax Dashboard.

2. 2

   Add to your MCP client

   Point your MCP client to the ProTax MCP Server URL and provide your API key as the bearer token.

3. 3

   Start invoicing via AI

   Ask your AI assistant to create an invoice — it will call the ProTax MCP tools automatically.