> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitaji360.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Withholding Tax (WHT)

> Withholding tax is tax you deduct from a payment to a supplier and remit to the tax authority on their behalf, instead of paying the full amount to the…

Withholding tax is tax you deduct from a payment to a supplier and remit to the tax authority on their behalf, instead of paying the full amount to the supplier. For example, on a 1,000,000 service bill subject to 6% WHT, you pay the supplier 940,000 and hold back 60,000 to remit to the authority. Hitaji's **withholding codes** let you configure these rules once — the rate, the bracket thresholds, and the GL accounts — so the system computes and posts the withheld amount for you at bill or payment time.

**You'll find this at:** `/settings/erp/finance/withholding-codes` — in the left navigation under **Settings → ERP / Finance → Withholding Codes**. (The older link `/accounting/settings/withholding-codes` redirects here.)

> 📷 *Screenshot: Withholding Codes settings page listing each code with its basis and thresholds — to be added.*

***

## Multi-business note

Withholding codes are stored **per business**. Each business configures its own codes and keeps its own running totals. Switch the active business with the business switcher before adding or editing codes.

***

## How a withholding code works

A withholding code bundles together everything needed to apply WHT to a vendor payment:

* **A basis** — whether the rate is applied to the **gross** amount (before VAT) or the **net** amount (after VAT). Uganda typically withholds on **net**; some cases use gross.
* **One or more thresholds (a bracket table)** — the rate to apply, and the cumulative amount at which it starts. The simplest code has a single threshold of **0**, meaning WHT applies "from the first shilling".
* **GL accounts** — a **payable account** (the WHT you've withheld and now owe the authority) and an optional **recoverable account** (WHT that can be reclaimed).
* **Vendor categories** — optional labels used to match the code to the right kind of supplier.

### Thresholds explained

Thresholds let a single code change rate as a vendor's cumulative year-to-date amount grows. Each threshold row has:

* **Threshold amount** — the cumulative amount at or above which this row applies.
* **Rate percent** — the WHT rate for that bracket.
* **Row order** — the display/evaluation order.

The engine picks the applicable bracket based on the vendor's **year-to-date cumulative total** (see "Balances" below). A code must have **at least one threshold** — Hitaji rejects a code with none.

> **The common Uganda setup:** one threshold with **threshold amount = 0** and your standard rate (e.g. 6%). That applies WHT to every payment regardless of cumulative total.

***

## Creating a withholding code

1. Go to **Settings → ERP / Finance → Withholding Codes** (`/settings/erp/finance/withholding-codes`).
2. Click **Add Withholding Code**.
3. Fill in the fields below, including at least one threshold row.
4. Save.

> 📷 *Screenshot: Create-withholding-code form with basis selector, account pickers, and the threshold rows table — to be added.*

### Fields

| Field                   | Required | Notes                                                                                                                          |
| ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Code**                | Yes      | A short identifier, e.g. `WHT6`. **Unique per business.** Max 20 characters.                                                   |
| **Label**               | Yes      | A readable name, e.g. "WHT 6% — Services". Max 100 characters.                                                                 |
| **Basis**               | Yes      | **Gross** (pre-VAT) or **Net** (post-VAT).                                                                                     |
| **Payable account**     | Yes      | The GL account **credited** with the withheld tax — your WHT Payable liability. Must be an active account in the current book. |
| **Recoverable account** | No       | The GL account for recoverable WHT, if applicable. Must be an active account in the current book.                              |
| **Vendor categories**   | No       | Labels used to match this code to applicable suppliers.                                                                        |
| **Active**              | No       | Active codes appear in pickers; inactive ones are hidden but kept. On by default.                                              |
| **Thresholds**          | Yes      | At least one bracket row: threshold amount, rate percent, and row order.                                                       |

***

## How WHT is applied and posted

When a withholding deduction is taken on a vendor payment, Hitaji records it as a **deduction line** on that payment. Each deduction line carries the withholding code, the amount withheld, and the GL account it hits.

**Behind the scenes.** A withholding deduction reduces the net cash leaving on the payment and **credits the WHT Payable account**. So for a 1,000,000 payment with 60,000 WHT: the supplier receives 940,000 of cash, and 60,000 is parked in WHT Payable as money you now owe the tax authority. When you later remit to the authority, that payable is cleared.

> A payment can carry several deduction lines (WHT, bank charges, early-payment discount, or other). Only the **withholding** lines require a withholding code; the engine also keeps a cached total of WHT withheld on the payment for reporting.

The exact moment WHT is computed — at **bill submit** or at **payment** — is governed by your business's WHT timing setting.

***

## Balances (year-to-date running totals)

To apply the correct bracket, Hitaji keeps a **withholding balance** per party, per code, per fiscal year. Each balance row tracks:

* the **cumulative amount** transacted with that party this year, and
* the **cumulative tax withheld** so far.

When a new deduction is calculated, the engine reads this running total to decide which threshold bracket applies, then updates the total within the same posting transaction (with a lock so concurrent payments can't double-count). This is what makes graduated thresholds — "the first X is at one rate, amounts above X at another" — work correctly across many payments to the same vendor over a year.

You don't maintain these balances by hand; they are accumulated automatically as you post bills and payments.

***

## Editing a withholding code

Open a code and change its label, basis, accounts, vendor categories, active flag, or its threshold rows. If you replace the thresholds, you must still provide **at least one** — Hitaji rejects an empty threshold set. Any payable/recoverable account must still be an active account in the current book.

***

## Deleting a withholding code

A withholding code is **soft-deleted**. **You cannot delete a code that is still referenced** — if any bill line or any payment deduction uses it, Hitaji blocks the deletion with a count, e.g. *"WithholdingCode WHT6 is referenced by 3 bill line(s) / payment(s) and cannot be deleted"*. Deactivate the code instead so it leaves the pickers while preserving history and balances.

***

## Access & permissions

* **Viewing** withholding codes requires the `accounting:read` scope.
* **Creating, editing and deleting** withholding codes requires `accounting:admin` or `accounting:config`.

***

## Related

* [Tax codes](/accounting/user/masters/taxes) — VAT / sales tax on invoices and bills.
* [Customers & Vendors (Contacts)](/accounting/user/masters/contacts)
* [Payment terms](/accounting/user/masters/payment-terms)
* [Categories](/accounting/user/masters/categories)