DEV Community: taxgarden

Python Function to Select Correct ITR Form (AY 2026-27)

taxgarden — Thu, 10 Sep 2026 05:22:35 +0000

Filing the wrong ITR form is one of the most common compliance errors for self-employed developers. Here's a deterministic function that returns the correct form given your income sources:

```python def get_itr_form(

has_salary
bool = False,
has_capital_gains
bool = False,
has_business_income
bool = False,
is_presumptive
bool = False, # 44AD/44ADA/44AE
foreign_assets_or_income
bool = False,
is_company_or_llp
bool = False,
is_director_or_unlisted_equity
bool = False,
total_income_above_50L
bool = False,
agricultural_income_above_5k
bool = False,
) -> str: """Returns correct ITR form for AY 2026-27.""" if is_company_or_llp: return 'ITR-6'

if foreign_assets_or_income or is_director_or_unlisted_equity: if has_business_income: return 'ITR-3' return 'ITR-2'

if has_business_income: if is_presumptive: return 'ITR-4' # 44AD/44ADA if income < 3Cr/75L return 'ITR-3'

if has_capital_gains: return 'ITR-2'

if total_income_above_50L or agricultural_income_above_5k: return 'ITR-2'

return 'ITR-1'

Examples print(get_itr_form(has_salary=True)) # ITR-1 print(get_itr_form(has_salary=True, has_capital_gains=True)) # ITR-2 print(get_itr_form(has_business_income=True, is_presumptive=True)) # ITR-4 print(get_itr_form(has_business_income=True)) # ITR-3 ```

Key edge cases AY 2026-27:

LTCG on listed shares (112A) triggers ITR-2, NOT ITR-1 even if otherwise salary-only
Freelancers under 44ADA (professions) use ITR-4 if income under Rs 75 lakh
Crypto/VDA income: many file ITR-2 to be safe
Director in private company: mandatory ITR-2 even with only salary
Form deadlines AY 2026-27:

ITR-1/2/4 (non-audit): July 31, 2026
ITR-3 with tax audit: October 31, 2026
ITR-6 (companies): November 30, 2026
Full ITR form guide: https://taxgarden.in/blog/which-itr-form-ay-2026-27-key-changes

python #tax #india #incometax #ITR

Python Function to Validate GSTIN Checksum: The Algorithm Behind India's 15-Digit GST Number

taxgarden — Tue, 08 Sep 2026 05:16:17 +0000

Every Indian GST registration number (GSTIN) has a checksum in the 15th character. For invoicing software, ERP integrations, or vendor onboarding tools, validating before save prevents downstream pain.

GSTIN STRUCTURE

Position 1-2
State code (01-38)
Position 3-12
PAN of the entity
Position 13
Entity number (1-9 or A-Z)
Position 14
Always 'Z'
Position 15
Checksum
THE ALGORITHM (modified Luhn with custom 36-character set):

```python def validate_gstin(gstin: str) -> dict: import re CHARS = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ" gstin = gstin.strip().upper()

pattern = r'^[0-3][0-9][A-Z]{5}[0-9]{4}[A-Z][1-9A-Z]Z[0-9A-Z]$' if not re.match(pattern, gstin): return {"valid": False, "error": "GSTIN format invalid"}

state_code = int(gstin[:2]) if not (1 <= state_code <= 38): return {"valid": False, "error": f"Invalid state code: {gstin[:2]}"}

def calculate_checksum(g14: str) -> str: total, factor = 0, 2 for char in reversed(g14): code = CHARS.index(char) addend = factor * code factor = 1 if factor == 2 else 2 addend = (addend // len(CHARS)) + (addend % len(CHARS)) total += addend return CHARS[(len(CHARS) - total % len(CHARS)) % len(CHARS)]

expected = calculate_checksum(gstin[:14]) if expected != gstin[14]: return {"valid": False, "error": f"Checksum mismatch: expected {expected}, got {gstin[14]}"}

return {"valid": True, "state_code": gstin[:2], "pan": gstin[2:12]}

Test for g in ["29AAACB2230M1ZP", "27AADCB2230M1ZA", "99AAACB2230M1ZP"]: print(g, validate_gstin(g)) ```

