Tax and eTIMS

Finance → Accounting → Tax → /tax · Provider mappings → /provider-mappings

Kenyan tax compliance runs through eTIMS, the Revenue Authority's electronic tax invoice system. Nyumba Zetu submits invoices to eTIMS through the DigiTax integration and stores the certified result on the invoice.

How tax works on the platform

The tax applied to a line comes from its service type, which carries a tax class. The platform default is class D (Non-VAT); VAT-rated items are mapped explicitly. See Chart of accounts.

Setup

Tax submission requires a connection per business, configured under the integration setup:

Before submitting real invoices, the item catalogue must be synchronised so that every service type you bill exists on the provider side.

Submitting an invoice

1. Issue the invoice

   Only issued invoices are submitted.

2. Send to eTIMS

   Use the send action on the invoice, or the eTIMS Integration tab. A confirmation dialog states what will be submitted.

3. Watch the status

   The invoice's eTIMS tab shows the submission status with live updates and an audit trail of every attempt.

4. Read the certified receipt

   On acceptance the invoice shows KRA eTIMS Certified with the QR code, receipt details and fiscal identifiers, rendered inline on the invoice.

Submission statuses

Submissions move through queued → submitted → accepted or failed, with the attempt count and the reason on failure. The eTIMS tab shows why it failed rather than a bare error code.

Provider mappings

/provider-mappings is the cross-invoice view of integration state: every submission, its status, provider, document type, correlation and idempotency keys, attempts, and the failure reason.

From here you can:

• filter by provider and status to find everything that failed;
• retry failed submissions, with background processing hints so you know a retry is in flight;
• drill into an individual mapping's timeline and payload.

A per-invoice mappings tab gives the same detail for one document.

Available operations

The integration supports the operations eTIMS exposes, including:

Operations can also be run individually from the manual capability runner for diagnosis, with a payload builder and the last operation response shown.

Correcting a filing

Once KRA has accepted an invoice, the certified receipt is on record permanently. There are two buttons on the eTIMS tab and they do very different things.

The usual correction is therefore: void with credit note first, then re-file if a corrected receipt is needed. After voiding, the invoice sits unfiled again.

Voiding the right receipt

If an invoice has been filed more than once, several live receipts exist at KRA and which one you cancel matters. The audit trail on the eTIMS tab lists every submission attempt, names the document each one produced (INV-748472 against INV-748472-R1), and carries its own Void button on any accepted row — so you cancel the receipt you meant to.

A receipt can only be credited once. Voiding one that already carries a credit note is refused, and the panel says so.

Tax schedule and withholding

The tax module also covers the tax schedule and withholding tax surfaces, for tracking what is due and what has been withheld on payments.

Monthly tax routine

1. Clear the failed queue

   Filter provider mappings by failed status and resolve each one. Most failures are tax-class or item-mapping issues, not connectivity.

2. Confirm every issued invoice was submitted

   An invoice with no submission is an unreported sale.

3. Reconcile the sales summary

   Compare the provider's sales summary against your revenue for the period.

4. Review credits

   Any credit note against a certified invoice needs a decision on how it is handled with KRA.

5. Then close the period

   See Accounting periods.

Common problems