Odoo KRA eTIMS Integration: OSCU vs VSCU, Setup Steps and Error Fixes

Most eTIMS articles stop at "Odoo is compliant" and leave the hard part to you: the service request, item codes, stock discipline and the errors that appear on the first live invoice. This guide covers all of it, the same steps our Odoo integration services run for Kenyan clients.

It is for finance managers, IT leads and Odoo administrators in Kenya who need KRA-signed invoices without rebuilding their ERP. Still budgeting? Start with our guide to Odoo implementation cost in Kenya and Africa, which prices eTIMS as one budget line.

What is KRA eTIMS and who has to use it?

KRA eTIMS is the electronic Tax Invoice Management System through which every invoice must be validated, signed and transmitted to the Kenya Revenue Authority. It replaced the hardware-based TIMS control units for most taxpayers.

The legal basis is Section 23A of the Tax Procedures Act, introduced by the Finance Act 2023. KRA's guidance says it "requires every person in business to record each sale, issue and transmit invoices". KRA's eTIMS page adds that all persons engaged in business must onboard, VAT-registered or not.

KRA offers several ways to comply. Only the last row matters for an ERP.

Two KRA rules shape every ERP decision: each solution keeps its own invoice sequence, and a credit note can only be raised from the solution that issued the original invoice. Re-keying Odoo invoices into the portal creates duplicates and orphaned credit notes.

eTIMS OSCU vs VSCU: which one does Odoo use?

Odoo's native Kenya module is an OSCU, hosted at KRA and designed for systems that are always online; a VSCU is a Java service you host yourself for bulk or intermittent invoicing. Both are "Sales Control Units" that validate, encrypt, sign and store invoices.

KRA's sign-up guide puts it plainly. The OSCU is "Implemented and hosted at KRA" and suits online systems. The VSCU is "Implemented and hosted on the client side" and suits organizations that generate large invoice volumes in a short time or whose invoicing is not always online.

KRA's technical specification sets a transmission schedule of at most 15 minutes, with status "P" for a processed command and "E" for an error. Odoo's OSCU hides this detail: you click Send and the invoice returns with a KRA invoice number, SCU ID, receipt signature and QR code.

Pick a VSCU only if you bill thousands of lines in short bursts or your sites lose connectivity for hours. For most Kenyan firms on Odoo Enterprise, the native OSCU is the lower-risk choice because Odoo maintains it with each release.

Which Odoo versions and editions support eTIMS?

The eTIMS EDI modules run on Odoo Enterprise 17.0 and later, including Odoo 19 and Odoo 20, while Odoo Community only has the Kenyan chart of accounts, taxes and the legacy Tremol TIMS module. This is the single most common surprise in scoping calls.

The Odoo Kenya localization documentation lists the first four as installed automatically, and POS and Tremol as optional. The commitment form asks for "the Odoo version you're using (17.0 or onwards)", so Odoo 16 and older must upgrade first.

Community users need a paid connector. One OSCU module on the Odoo Apps Store lists at about US$670 for Odoo 18; a newer Community and Enterprise eTIMS module for Odoo 17 to 19 lists at about US$298 plus US$199 for a VSCU add-on, but not on Odoo Online.

Add upgrades and support for that connector and the gap to Enterprise narrows. Our Odoo Community vs Enterprise comparison weighs those costs against the license.

On Odoo 15 or 16 with a Tremol device, plan the eTIMS move together with the version jump. Our Odoo upgrade services run both in one test cycle.

How do you set up Odoo eTIMS step by step?

Odoo eTIMS setup has four stages: KRA portal registration, OSCU initialization in Test mode, the integration token, and the switch to Production. Budget two to five working days, most of it waiting for approvals.