COMMON GOTCHAS

Always normalize to uppercase first
O vs 0 confusion from OCR on scanned invoices
Position 14 is always 'Z'; foreign OIDAR entities differ
State 37 = current AP, 28 = legacy AP (both valid)
For GST registration process and all state codes: https://taxgarden.in/blog/gst-registration-process-india-2026

#python #gst #india #fintech #validation

TDS Compliance with Node.js: Calling TRACES API to Verify Deduction Certificates

taxgarden — Fri, 04 Sep 2026 06:45:49 +0000

TDS compliance is not just an accounting problem , it is a data problem. Every quarter, finance teams reconcile 26AS with vendor invoices manually. It takes hours and misses errors.

Here is a basic Node.js fetch call to check a TAN holder's deduction summary via the TRACES (TDS Reconciliation Analysis and Correction Enabling System) portal API:

```js const axios = require("axios");

async function getTDSSummary(tan, fy) { const response = await axios.post( "https://www.tdscpc.gov.in/app/api/tdssummary", { tan, financialYear: fy }, {

headers: { "Content-Type": "application/json",

Authorization: Bearer ${process.env.TRACES_TOKEN}, }, } ); return response.data; } ```

TRACES requires authentication via DSC or Aadhaar OTP. The API returns quarter-wise deduction data including:

Total TDS deducted
Total TDS deposited
Challan mapping status
Number of deductees per quarter
Match deducted vs deposited: any delta means a short-deduction notice risk under Section 201.

For a complete TDS rate reference by payment type (194C, 194J, 194Q, etc.), see: https://taxgarden.in/blog/tds-rate-chart-2026-to-2027

Quality gate: Remove link mentally. Still useful? YES , gives real code + explains what TRACES API returns and why gaps matter.

GST e-invoicing API integration for developers: IRN generation, IRP endpoints, common errors

taxgarden — Thu, 03 Sep 2026 12:24:03 +0000

If you build ERP integrations for Indian SMBs, e-invoicing via the GST IRP API is something you will eventually touch.

Authentication: POST to sandbox.einvoice1.gst.gov.in/eicore/v1.03/Auth. Generate a 32-byte random session key. Encrypt with NIC public key (provided in sandbox docs). Base64 encode becomes app_key. Response gives auth_token encrypted with your session key. Decrypt to get bearer token. 6-hour expiry.

Generate IRN: POST /eicore/v1.03/Invoice with Version, TranDtls (supply type), DocDtls (invoice number, type, date), SellerDtls + BuyerDtls (GSTIN and address), ItemList (HSN, quantity, rate, GST amounts), ValDtls (total). Response: IRN (64-char hash), SignedQRCode, AckNo.

Common errors: 2150: GSTIN not found in sandbox. Use provided test GSTINs only. 2283: Duplicate IRN. Invoice number already submitted. 2271: HSN code invalid for the supply type.

Cancellation: only within 24 hours. PUT /eicore/v1.03/Invoice/Cancel with IRN and reason.

Mandatory for Rs 5 crore plus turnover since August 2023. Build it before clients hit the threshold.

Business compliance context: GST e-invoicing compliance guide

Tech-focused comparison of TDS compliance tools for developers building payroll/accounts integrations

taxgarden — Wed, 02 Sep 2026 06:10:47 +0000

If you're building a payroll or accounts payable system for Indian clients, TDS compliance is non-negotiable. The question isn't whether to integrate it , it's which tool handles the edge cases without breaking your pipeline.

Here's what I've seen in production integrations:

The filing requirements that catch developers off guard

TDS has seven distinct return types: 24Q (salary), 26Q (non-salary domestic), 27Q (non-resident payments), 27EQ (TCS), 26QC (rent TDS by individual/HUF), 26QD (contractor payments), 26QB (property purchase). Each has a different form structure, different due dates, and different TRACES upload format.

What to look for in a TDS tool's API

