KRA eTIMS for ERPNext: what compliance actually demands

The technical side of connecting ERPNext to KRA eTIMS is a solved problem: you sign an invoice payload, transmit it, and store the response. The harder question, and the one that keeps finance directors awake, is compliance. What does the law actually require, which invoices must be reported, how does your VAT return have to reconcile, and what happens when it does not. This guide takes the compliance view. It assumes the integration works and asks the question that matters at audit time: can you prove you complied?

We have taken retail, manufacturing, and distribution clients through eTIMS on ERPNext. Every one of them cared far less about the API than about the consequences of getting a return wrong. Here is what compliance means in practice.

Who has to comply, and with what

eTIMS is the Kenya Revenue Authority's electronic Tax Invoice Management System. It replaced the older hardware-only TIMS regime with software and online options, and its scope is broad. In practice, if you are a VAT-registered business you must issue electronic tax invoices through eTIMS. Beyond VAT, KRA has progressively extended the expectation that business expenses be supported by eTIMS-generated invoices to be deductible for income tax. That means eTIMS reaches businesses well past the VAT threshold, because their customers now need eTIMS invoices to claim the cost.

The compliance obligation, then, is not just 'issue invoices'. It is:

• Every taxable sale is transmitted to KRA in real time and carries a valid control unit signature and QR code on the printed or issued document.
• Every item on that invoice is classified with a KRA item code and the correct tax category, so the tax computed matches KRA's expectation.
• Credit notes and corrections are transmitted as their own document type, referencing the original. You never simply edit a reported invoice.
• Purchase invoices you intend to claim as input VAT are backed by supplier invoices that were themselves transmitted through eTIMS.
• Your periodic VAT return reconciles to the invoices KRA already holds, because KRA is comparing the two.

The shift most businesses underestimate is that KRA now sees your invoices as you issue them. Your VAT return is no longer a self-declared summary KRA takes on trust. It is a figure KRA can check against a transmission log it already has. Compliance is therefore about the match between what you reported invoice-by-invoice and what you declare on the return.

The invoice: what must be true for it to count

For an invoice to be compliant, it is not enough that it exists in ERPNext. It must have been transmitted and accepted, and it must carry the artefacts KRA's rules require. On the printed receipt or the PDF you send a customer, that means a control unit serial, the invoice number KRA assigned or accepted, a QR code that resolves against KRA's records, and the correct tax breakdown per item.

The compliance failure mode here is quiet. An invoice can be submitted in ERPNext, sit in your sales ledger, feed your VAT return, and never have been accepted by eTIMS because transmission failed and nobody noticed. From the accounts, everything looks normal. From KRA's side, that sale does not exist as a reported invoice, and the moment your return claims it, the two no longer match. This is why transmission status must be a first-class, visible field on every invoice, and why an empty error queue is a compliance control, not a nice-to-have.

Reconciling your VAT return to eTIMS

The compliance habit that matters most is a monthly reconciliation between your ERPNext output VAT and the invoices eTIMS holds for the period. On ERPNext this is straightforward to build because every transmission attempt should be logged against its invoice, so you can produce, for any period, a list of transmitted invoices, the tax per invoice, and the total to compare against the return.

Run that reconciliation before you file, not after KRA queries it. On the deployments we run, this monthly check is the thing that turns eTIMS from a source of anxiety into a routine close step. When the difference is zero, you file with confidence. When it is not, you have a specific list of invoices to fix rather than a vague worry that something is off.

Input VAT and the purchase side

Compliance is not only about what you sell. To claim input VAT, the expense must be supported by a valid eTIMS invoice from your supplier. That reframes purchasing as a compliance activity: a supplier invoice that was never transmitted through eTIMS is not just poor paperwork, it is a claim KRA can disallow, turning a recoverable input into a real cost.

In ERPNext we implement this as a validation on Purchase Invoice, and for clients who want it strict, a block on paying against unverified supplier invoices. The compliance value is direct: you cannot accidentally build a VAT claim on invoices that will not survive an audit. It also gives you a lever with suppliers. An invoice that is not eTIMS-compliant can be rejected before it ever enters your books.

Audit readiness: proving compliance after the fact

The real test of a compliance setup is not go-live day, it is the day KRA asks about a transaction from eight months ago. Audit readiness on ERPNext means every transmission left a trail you can retrieve in minutes:

• The full request and response for each invoice, so you can show exactly what was sent and what KRA returned.
• The signed payload and QR data, linked to the invoice, so you can reproduce the customer's receipt.
• A complete history of retries and failures, so a gap has a documented explanation rather than an unexplained hole.
• Credit notes traced to their originals, so corrections are legible rather than suspicious.

The difference between a five-minute audit answer and a five-day reconstruction is down to whether you logged every attempt. Treat the transmission log as permanent, searchable evidence, because that is what KRA will treat it as.

The cost of getting it wrong

Non-compliance is not a soft risk. Kenyan tax law attaches penalties to failure to issue electronic tax invoices, to under-declaration of VAT, and to late filing, and it adds interest on unpaid tax. Beyond the direct penalty, a return that does not reconcile to eTIMS invites the one thing every finance team wants to avoid: a detailed KRA audit, which consumes weeks of staff time regardless of the eventual finding. The most expensive eTIMS mistakes we see are not fines. They are the operational cost of an outage that went unnoticed until a return had already been filed on wrong numbers.

This is why compliance and system design are the same conversation. A queue-and-retry transmission model keeps your tills moving, but only if it is paired with alerting so that a stuck queue surfaces as a notification the same day, not as a discrepancy at month end. Numbering must stay in lockstep with KRA's sequence rules, because a numbering drift produces rejections that look like data errors but are really compliance failures.

A compliance checklist for ERPNext eTIMS

Get those six right and eTIMS stops being a compliance risk and becomes a routine, provable part of your close. The invoice reports itself, the return reconciles, and an audit is a search query rather than a fire drill.

Unsure whether your ERPNext eTIMS setup would survive a KRA audit? We run a compliance review that reconciles your books to your transmission log and surfaces the gaps before KRA does. Book a discovery call and we will walk through your last three returns with you.

Working on something like this?

We ship ERPNext and custom Frappe apps across Kenya, Uganda, Tanzania, Rwanda, Ethiopia, and Somalia. Let's talk through your build.