Automating a Kenya VAT return in Acumatica is less about clever code and more about mapping. Acumatica already knows every taxable transaction you posted; the work is lining up its tax zones, tax categories, and tax IDs so the totals fall onto the right lines of the KRA VAT3 return, and so the figure you file matches the figure your ledger will defend in an audit. Get the mapping right once and the monthly return becomes a report you run, reconcile, and export — not a spreadsheet you rebuild from scratch every 20th of the month.
How Acumatica models VAT before you automate anything
Every tax outcome in Acumatica comes from the intersection of a tax zone (attached to the customer or vendor, answering "where is this party for tax purposes") and a tax category (attached to the stock or non-stock item, answering "what kind of thing is being sold"). The combination selects a tax, and each tax carries a rate and a reporting group. For a Kenyan return you typically end up with taxes for standard-rated output (16%), zero-rated output, exempt supplies, and the corresponding input taxes on the purchase side. Before you automate, make sure these are set up cleanly, because the return is only ever as correct as this configuration.
On each tax's Taxes screen there is a Reporting Settings tab where you assign the tax amount and taxable amount to reporting groups. Those groups are the bridge between a posted transaction and a line on the VAT3. If two taxes should roll up to the same return line, they share a reporting group. This is the single most important thing to get right.
Mapping Acumatica taxes to the VAT3 lines
The KRA VAT3 return separates output tax (sales) from input tax (purchases), and within each splits standard-rated, zero-rated, and exempt. Build a mapping table so every tax you use in Acumatica has an unambiguous destination on the return. Keep it in writing and review it whenever a new tax is added.
| Acumatica tax | Reporting group | VAT3 destination |
|---|---|---|
| Output VAT 16% | Output – Standard | Standard-rated sales + output tax |
| Output Zero-rated | Output – Zero | Zero-rated sales |
| Output Exempt | Output – Exempt | Exempt sales |
| Input VAT 16% | Input – Standard | Standard-rated purchases + input tax |
| Input – Capital goods | Input – Capital | Purchases of capital goods |
Running and reconciling the tax report
Acumatica prepares the return through Tax Reports (the Prepare Tax Report / Release Tax Report cycle on the Taxes workspace). Preparing a report for a tax agency and period gathers every released document in that period and buckets the amounts by reporting group. The critical discipline is reconciliation: the output tax on the prepared report should tie back to the VAT liability in your GL tax accounts for the same period. If they diverge, the usual culprits are documents posted to the wrong tax, manual GL entries that touched the tax account directly, or documents released after the report was prepared.
Releasing the tax report closes the period for tax and marks those documents as reported, so they won't appear on the next one. If you release with an error still in it, correcting it means an adjustment on the following period rather than a clean re-run. Prepare, reconcile against the GL, fix, re-prepare — and only then release.
Producing the file iTax will accept
KRA's iTax portal expects the VAT3 uploaded as its published Excel template with the sales and purchases schedules populated. Acumatica does not ship a Kenya-specific iTax file out of the box, so the practical pattern is to drive the export from the tax report data with a Generic Inquiry or an Analytical Report, shaped to the columns iTax expects (PIN of the counterparty, invoice number, date, taxable value, VAT amount). Exporting the GI to Excel and pasting into the KRA template is a perfectly reasonable first version; only build a bespoke export once the manual step is genuinely the bottleneck.
-- Shape released output-tax detail for the iTax sales schedule.
-- In practice express this as a Generic Inquiry over TaxTran/ARTran;
-- shown as SQL here for clarity.
SELECT
c.AcctCPF AS CounterpartyPIN,
d.RefNbr AS InvoiceNbr,
d.DocDate AS InvoiceDate,
tt.TaxableAmt AS TaxableValue,
tt.TaxAmt AS VATAmount
FROM TaxTran tt
JOIN ARRegister d ON d.DocType = tt.TranType
AND d.RefNbr = tt.RefNbr
JOIN Customer c ON c.BAccountID = d.CustomerID
WHERE tt.TaxID = 'OUTPUT16'
AND d.TaxPeriodID = @period
AND d.Released = 1;Where withholding VAT complicates the picture
Kenya operates a withholding VAT regime for appointed agents, where the buyer withholds 2% of the VAT and remits it directly to KRA. If your client is an appointed withholding agent, or sells to one, the VAT they actually pay or collect differs from the VAT on the invoice, and that difference has to be tracked so the return and the ledger stay honest. Model the withholding as its own tax with its own reporting group rather than netting it silently — it needs to show separately on the return, and treating it as a distinct tax keeps the reconciliation traceable.
Filing cadence and closing the loop
The VAT return in Kenya is monthly, due by the 20th of the following month, and is filed even when there is no activity (a nil return). Build the monthly rhythm into the ERP process: close the sub-ledgers, prepare the tax report, reconcile to the GL, export and file on iTax, then record the payment against the VAT liability account so the balance rolls forward correctly. The value of automating this in Acumatica is not that a single return is faster — it is that every return after the first follows the same repeatable, auditable path.
Wrapping up
The Kenya VAT return is a mapping problem wearing an automation costume. Set up taxes and reporting groups so amounts land on the right VAT3 lines, reconcile the prepared report against the GL before you release it, and drive the iTax export from the same tax data rather than a side spreadsheet. Do that and each month's filing is a routine run rather than a scramble. If you are stuck on something specific, reach out or keep reading through the rest of the Acumatica blog.
Independent software engineer in Nairobi specialising in Acumatica customisations, Laravel backends, and tax fiscalisation integrations across East and Southern Africa.