feat!: Introduce tax withholding entry (backport #51099) by mergify[bot] · Pull Request #51297 · frappe/erpnext

mergify · 2025-12-23T15:18:42Z

This PR introduces a comprehensive refactor of the Tax Withholding (TDS/TCS) system in ERPNext. The key change is the introduction of a new child table Tax Withholding Entry that tracks every tax withholding transaction with full auditability, replacing the previous approach of calculating TDS/TCS on-the-fly.

Breaking Changes

Removed Tax Withheld Vouchers child table - Replaced by Tax Withholding Entry
Removed TDS fields from Purchase Order and Purchase Receipt - TDS is now only applicable on invoices and payment entries
Removed allocated_amount field from Advance Taxes and charges table - Advance TDS allocation is now tracked through Tax Withholding Entries
Removed consider_party_ledger_amount setting - Simplified threshold calculation logic (User will have select the checkbox for document to be considered).
Removed Consideration of unallocated payment entry in threshhold - Now if check box is enabled in Payment Entry, then TDS will always be deducted without the threshold check.

New Architecture

Tax Withholding Entry (Child Table)

A new child doctype that tracks every tax withholding transaction with the following key fields:

Field	Description
`tax_withholding_category`	The TDS/TCS category applied
`taxable_amount`	Base amount on which tax is calculated
`withholding_amount`	Actual tax withheld
`tax_rate`	Rate at which tax is calculated
`taxable_doctype/name`	Document that is subject to tax (Invoice)
`withholding_doctype/name`	Document from which tax is deducted (Invoice/Payment)
`status`	Settled, Under Withheld, Over Withheld, Duplicate, Cancelled
`under_withheld_reason`	Threshold Exemption or Lower Deduction Certificate
`lower_deduction_certificate`	Link to LDC if applicable

Entry Status Flow

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Under Withheld │────▶│    Settled      │◀────│  Over Withheld  │
│  (No TDS yet)   │     │  (TDS matched)  │     │ (Advance TDS)   │
└─────────────────┘     └─────────────────┘     └─────────────────┘

Under Withheld: Tax is due but not yet deducted (e.g., below threshold)
Over Withheld: Tax deducted in advance without a taxable document (e.g., advance payments)
Settled: Taxable amount and withholding amount are properly matched

Controller Architecture

TaxWithholdingController (Base)
├── PurchaseTaxWithholding  # For Purchase Invoice
├── SalesTaxWithholding     # For Sales Invoice  
├── PaymentTaxWithholding   # For Payment Entry
└── JournalTaxWithholding   # For Journal Entry

Key Features

1. Automatic Entry Matching

When a document is submitted, the system automatically matches:

Under withheld entries (pending TDS) with over withheld entries (advance TDS)
Entries are matched based on party, category, and fiscal year
Partial matching is supported with proportional allocation
First preference is given to allocated advance entry.

2. Cumulative Threshold Tracking

Invoice 1: ₹10,000 → Under threshold → Status: Under Withheld
Invoice 2: ₹10,000 → Under threshold → Status: Under Withheld  
Invoice 3: ₹15,000 → Crosses ₹30,000 threshold → All 3 settled with TDS

3. Tax on Excess Amount

When tax_on_excess_amount is enabled:

Only the amount exceeding threshold is taxed
Threshold exemption entries are created with under_withheld_reason = "Threshold Exemption"

4. Lower Deduction Certificate (LDC) Support

LDC utilization is tracked per entry
Supports partial LDC application
Automatic rate adjustment based on LDC

5. Advance Payment TDS/TCS

Scenario: Payment Entry with TDS → Sales Invoice allocation

Payment Entry: ₹30,000 (TCS: ₹3,000) → Status: Over Withheld
Sales Invoice: ₹50,000 with ₹30,000 advance allocated
  → Entry 1: ₹30,000 taxable, ₹0 TCS (Threshold Exemption)
  → Entry 2: ₹20,000 taxable, ₹2,000 TCS (Settled from PE)

6. Item-Level Tax Withholding

Items can have their own tax_withholding_category
Supports multiple TDS categories in a single invoice
Item-wise tax breakup in tax rows
TDS on Gross Amount and Net Amount.

7. Return Invoice Handling

Return invoices create negative taxable entries
Automatic adjustment of original invoice's TDS entries
Proper GL entry reversal

8. Tax Withholding Group

Introduces Tax Withholding Group to support different TDS/TCS rates within the same category based on entity type.
Use Case
In India, Section 194C has different rates:

Individual/HUF: 1%
Company/Firm: 2%
Without PAN: 20%

Migration

A patch update_tax_withholding_field_in_payment_entry handles:

Renaming apply_tax_withholding_amount to apply_tds in Payment Entry

Future Enhancements

Manual Adjustment
Update After Submit
Bulk reconciliation tool for under/over withheld entries
TDS in Journal Entry for multiple parties.(Manual Entry)
Handle Amendments
Don't use Advance taxes and Charges table for TDS in Payment Entry.
Configurable setting for TDS: Item level vs Party Level. Can be used to toggle additional settings like Tax withholding Group.
Generalize LDC (say TaxID instead of PAN)
Rounding off in auto calculation when the rate/taxable amount is changed.

Checklist

All existing tests pass
New test cases added for all scenarios
Documentation updated
Migration patch included

Features

no-docs

This is an automatic backport of pull request #51099 done by Mergify.

(cherry picked from commit c66f78c) # Conflicts: # erpnext/accounts/doctype/journal_entry/journal_entry.py # erpnext/accounts/doctype/payment_entry/payment_entry.json # erpnext/accounts/doctype/sales_invoice/sales_invoice.py # erpnext/accounts/doctype/tax_withholding_category/tax_withholding_category.py # erpnext/accounts/doctype/tax_withholding_category/test_tax_withholding_category.py # erpnext/patches.txt

mergify · 2025-12-23T15:18:45Z

Cherry-pick of c66f78c has failed:

On branch mergify/bp/version-16-beta/pr-51099
Your branch is up to date with 'origin/version-16-beta'.

You are currently cherry-picking commit c66f78c784.
  (fix conflicts and run "git cherry-pick --continue")
  (use "git cherry-pick --skip" to skip this patch)
  (use "git cherry-pick --abort" to cancel the cherry-pick operation)

Changes to be committed:
	deleted:    erpnext/accounts/doctype/advance_tax/advance_tax.json
	deleted:    erpnext/accounts/doctype/advance_tax/advance_tax.py
	modified:   erpnext/accounts/doctype/advance_taxes_and_charges/advance_taxes_and_charges.json
	modified:   erpnext/accounts/doctype/advance_taxes_and_charges/advance_taxes_and_charges.py
	modified:   erpnext/accounts/doctype/journal_entry/journal_entry.js
	modified:   erpnext/accounts/doctype/journal_entry/journal_entry.json
	modified:   erpnext/accounts/doctype/payment_entry/payment_entry.js
	modified:   erpnext/accounts/doctype/payment_entry/payment_entry.py
	modified:   erpnext/accounts/doctype/payment_entry_deduction/payment_entry_deduction.json
	modified:   erpnext/accounts/doctype/purchase_invoice/purchase_invoice.js
	modified:   erpnext/accounts/doctype/purchase_invoice/purchase_invoice.json
	modified:   erpnext/accounts/doctype/purchase_invoice/purchase_invoice.py
	modified:   erpnext/accounts/doctype/purchase_invoice/test_purchase_invoice.py
	modified:   erpnext/accounts/doctype/purchase_invoice_item/purchase_invoice_item.json
	modified:   erpnext/accounts/doctype/purchase_invoice_item/purchase_invoice_item.py
	modified:   erpnext/accounts/doctype/purchase_taxes_and_charges/purchase_taxes_and_charges.json
	modified:   erpnext/accounts/doctype/purchase_taxes_and_charges/purchase_taxes_and_charges.py
	modified:   erpnext/accounts/doctype/sales_invoice/sales_invoice.js
	modified:   erpnext/accounts/doctype/sales_invoice/sales_invoice.json
	modified:   erpnext/accounts/doctype/sales_invoice_item/sales_invoice_item.json
	modified:   erpnext/accounts/doctype/sales_invoice_item/sales_invoice_item.py
	modified:   erpnext/accounts/doctype/sales_taxes_and_charges/sales_taxes_and_charges.json
	modified:   erpnext/accounts/doctype/sales_taxes_and_charges/sales_taxes_and_charges.py
	modified:   erpnext/accounts/doctype/subscription/subscription.py
	deleted:    erpnext/accounts/doctype/tax_withheld_vouchers/tax_withheld_vouchers.json
	modified:   erpnext/accounts/doctype/tax_withholding_category/tax_withholding_category.js
	modified:   erpnext/accounts/doctype/tax_withholding_category/tax_withholding_category.json
	renamed:    erpnext/accounts/doctype/advance_tax/__init__.py -> erpnext/accounts/doctype/tax_withholding_entry/__init__.py
	new file:   erpnext/accounts/doctype/tax_withholding_entry/tax_withholding_entry.json
	new file:   erpnext/accounts/doctype/tax_withholding_entry/tax_withholding_entry.py
	new file:   erpnext/accounts/doctype/tax_withholding_entry/test_tax_withholding_entry.py
	renamed:    erpnext/accounts/doctype/tax_withheld_vouchers/__init__.py -> erpnext/accounts/doctype/tax_withholding_group/__init__.py
	new file:   erpnext/accounts/doctype/tax_withholding_group/tax_withholding_group.js
	new file:   erpnext/accounts/doctype/tax_withholding_group/tax_withholding_group.json
	renamed:    erpnext/accounts/doctype/tax_withheld_vouchers/tax_withheld_vouchers.py -> erpnext/accounts/doctype/tax_withholding_group/tax_withholding_group.py
	new file:   erpnext/accounts/doctype/tax_withholding_group/test_tax_withholding_group.py
	modified:   erpnext/accounts/doctype/tax_withholding_rate/tax_withholding_rate.json
	modified:   erpnext/accounts/doctype/tax_withholding_rate/tax_withholding_rate.py
	modified:   erpnext/accounts/party.py
	modified:   erpnext/accounts/report/tax_withholding_details/tax_withholding_details.js
	modified:   erpnext/accounts/report/tax_withholding_details/tax_withholding_details.py
	modified:   erpnext/accounts/report/tds_computation_summary/tds_computation_summary.py
	modified:   erpnext/buying/doctype/purchase_order/purchase_order.js
	modified:   erpnext/buying/doctype/purchase_order/purchase_order.json
	modified:   erpnext/buying/doctype/purchase_order/purchase_order.py
	modified:   erpnext/buying/doctype/purchase_order_item/purchase_order_item.json
	modified:   erpnext/buying/doctype/purchase_order_item/purchase_order_item.py
	modified:   erpnext/buying/doctype/supplier/supplier.json
	modified:   erpnext/buying/doctype/supplier/supplier.py
	modified:   erpnext/controllers/accounts_controller.py
	modified:   erpnext/controllers/sales_and_purchase_return.py
	modified:   erpnext/controllers/taxes_and_totals.py
	modified:   erpnext/hooks.py
	deleted:    erpnext/patches/v14_0/update_partial_tds_fields.py
	new file:   erpnext/patches/v16_0/migrate_tax_withholding_data.py
	new file:   erpnext/patches/v16_0/update_tax_withholding_field_in_payment_entry.py
	modified:   erpnext/public/js/controllers/transaction.js
	modified:   erpnext/public/js/utils/party.js
	modified:   erpnext/selling/doctype/customer/customer.json
	modified:   erpnext/selling/doctype/customer/customer.py
	modified:   erpnext/stock/doctype/item/item.json
	modified:   erpnext/stock/doctype/item/item.py
	modified:   erpnext/stock/doctype/purchase_receipt/purchase_receipt.json
	modified:   erpnext/stock/doctype/purchase_receipt/purchase_receipt.py
	modified:   erpnext/stock/doctype/purchase_receipt_item/purchase_receipt_item.json
	modified:   erpnext/stock/doctype/purchase_receipt_item/purchase_receipt_item.py
	modified:   erpnext/stock/get_item_details.py
	modified:   erpnext/subcontracting/doctype/subcontracting_receipt/subcontracting_receipt.py

Unmerged paths:
  (use "git add <file>..." to mark resolution)
	both modified:   erpnext/accounts/doctype/journal_entry/journal_entry.py
	both modified:   erpnext/accounts/doctype/payment_entry/payment_entry.json
	both modified:   erpnext/accounts/doctype/sales_invoice/sales_invoice.py
	both modified:   erpnext/accounts/doctype/tax_withholding_category/tax_withholding_category.py
	both modified:   erpnext/accounts/doctype/tax_withholding_category/test_tax_withholding_category.py
	both modified:   erpnext/patches.txt

To fix up this pull request, you can check it out locally. See documentation: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally

mergify Bot added the conflicts label Dec 23, 2025

mergify Bot requested review from mihir-kandoi, rohitwaghchaure and ruthra-kumar as code owners December 23, 2025 15:18

mergify Bot assigned ljain112 Dec 23, 2025

mergify Bot added the conflicts label Dec 23, 2025

github-actions Bot added accounts stock labels Dec 23, 2025

ruthra-kumar closed this Dec 23, 2025

github-actions Bot locked as resolved and limited conversation to collaborators Jan 7, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat!: Introduce tax withholding entry (backport #51099)#51297

feat!: Introduce tax withholding entry (backport #51099)#51297
mergify[bot] wants to merge 1 commit intoversion-16-betafrom
mergify/bp/version-16-beta/pr-51099

mergify Bot commented Dec 23, 2025

Uh oh!

mergify Bot commented Dec 23, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

mergify Bot commented Dec 23, 2025

Breaking Changes

New Architecture

Tax Withholding Entry (Child Table)

Entry Status Flow

Controller Architecture

Key Features

1. Automatic Entry Matching

2. Cumulative Threshold Tracking

3. Tax on Excess Amount

4. Lower Deduction Certificate (LDC) Support

5. Advance Payment TDS/TCS

6. Item-Level Tax Withholding

7. Return Invoice Handling

8. Tax Withholding Group

Migration

Future Enhancements

Checklist

Uh oh!

mergify Bot commented Dec 23, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants