This guide on uganda efris in erpnext is written for finance teams, compliance leads and IT administrators running Ugandan operations, with code samples, ERPNext / Medusa recipes, and step-by-step fixes you can copy into a real project. For years, Uganda's EFRIS was a VAT-registered taxpayer's problem. That changed on 1 July 2025. Under URA General Notice 2218 of 2025, businesses in 12 gazetted sectors must now issue EFRIS e-invoices whether. Not they are VAT-registered — and the consequence reaches income tax, not just VAT. A purchase from a non-compliant supplier in those sectors is disallowed as a deductible expense. If you run ERPNext in Uganda, the Fiscal Document Number (FDN) is no longer a VAT detail; it is the gate on both your invoices and your deductions. This guide covers the scope shift, the FDN gate, goods registration and stock sync in ERPNext. This guide on uganda efris in erpnext is written for finance teams, compliance leads and IT administrators running Ugandan operations, with code samples, ERPNext / Medusa recipes, and step-by-step fixes you can copy into a real project.
The trap in 2026 is assuming EFRIS still only matters if you're VAT-registered. It doesn't, and the income-tax disallowance for non-compliant purchases is the part that surprises finance teams. I lead enterprise ERPNext and Frappe implementation programmes at MithTech, a 35-person practice in Bengaluru that designs, customises, integrates and operates business-critical software for manufacturers, distributors, schools, financial services and multi-location operations across multiple jurisdictions. Treating the FDN as a hard gate — on both sales and purchases — is what keeps a Ugandan ERPNext rollout compliant.
Are you even in scope?
Before anything technical, establish whether EFRIS is mandatory for your business — because the 2025 expansion changed the answer for a lot of companies that assumed they were exempt.
Toggle whether you are VAT-registered and whether you operate in a gazetted sector to see if EFRIS e-invoicing is mandatory for you.
VAT-registered taxpayers (annual turnover above the UGX 150 million threshold) have been in scope from the start. The shift is the second lever: businesses in 12 gazetted sectors — fuel, mining, manufacturing, construction, ICT, professional services. Others — were brought in from 1 July 2025 regardless of VAT status. If either applies, every sale must be an EFRIS e-invoice.
The FDN gate reaches your deductions
Here is the part finance teams miss. EFRIS validity no longer gates only VAT input credit; in the gazetted sectors it gates income-tax deductibility on the purchase side.
Toggle whether a supplier is in a mandatory-EFRIS sector and whether their invoice carries an FDN to see whether the expense is safely deductible.
Wire EFRIS into ERPNext
EFRIS exposes a system-to-system API, and there is a maintained community app — erpchampions/uganda_compliance, covering ERPNext v13, v14 and v15 — that maps ERPNext documents to it. Verify its status for your version; either way, the moving parts are the same.
Copy-paste the layered architecture, the invoice-upload flow that stores the FDN, the goods and stock registration steps, and the habits that keep invoices valid and deductions safe.
Register goods and report stock
EFRIS is not only invoicing — you register each sellable item as an EFRIS good with the correct commodity code, unit and tax category, and report stock-in before you can invoice it. Map ERPNext Purchase Receipts, Stock Entries and Stock Reconciliations to the matching EFRIS stock operations so URA's ledger and yours agree.
Issue e-invoices that carry an FDN
On submit, map the Sales Invoice to the EFRIS payload, upload it, and store the returned FDN, verification code and QR on the document — then render them on the print format. Without a returned FDN, do not hand the customer the invoice; it is not a valid fiscal document.
Screen purchases for the FDN
For suppliers in the gazetted sectors, treat a missing FDN as a hard block on booking the purchase — otherwise you lose the income-tax deduction. Store the supplier's FDN and QR on the purchase record for audit, the same evidence discipline as reconciling an Indian e-invoice IRN.
Reconcile stock on a schedule
Mismatched stock between EFRIS and ERPNext is a common audit flag. Reconcile the EFRIS goods list against the ERPNext Item master, and EFRIS stock against ERPNext stock, on a schedule — not in a panic at year-end.
When sales, stores and finance each own a piece
In a Ugandan operation the sales desk issues invoices, the stores team manages goods and stock, and finance books purchases. EFRIS touches all three, and the failure sits between them: an item sold before it was registered with URA, an invoice handed over before the FDN came back, or a purchase booked from a gazetted-sector supplier whose invoice had no FDN — quietly costing a deduction.
The control is to make the FDN the single gate the system enforces, not a check any one desk remembers. No item reaches a sales invoice until it is registered; no invoice is "issued" until URA returns an FDN; no gazetted-sector purchase is booked without one. Automate the goods sync rather than registering SKUs by hand, and reconcile EFRIS against ERPNext on a schedule so a drift is caught early.
Draft policy for your finance and operations leads to ratify. Every sellable item is registered with URA before it appears on a sales invoice. No sales invoice is issued to a customer until EFRIS returns a Fiscal Document Number; a missing FDN is a hard block, not a warning. Purchases from suppliers in the gazetted EFRIS sectors are not booked without a valid FDN, to preserve the income-tax deduction. EFRIS goods and stock are reconciled against the ERPNext Item master and stock ledger on a set schedule. Current scope, penalty and deductibility rules are confirmed with URA, not carried over from prior guidance. Ratify with your Ugandan tax advisor before adoption.
Should you buy the app or build the integration?
| Use the uganda_compliance app | Build the integration |
|---|---|
| A maintained app covers your ERPNext version and current EFRIS fields | No maintained app matches your version or requirements |
| Standard invoicing, goods and stock sync, credit notes | Bespoke document flows or unusual stock handling |
| You want the fastest route to compliant invoicing | You need full control of the EFRIS mapping |
| Small IT team, prefer a supported dependency | In-house capacity to track EFRIS API changes |
| Either way: verify FDN, QR and antifake code render on the print format | Either way: test the full invoice + stock flow before go-live |
How do you At a glance — quick reference?
| Aspect | What to know |
|---|---|
| When to use Uganda EFRIS in ERPNext | Standard fit for the common case; review edge cases against the table. |
| Typical effort | 1–4 hours for a small team; longer with custom data or multi-entity setups. |
| Main risk | Skipping reconciliation or running before the data is clean. |
| What to do next | Run the steps below, then verify against the checklist. |
FAQ: what do people ask most?
+Is EFRIS only for VAT-registered businesses in Uganda?
No — not since 1 July 2025. Under URA General Notice 2218 of 2025, businesses in 12 gazetted sectors must issue EFRIS e-invoices whether or not they are VAT-registered. VAT-registered taxpayers were always in scope; the expansion brought in non-VAT businesses in those sectors too.
+What is a Fiscal Document Number (FDN) in EFRIS?
The FDN is the identifier URA assigns to each validated e-invoice or e-receipt, issued alongside a verification (antifake) code and a QR code. It is what makes the document a valid fiscal invoice. An invoice without an FDN is not a valid tax document, so the buyer cannot rely on it.
+Can I still deduct a purchase if the supplier's invoice has no FDN?
In the gazetted EFRIS sectors, no — purchases from non-compliant suppliers are disallowed as deductible expenses for income tax, not just blocked for VAT input credit. This is why you should screen suppliers in those sectors and refuse to book an invoice that lacks an FDN. Confirm the current position with URA or your tax advisor.
+Does ERPNext integrate with EFRIS?
Not natively, but there is a maintained community app — erpchampions/uganda_compliance — covering ERPNext v13, v14 and v15, which syncs goods and stock, issues invoices carrying the FDN, verification code and QR, and handles credit notes. Verify its status for your version; otherwise the EFRIS integration is a custom build against URA's API.
+What happens if we issue an invoice without an FDN?
It is not a valid fiscal document. Your customer cannot use it to claim input credit or, in the gazetted sectors, to support their own deduction, and you are non-compliant with the e-invoicing obligation, which carries penalties. Gate ERPNext so no invoice is handed to a customer until URA returns an FDN.
+Does EFRIS track stock or only invoices?
Both. EFRIS registers goods with commodity codes and tracks stock movements, so you must register a sellable item and report stock-in before invoicing it. Keep EFRIS stock and ERPNext stock reconciled — a mismatch is a common audit flag.
What related issues might you also hit?
- India's GST e-invoicing IRP round-trip — the same real-time-validation model in another jurisdiction.
- Saudi Arabia's ZATCA Phase 2 clearance vs reporting — an authority-validates-first e-invoicing regime.
- ERPNext multi-currency and multi-company setup — running a Ugandan entity, with UGX and foreign currencies, inside a group.
What is the bottom line?
EFRIS stopped being a VAT-only concern in July 2025, and the income-tax disallowance for non-compliant purchases is the change that bites hardest. Gate ERPNext on the FDN — on sales and on purchases — register goods before you sell them, and keep stock reconciled with URA. Get that right and EFRIS is a background validation; get it wrong and a missing identifier costs you a deduction you never saw leave.
Running ERPNext in Uganda and unsure your EFRIS setup covers the 2025 rules?
We wire ERPNext to EFRIS — goods registration, FDN-gated invoicing, stock sync and purchase screening — and test the whole flow against URA before your next filing across companies, branches and warehouses.