1. Clean the company record. In Settings, click Update Info and enter the Kenyan Tax ID (KRA PIN). Set the country to Kenya. Odoo generates the OSCU serial number from this VAT number with the prefix ODOO.
2. Initialize in Test mode. Go to Accounting, Configuration, Settings, Kenya eTIMS Integration. Set eTIMS Server Mode to Test, enter the Serial Number, tick the two check boxes and click Initialize OSCU.
3. Sign up on the eTIMS portal. Create the account with your PIN, confirm the OTP sent to the iTax phone number, and upload the owner's or director's ID plus the signed commitment form.
4. File the service request. On the eTIMS dashboard choose Service Request, select OSCU as the eTIMS type, enter Odoo KE LTD as the third-party integrator with PIN PO52112956W, and paste your OSCU serial number.
5. Request the integration token. Email etims@mail.odoo.com with your eTIMS portal credentials and database name; Odoo's documentation says the token arrives the same day. Enter it in the Integration Token field.
6. Fetch the codes. OSCU standard codes refresh every two days and UNSPSC codes daily, but on a new database run the scheduled actions "KE eTIMS: Fetch KRA standard codes" and "Fetch UNSPSC codes from eTIMS" manually.
7. Register products and test a full cycle. Sale, delivery, invoice, send to eTIMS, credit note, vendor bill and stock adjustment. Check the KRA invoice number and QR code on the PDF.
8. Switch to Production. Change the server mode, send one live invoice, and confirm it appears under Sales by Invoice on the KRA portal.

A third mode, Demo, uses mock data and needs no initialized OSCU. Use it for training, never for the final test. If the device was already initialized through another ERP, enable developer mode and enter the existing Unit ID and CMC Key instead of initializing again.

How does eTIMS product registration work in Odoo?

KRA requires every product to be registered before it appears on an invoice, stock move or bill of materials, and Odoo registers it automatically the first time all mandatory fields are filled. Missing fields show as a yellow banner at the top of the document.

The General Information tab needs a Cost and Sales taxes. The Accounting tab needs Packaging Unit, Packaging Quantity, Origin Country, eTIMS Product Type, Insurance Applicable and a UNSPSC Category. Odoo pulls the UNSPSC list from KRA daily, so the field is a lookup, not free text.

Tax classification matters as much as the product code. KRA labels tax rates A to E, and Odoo's Kenyan taxes carry a KRA Item Code that justifies each rate.

The Kenya accounting module ships roughly 340 KRA item codes that justify a zero or exempt rate. Map exempt and zero-rated products to them during setup, not after the first dispute with KRA.

For catalogs with thousands of SKUs we script the registration: a CSV import of packaging unit, origin and UNSPSC category, then a test send per category. Our Odoo customization services add validation rules so no product reaches an invoice with eTIMS fields missing.

How do stock movements, purchases and BOMs report to eTIMS?

eTIMS is not a sales-only system: KRA expects stock movements, vendor bills, customs imports and bills of materials, and Odoo sends each of them from its own module. This is where spreadsheets and sales-only connectors fall short.

• Stock movements: Odoo sends internal transfers and stock adjustments automatically when no contact is set or the contact is your own company or branch. External moves go after the related invoice. The move must be confirmed and every product registered.
• Sales of unstocked items: KRA does not accept a sale if the product is not in stock, so the advised flow is sales order, validate delivery, confirm invoice, then Send to eTIMS.
• Vendor bills: Odoo fetches new bills from eTIMS daily. You set the product, link the bill to confirmed purchase order lines with quantities equal to the received quantity, choose an eTIMS Payment Method and click Send to eTIMS.
• Customs imports: import records arrive daily under Vendors, Customs Imports. Match each to a registered product, a vendor and a purchase order, then click Match and Approve or Match and Reject.
• Bills of materials: with l10n_ke_edi_oscu_mrp installed, open the BOM and click Send to eTIMS. Both the finished product and every component must be registered first.

Stock accuracy now has a tax consequence, so run a full count before go-live. Our guide on Odoo internal controls covers the three-way match that the eTIMS purchase flow enforces.

How do credit notes work with eTIMS in Odoo?

KRA accepts an eTIMS credit note only if it references a signed invoice and does not exceed that invoice's quantities or prices. Odoo enforces this with two extra fields on the credit note.

Open the eTIMS Details tab on the credit note, choose an eTIMS Credit Note Reason, and select the original invoice in the Reversal of field. Then send it like an invoice. Without the reason or the reference, the send fails or KRA rejects it.

The KRA specification adds two constraints. A credit note "contains only negative, credit note amounts", and an original transaction can be cancelled only once. A partial return followed by a second correction therefore needs a credit for the remainder and a new invoice.

The Odoo credit notes documentation covers partial refunds, full refunds and "full refund and new draft invoice", the cleanest way to fix a wrong price under eTIMS.

What are the most common eTIMS invoice rejection errors and how do you fix them?