Bulk challan validation (cross-check BSR code, challan serial, and amount before filing)
PAN validation against TRACES database (invalid PANs trigger 20% TDS deduction , expensive bug)
FVU (File Validation Utility) output generation , NSDL's FVU format is required for all return submissions
Correction statement support , most tools handle original returns but botch the C3/C5 correction workflow
Tools worth evaluating

Gen TDS, TDSMAN, ClearTDS, Saral TDS, and Winman TDS are the major ones. The differences aren't in coverage , they all handle the major sections. The delta is in correction workflows, multi-deductor support, and whether they expose an API vs require manual data entry.

For a full feature comparison relevant to both developers and CA firms, see best TDS software India 2026.

80C tax saving - data-driven comparison for developers and tech workers

taxgarden — Tue, 01 Sep 2026 07:10:46 +0000

Every year around January, developers suddenly remember they need to submit investment proofs. Then they scramble to pick something from the list HR sent.

Let me save you some time with a data-driven comparison.

Section 80C gives you up to Rs 1.5 lakh in deductions per year. The instruments differ massively in lock-in, liquidity, and actual post-tax returns.

ELSS (Equity Linked Savings Scheme)

Lock-in
3 years (shortest of all 80C options)
Returns
Market-linked, ~12-15% historical CAGR over 10yr
Tax on returns
LTCG at 12.5% after Rs 1.25 lakh threshold
Liquidity
After 3 years, fully liquid
Who it suits
Tech workers with 5+ year horizon, comfortable with equity risk
PPF (Public Provident Fund)

Lock-in
15 years (with partial withdrawal after 7)
Returns
7.1% p.a. (government-set, tax-free)
Tax on returns
ZERO. EEE status (exempt at investment, growth, and withdrawal)
Liquidity
Low. Loans allowed against it.
Who it suits
Anyone wanting guaranteed returns + full tax exemption
NPS (National Pension System)

Lock-in
Until age 60
Returns
Market-linked (choose equity/debt allocation)
Tax benefit
Additional Rs 50,000 deduction under 80CCD(1B) OVER the 1.5L limit
Tax on returns
60% of corpus tax-free at withdrawal; 40% mandatorily in annuity
Who it suits
High-income folks who want the extra 50K deduction; long-term focused
The REAL comparison for a developer earning Rs 20L+ per year in the new tax regime: if you are on the new tax regime, 80C deductions are NOT available. Repeat - the new tax regime does not allow 80C. So this entire exercise only applies if you opt for the old regime.

If you are on the old regime and want liquidity + solid returns: ELSS. If you want guaranteed safety + EEE: PPF. If you want the extra Rs 50K deduction: NPS.

Full comparison with returns data: 80C investment options compared: ELSS, PPF, NSC

GST returns, TDS reconciliation, ROC filings , for most Indian startups this is still a spreadsheet problem. But a quiet shift is happening.

taxgarden — Fri, 28 Aug 2026 06:59:47 +0000

Companies are now running AI agents that:

Pull GSTR-2B data from the GST portal API nightly
Match it against internal purchase ledgers
Flag ITC mismatches before the human accountant logs in Monday morning
Generate a pre-filled GSTR-3B with confidence scores on each line item
The agent doesn't file. It prepares. The human reviews and approves. But the 3 hours of reconciliation work is now 15 minutes of exception handling.

What's Actually Powering This
Most implementations use a combination of:

Python scripts calling GSTN sandbox APIs for return data
Claude or GPT-4o for ledger interpretation and anomaly flagging
Simple rule engines for TDS section classification (194C vs 194J vs 194Q)
Email triggers for due-date reminders with pre-filled data
None of this requires a dedicated ML team. A single backend developer with access to the GSTN API and an LLM SDK can build a working prototype in a weekend.

The Interesting Problem: Section Classification
The hardest part is TDS section classification. When a company pays a vendor, is it 194C (contractor) or 194J (professional/technical)? Misclassify, and the TDS rate changes (1-2% vs 10%). An LLM with the right context window can handle this with ~90% accuracy , the edge cases still need human review.

Where This Is Going
The CBDT has announced a move toward faceless compliance. Automated matching systems already flag mismatches before they become notices. The startups building internal compliance automation now will have a significant operational advantage in 3 years.

