eTIMS: How Filing Actually Works
What actually happens when an invoice is filed to KRA, why the job is designed so it can never file twice, the retry behaviour that matters during an outage — and the two gaps a VAT-registered business needs to know about before go-live.
eTIMS is not a feature you evaluate. If you are VAT-registered in Kenya it is a condition of trading, and the only real questions are whether your system files reliably, what happens when KRA is unreachable, and which of your documents it does not cover. Those three answers are worth more than any capability grid.
The mechanics, in the order they happen
-
Device initialisation, once
Your TIN and branch identifier are sent to KRA and a control key comes back and is stored for your organisation. Nothing can be filed until this has been done, and it is the step people skip and then wonder why invoices sit unfiled.
-
An invoice is issued
Either the auto-file hook fires, or somebody presses the file button. Both dispatch the same background job, which is the design decision that makes the rest of this safe.
-
The job files it and stores what comes back
The signed receipt from KRA is written onto the invoice, so the fiscal evidence lives on the document rather than in a log.
-
If it fails, the failure is recorded on the invoice
And the invoice still exists. Filing never blocks invoice creation — a KRA outage must not stop you selling.
-
The queue retries with backoff
Three attempts, spaced roughly half a minute, two minutes and five minutes apart, so a transient network or KRA problem recovers without anybody noticing.
Why it cannot file twice
Double filing is the failure that costs you real money, because an invoice filed twice is output VAT declared twice. Two independent guards prevent it, and they are worth understanding because this is the specific thing to interrogate in any vendor's implementation.
Two guards, not one
Guard What it stops
One filing job per invoice at a time A user pressing the button while the auto-file hook is already running
An already-filed check inside the job A job that starts after the invoice was successfully filed by another route
Either guard alone leaves a race. The first stops two jobs existing; the second stops a job that legitimately exists from acting on an invoice whose state changed while it waited in the queue. Ask any vendor how they prevent double filing and listen for whether they describe two mechanisms or one.
What can and cannot be filed
Coverage
| Document | Filed to eTIMS |
|---|---|
| Customer invoices | Yes |
| POS sales | Yes |
| Subscription invoices | Yes |
| Credit notes | No |
| Sales made while offline | No |
| Anything outside Kenya | No |
Built and maintained Configurable by you, not maintained by us Not built
Auto-filing is configured per document type, so you can have customer invoices file automatically and POS sales filed on a button, or any other combination — which is useful when a till is on an unreliable connection.
The two gaps that matter
What AWRA OpsHub does today
- Device initialisation against KRA, holding your own credentials for your own organisation.
- Filing of customer invoices, POS sales and subscription invoices, with the signed receipt stored on the document.
- Auto-file on issue, configurable per document type, plus a manual file button — both routed through the same job.
- Two independent guards against double filing.
- Three retries with increasing backoff, and the failure recorded on the invoice where somebody will see it.
- A sandbox mode, and a test invoice you can send before going live.
What it does not do
- Credit notes are not transmitted. A credit note reduces your output VAT, and applying one here updates the invoice balance without telling KRA. That has to be handled outside the system, and it is the single most important thing on this page.
- Nothing can be transmitted while offline. A till that keeps selling through an outage is producing sales with no fiscal reference, which makes a connectivity problem a compliance problem. Decide your policy on this deliberately.
- No daily exception report listing sales that carry no fiscal reference. The status is on each invoice; nothing aggregates it, so somebody has to look.
- eTIMS is Kenya-only. No other authority is integrated — not FIRS in Nigeria, ETA in Egypt, EFRIS in Uganda, EBM in Rwanda, EFD in Tanzania, GRA in Ghana or SARS in South Africa.
The credit-note gap is the one to raise with your accountant on the day you go live rather than the day it matters. It is not a limitation you can work around by being careful — it is a document class that has to be dealt with separately.
The offline question, which is a policy decision
You cannot transmit during an outage. So you have to decide, in advance and in writing, what a till does when the connection drops. There are only three answers and each has a cost.
Option A
Keep selling, file on reconnection
Commercially obvious and it produces a window of sales with no fiscal reference. Workable if somebody reliably checks and files them, and a genuine exposure if nobody does. This is what most retailers do, usually without having decided it.
Option B
Stop selling until it is back
Compliant and unacceptable to most businesses. Worth naming as an option so the choice of A is visibly a choice rather than a default.
Option C
Keep selling and reconcile the same day, by rule
The workable middle. Whoever closes the till checks that every sale carries a fiscal reference before cashing up, and files what does not. It costs five minutes and it converts an open exposure into a closed one — daily.
Since nothing aggregates the status
Option C requires somebody to look, because there is no report that lists unfiled sales. Build it into the cash-up routine rather than leaving it to whoever remembers — a control that depends on memory has already failed on the day it was needed.
Setting up without a bad first week
In order
- Get your own eTIMS credentials from KRA under your own TIN and branch. They are yours; nobody should be filing on your behalf with theirs.
- Initialise the device in sandbox and send a test invoice. Confirm you get a signed receipt back rather than assuming it worked.
- Decide which document types auto-file. Customer invoices almost always should; POS depends on your connectivity.
- Move to production and file one small real invoice. Check the receipt is stored on the document.
- Write down your offline policy and tell the till operators what it is.
- Add a check to the daily cash-up: does every sale today carry a fiscal reference?
- Raise credit notes with your accountant now, before you need one.
For the wider statutory picture — PAYE, NSSF, SHA and what computes here versus who files it — Kenya compliance features is the piece to read alongside this.
Our take
Filing is reliable by design: one job for both routes, two independent guards against double filing, retries with backoff, and failures recorded on the invoice rather than in a log. Two things need a decision from you rather than from us — the credit-note gap, which your accountant must handle separately, and your written offline policy, which the till operators need to know by name.
File on issue, with the receipt on the document
Device initialisation under your own TIN, per-document-type auto-filing, two guards against double filing, retries with backoff — and the credit-note and offline gaps stated plainly rather than discovered at an audit.
See plans & pricingFrequently asked questions
How does eTIMS filing work?
Your device is initialised once against KRA with your TIN and branch identifier and a control key is stored for your organisation. After that, an issued invoice is filed by a background job — dispatched either by the auto-file hook or by the manual button, both the same job — and the signed receipt from KRA is written onto the invoice. Failures are recorded on the invoice and never block invoice creation.
Can an invoice be filed twice?
No, and it is guarded twice. Only one filing job per invoice can be queued or running, so a manual click while the auto-file hook is already working collapses into one; and the job itself re-checks whether the invoice is already filed before acting, which covers a job whose state changed while it waited in the queue. Either guard alone would leave a race.
What happens if KRA is unreachable?
The job retries three times with increasing backoff — roughly thirty seconds, two minutes and five minutes — so transient problems recover unnoticed. If it still fails, the failure is recorded on the invoice and the invoice stands. What you cannot do is transmit while offline, which is why an offline policy needs to be a written decision rather than a default.
Are credit notes filed to eTIMS?
No, and this is the most important limitation on the page. A credit note reduces your output VAT, and applying one here updates the invoice balance without notifying KRA. It has to be handled outside the system, and it is worth raising with your accountant on the day you go live rather than the day you need one.
What should a till do when the connection drops?
That is a policy decision with three answers: keep selling and file on reconnection, which leaves a window of sales with no fiscal reference; stop selling, which is compliant and unacceptable to most businesses; or keep selling and check at cash-up that every sale carries a fiscal reference, filing whatever does not. The third is the workable one, and since nothing aggregates the filing status, it has to be built into the cash-up routine rather than left to memory.
Does this work outside Kenya?
No. eTIMS is Kenya-only and no other tax authority is integrated — not FIRS in Nigeria, ETA in Egypt, EFRIS in Uganda, EBM in Rwanda, EFD in Tanzania, GRA in Ghana or SARS in South Africa. Where those exist, figures can be produced and reconciled against but nothing transmits.