Most eTIMS rejections in Odoo come from six causes: an unapproved service request, a sequence mismatch, unregistered products, unvalidated stock, a credit note that breaks KRA's rules, or a branch that was never initialized. The table maps the message you see to the fix.

The same pattern shows up outside Odoo. Zoho's eTIMS troubleshooting guide lists "Invoice number already exists" and item-before-transaction errors at the top, confirming these are KRA rules, not Odoo bugs.

Keep the JSON in the chatter. Every bill, customs import and BOM sent to eTIMS stores its request and response file there, and KRA support will ask for it.

How do branches, multi-company and KRA sequences work?

KRA treats every place of supply as a branch with its own ID, its own OSCU initialization and its own invoice sequence, and Odoo models this with branch companies under one parent. Three shops mean three initializations.

The parent company carries eTIMS Branch Code 00. Outlets are created as branches of that parent and receive their IDs from KRA. Once the parent's OSCU is initialized, open the Branches tab and click Populate from KRA.

Sequences change too. Normally a parent and two branches share one series, so the group's third invoice is INV/2024/00003. Under eTIMS each branch restarts at 00001, because KRA needs independent numbering per branch. Tell your auditors before period close.

Contacts carry a branch code on the Accounting tab as well, defaulting to OO. Set it for customers with several KRA branches. For the wider structure, see our guide to Odoo multi-company setup and intercompany rules.

Which Kenyan industries feel eTIMS most in Odoo?

Distributors, retailers and manufacturers carry the heaviest eTIMS load because stock, POS receipts and bills of materials all report to KRA, while service firms mostly deal with invoices and credit notes. The table shows where the effort goes.

Retailers should read our Odoo POS implementation guide alongside this one. A till that loses connectivity cannot sign receipts through an OSCU, so the rollout plan needs a documented fallback.

How iVentureTeam helps with Odoo eTIMS integration in Kenya

iVentureTeam configures, registers, tests and supports Odoo eTIMS for Kenyan companies, and builds the custom pieces where the native module stops. We have delivered 150+ ERP projects across 35+ countries with 40+ Odoo specialists over 13+ years.

• Scoping and version check: confirm your Odoo version, edition and hosting support the native OSCU, or price a third-party or VSCU route honestly. A quick number comes from our Odoo project estimate tool.
• Registration and initialization: we prepare the commitment form, serial numbers and token request, and run Test mode until a full sale, bill, credit note and stock cycle passes.
• Master data: bulk UNSPSC, packaging, origin and tax code mapping across your product catalog, with validation rules so nothing unregistered reaches an invoice.
• Custom work: branch-aware reports, POS fallbacks, insurance filing and integrations with M-Pesa or your bank through our Odoo integration services.
• Run and support: monitoring of the daily KRA fetch jobs, sequence checks at month end and version upgrades under our Odoo ERP support plans.

Odoo in Kenya case study: Kongowea Village

Before eTIMS existed, iVentureTeam was already delivering Odoo Enterprise projects for Kenyan organizations, which is the experience we bring to compliance work today. Kongowea Village is a community initiative in Kenya.

The initiative had no digital presence and no structured way to hear from residents. Investors, partners and advertisers needed a credible place to learn about it, and most of the audience would arrive on mobile phones.

We delivered the whole footprint on Odoo 12 Enterprise in five weeks: seven custom-designed pages, from Homepage to Advertise, plus an integrated survey with a predefined questionnaire, all in one backend.

The site is live at kongoweavillage.co.ke, survey responses arrive structured instead of scattered across email and paper, and the backend is ready for eCommerce, CRM or events. It was a website project, not an eTIMS one, but it shows how we deliver in Kenya.

Read the Kongowea Village Odoo website and survey case study.

The bottom line on Odoo eTIMS in Kenya

If you run Odoo Enterprise 17 or later, use the native OSCU: register, initialize in Test, fix your product master and stock, then switch to Production. Choose a VSCU or a third-party module only when offline bulk invoicing or Odoo Community forces the issue.

The errors that stop Kenyan go-lives are predictable: unregistered products, unvalidated stock, drifting sequences and credit notes that break KRA's rules. Fix them in a test database and the live cutover becomes routine.

Ready to get your Odoo invoices signed by KRA?

Tell us your Odoo version, number of branches and SKU count, and we will map the eTIMS work in one business day. Request an Odoo eTIMS readiness review, call +91-90235-15208, or email business@iventureteam.com.