Odoo and KRA eTIMS: how integration works for Kenyan businesses

Two ways to connect a business system to eTIMS

KRA offers several eTIMS solutions. For a business that already invoices from an ERP such as Odoo, the relevant ones are the two system-to-system integrations, where your system talks to eTIMS directly through an interface instead of someone re-typing invoices into a portal:

• OSCU (Online Sales Control Unit): KRA describes it as suitable for taxpayers whose invoicing is always online.
• VSCU (Virtual Sales Control Unit): suitable for taxpayers doing bulk invoicing whose systems are not always online.

Either route goes through development, testing, vetting and certification. A business can integrate its own system, or use a KRA-verified third-party integrator. KRA publishes the OSCU and VSCU specifications and a sandbox environment for testing.

How Odoo does it

Odoo's Kenya localisation uses the OSCU route, with Odoo acting as the third-party integrator. In practice that means three things. First, the business registers on the KRA eTIMS portal and requests an OSCU service, naming Odoo as the integrator. Second, the Kenya eTIMS modules are installed in Odoo and the OSCU is initialised from the accounting settings, first in test mode and then in production. Third, each branch is set up separately: every place of supply has its own branch ID and its own OSCU initialisation, and invoice sequences run per branch.

Once that is done, Odoo sends invoices, credit notes and the related stock movements to eTIMS as part of normal work, and fetches KRA's standard codes and notices automatically.

Item registration and UNSPSC codes

This is where most of the preparation time goes. KRA requires each product or service to be registered before it is used in business operations such as invoices or stock movements. In Odoo, a product is registered automatically the first time it is sent to KRA, provided its eTIMS fields are complete. According to Odoo's documentation, that means a cost and sales taxes on the product, plus a packaging unit, packaging quantity, origin country, eTIMS product type, an insurance flag and a UNSPSC category.

UNSPSC is the United Nations Standard Products and Services Code, a global classification that KRA uses for items. Odoo fetches the code list from KRA; KRA's portal also has a search to look up the right code for a product or service. Choosing codes is a one-off task, but for a business with hundreds of products it is a real piece of work and is best done in a spreadsheet, reviewed by someone who knows the products, and imported in one go.

Stock, purchases and credit notes

Three behaviours surprise finance teams the first time:

• Stock movements are reported too. Internal moves and stock adjustments are sent to KRA without an invoice; deliveries to outside customers are sent after the invoice.
• Vendor bills arrive from KRA. Odoo fetches suppliers' eTIMS invoices daily. Each one has to be confirmed and matched to confirmed purchase order lines, so purchase discipline matters: no purchase order, no clean match.
• Credit notes have rules. A credit note cannot exceed the quantities or prices on the original invoice, and it needs a KRA reason and a reference to the invoice it reverses.

What to prepare before you switch on

1. Your KRA portal access and the business details exactly as KRA holds them.
2. A list of branches and places of supply, so that each gets the right branch ID.
3. A clean product list: duplicates merged, units of measure consistent, and a UNSPSC code, packaging unit and origin country for each item.
4. Customer and supplier records with correct KRA PINs, since vendor bills are matched on the supplier's PIN.
5. A purchase-order habit for anything you buy, so that incoming eTIMS bills can be matched.
6. A test period: run real scenarios (an invoice, a credit note, a stock adjustment, a vendor bill) in test mode before you move to production.

Where it goes wrong

The technical connection is rarely the problem. Delays come from product data that was never cleaned, branches that were not thought through, and purchase processes that do not produce a purchase order. Treat the integration as a small finance project with an owner, a product-data clean-up and a test plan, not as a module to tick.

We implement and integrate Odoo for Kenyan organisations, including eTIMS. See integrations and business systems.