Read more about how AI in tax compliance India is reshaping accounting workflows for SMEs and startups.

The Compliance Stack Nobody Talks About

taxgarden — Fri, 28 Aug 2026 06:39:30 +0000

GST returns, TDS reconciliation, ROC filings , for most Indian startups this is still a spreadsheet problem. But a quiet shift is happening.

Companies are now running AI agents that:

What's Actually Powering This
Most implementations use a combination of:

Read more about how AI in tax compliance India is reshaping accounting workflows for SMEs and startups.

Building AI-powered compliance systems for India's GST and TDS regime

taxgarden — Wed, 26 Aug 2026 07:00:12 +0000

ndia's tax system generates remarkable amounts of structured data. GST alone produces GSTR-1, GSTR-2B, GSTR-3B, GSTR-9 , every transaction captured in a format that is, in principle, machine-readable. The compliance problem is not a data availability problem. It is an aggregation, reconciliation, and action problem.

That is the gap where AI agents are starting to operate.

The reconciliation problem

Every month, a GST-registered business must reconcile its GSTR-2B (auto-populated purchase register from suppliers' filings) against its own purchase register. ITC claimed in GSTR-3B cannot exceed the ITC in GSTR-2B. But suppliers file late, amend invoices, or match GST numbers incorrectly , so the raw data is always dirty.

A rule-based reconciliation script can flag mismatches. An AI layer can classify them: supplier-delay (wait and reclaim next month), permanent mismatch (chase the supplier), vendor-error (the GSTIN was mistyped), or genuine ineligibility (the item is blocked for ITC). Correct classification reduces the manual review queue by 60-80% in practice.

The TDS section classification problem

TDS requires applying the correct section to each payment type. Section 194C for contractors, 194J for professionals, 194H for commission, 194Q for goods purchases above Rs 50 lakh , with overlapping criteria and frequent edge cases (a mixed-service contract spanning 194C and 194J).

LLMs trained on statutory text and case law can classify invoice descriptions into the right TDS section with reasonable accuracy. A small fine-tuned model outperforms a generic LLM for this task because the vocabulary is domain-specific and the training data (actual invoices with confirmed TDS sections) is available within any mid-sized accounting practice.

The architecture pattern that works

Input layer
structured invoice data (description, amount, vendor type, GSTIN, payment terms)
Classification layer
LLM + retrieval over statutory definitions
Validation layer
rule-based checks against the classifier output
Action layer
populate TDS challan or flag for human review
Tax Garden's overview of how AI in Indian tax compliance is reshaping small business GST and TDS management covers the practitioner side of these systems.

GST input tax credit depends on GSTR-2B reconciliation, an automatable data-matching job

taxgarden — Wed, 26 Aug 2026 06:26:57 +0000

If you run a SaaS or product company in Hyderabad and outsource GST filing, here is the part that determines whether you keep your input tax credit: GSTR-2B reconciliation. It is a data-matching problem, and it is exactly where Rs 400-a-month filing quietly skips work.

GSTR-2B is the auto-drafted statement of credit available to you, generated from your suppliers' filings. Your claimed ITC has to match what your suppliers actually reported. When a supplier files late or files wrong, your credit moves, and unreconciled invoices are credit you silently lose.

Why this is a real engineering-shaped task: you are joining your purchase register against GSTR-2B on GSTIN, invoice number, date and value, flagging mismatches, and chasing suppliers before the filing window closes. Done by hand on a few hundred invoices it is error-prone; done with no process it does not happen at all.

Pricing reality for Telangana (code 36): basic GSTR-1 plus GSTR-3B is Rs 1,500 to Rs 3,000 a month. Full compliance with monthly GSTR-2B reconciliation is Rs 5,000 to Rs 12,000. The gap between those two numbers is the reconciliation work.

Before you sign, ask for the consultant's GSTIN (36-series for Hyderabad), a recent GSTR-9 they filed, and a written scope.

Details on what GST compliance in Hyderabad actually covers, beyond just pressing submit.

Pre-filled ITR from AIS/TIS as untrusted upstream data; reconcile before submit.

taxgarden — Wed, 26 Aug 2026 06:23:04 +0000

Engineer framing for tax season: the pre-filled ITR is an auto-populated form sourced from upstream systems you do not control. AIS and TIS aggregate salary, interest, dividends, capital gains and TDS credits from employers, banks and brokers. Like any ingested data, it can be stale, duplicated or wrong.
Common failure modes I see every year:

Late TDS returns from an employer, so a credit is missing at filing time.
Banks reporting interest figures that do not match your statements.
Broker data that does not reconcile with your actual realised gain or loss.
The validation step before you hit Submit: reconcile every pre-filled field against Form 16, Form 26AS, bank statements and broker contract notes. Treat the portal value as a claim to verify, not a source of truth.

One non-obvious detail. If AIS is wrong, you must do two independent things: submit feedback inside AIS for each transaction, and file your ITR with the correct figures. Doing only one leaves a mismatch open. A revised return under Section 139(5) fixes most post-filing mistakes penalty-free before December 31, 2026 for AY 2026-27; for CPC processing errors you use rectification under Section 154.

Full checklist on how to verify and correct pre-filled ITR data before you file.

# Automate CBDT Scrutiny Risk Scoring Against AIS Data in Python

taxgarden — Mon, 17 Aug 2026 10:07:44 +0000

CBDT issues compulsory scrutiny guidelines each year specifying which ITRs get flagged for mandatory audit. For FY 2026-27, the criteria are broader than previous years. If you are building compliance tools or processing ITR data, you need these rules encoded.

The FY 2026-27 Compulsory Scrutiny Criteria
CBDT mandates scrutiny when any of the following are present:

AIR/SFT mismatch: Cash deposits above Rs 10 lakh in savings accounts not matching declared income
Capital gains underreporting: LTCG/STCG in AIS not matching Schedule CG in ITR
International transactions: Transfer pricing cases with turnover above Rs 50 crore
Treaty claims: Non-residents claiming DTAA exemptions above threshold
Non-filers with high-value transactions: Persons with SFT-reported transactions who did not file an ITR
Returns selected by system-based risk parameters: INSIGHT portal flags based on behavioural analytics
Building a Risk Scorer in Python

```python from dataclasses import dataclass from typing import Optional

@dataclass class AISData:

cash_deposits
float
reported_income
float
stcg_in_ais
float
stcg_in_itr
float
ltcg_in_ais
float
ltcg_in_itr
float
has_international_txn
bool
intl_txn_turnover
float
is_non_resident
bool
filed_itr
bool
sft_high_value
bool
def scrutiny_risk_score(ais: AISData) -> dict: flags = []

if ais.cash_deposits > 1_000_000 and ais.cash_deposits > ais.reported_income * 0.3: flags.append("CASH_DEPOSIT_MISMATCH")

if abs(ais.stcg_in_ais - ais.stcg_in_itr) > 10_000: flags.append("STCG_MISMATCH")

if abs(ais.ltcg_in_ais - ais.ltcg_in_itr) > 10_000: flags.append("LTCG_MISMATCH")

if ais.has_international_txn and ais.intl_txn_turnover > 50_000_000: flags.append("TRANSFER_PRICING_RISK")

if ais.sft_high_value and not ais.filed_itr: flags.append("NON_FILER_HIGH_VALUE")

return { "risk_level": "HIGH" if len(flags) >= 2 else "MEDIUM" if flags else "LOW", "flags": flags, "recommend_review": bool(flags) } ```

Integrating with AIS JSON Export
The AIS is downloadable from the income tax portal as a JSON. Parse partB.generalInfo for SFT transactions and partB.capitalGains for AIS capital gains data. Cross-reference against the ITR XML export (ITR-2 / ITR-3 Schedule CG).

Why This Matters for Compliance Platforms
If you are building ITR validation or pre-filing checks, encoding the CBDT scrutiny criteria as a rule engine flags high-risk returns before submission. The taxpayer can either correct the return or prepare a paper trail in advance.

Full CBDT scrutiny guidelines FY 2026-27 with case examples: CBDT compulsory scrutiny criteria FY 2026-27