GSTR-2B Reconciliation with Configurable Tolerances

#python #fastapi #postgres #fintech

The Problem with Exact-Match ITC Reconciliation

Claiming Input Tax Credit (ITC) under the Indian GST regime requires matching your internal purchase register against the auto-generated GSTR-2B statement each tax period. If an invoice appears in your internal books but is absent or mismatched in GSTR-2B, claiming that credit risks scrutiny and penalties; failing to claim matched invoices delays cash flow.

In practice, naive exact-match scripts break on normal accounting variations:

Leading zeroes or vendor prefixes in invoice numbers (e.g., INV-2023-042 vs. 42).
Rounding discrepancies of a few paise in taxable values or tax totals.
Small variations in invoice dates across system boundaries.

Most commercial tools that handle fuzzy matching and exception handling are priced for enterprise ERPs, while gst software for small business india often limits functionality to portal uploads and basic return filing. Finance teams at SMBs end up running manual VLOOKUPs across thousands of rows every month to reconcile ITC.

How GSTBot Runs GSTR-2B Reconciliation

GSTBot approaches itc reconciliation by replacing rigid string equality with a configurable matching pipeline built in Python. The system processes purchase records against GSTR-2B data using tolerance thresholds across numerical and identifier fields, then categorizes every mismatch into an actionable bucket.

The Architecture

The backend runs on FastAPI and Python, using Celery backed by Redis for asynchronous reconciliation jobs. Data is persisted in PostgreSQL, while the user interface is built with React and Vite.

[Purchase Register / GSTR-2B] 
            │
            ▼
     FastAPI Endpoints
            │
            ▼
      Celery + Redis ───► Matching Worker
                               │
                               ├─ Normalized string matching
                               ├─ Numerical tolerance checks (± value)
                               └─ Exception categorization
                               │
                               ▼
                          PostgreSQL

Matching Logic and Tolerance Thresholds

Instead of evaluating pr_inv_num == g2b_inv_num, GSTBot strips common delimiters (slashes, hyphens, prefixes) and compares normalized invoice identifiers alongside GSTIN matching. Tax amounts are evaluated against configurable absolute thresholds rather than strict equality.

A simplified view of the tolerance and classification logic implemented in the Python backend:

from decimal import Decimal
from typing import Optional
from pydantic import BaseModel

class MatchConfig(BaseModel):
    tax_tolerance: Decimal = Decimal("1.00")
    normalize_invoice_numbers: bool = True

def classify_match(
    pr_invoice: dict,
    g2b_invoice: Optional[dict],
    config: MatchConfig
) -> tuple[str, str]:
    if not g2b_invoice:
        return "MISSING_IN_GSTR2B", "Hold ITC; follow up with vendor to file GSTR-1"

    tax_diff = abs(Decimal(str(pr_invoice["tax_amount"])) - Decimal(str(g2b_invoice["tax_amount"])))

    if tax_diff > config.tax_tolerance:
        return "TAX_AMOUNT_MISMATCH", "Reconcile difference with vendor; claim lower amount"

    return "MATCHED", "Eligible for full ITC claim"

By parameterizing tax_tolerance (for instance, allowing up to ₹1.00 or ₹2.00 in fractional differences caused by fractional tax rounding), the system eliminates manual audits of false positives while catching genuine discrepancies.

Exception Classification

Every record that fails a threshold check is assigned an explicit exception state and recommended operational response, such as:

Missing in GSTR-2B: Flagged to withhold provisional credit and notify the vendor to report the supply in their GSTR-1.
Tax Value Mismatch: Identifies the delta between internal books and supplier filing, prompting finance staff to verify against original tax invoices.
Tax Rate / HSN Inconsistency: Flags line-item discrepancies between rates claimed and rates filed.

What It Looks Like to Use

Data Intake: Users ingest vendor invoices into the system—via bulk PDF, invoice photos, or Excel sheets—alongside the exported GSTR-2B data from the GST portal.
Configuration: The user specifies tolerances (such as acceptable rupee variance) according to their firm's accounting standards.
Execution: Celery processes the comparison asynchronously, preventing request timeouts on multi-thousand-row purchase registers.
Exception Dashboard: The React interface displays the ledger segmented into matched line items and flagged exceptions. Each exception displays the exact delta and the prescribed action, allowing accountants to make claim decisions directly rather than cross-referencing raw spreadsheets.

By treating gstr-2b reconciliation as an asynchronous pipeline with configurable tolerances, GSTBot automates input tax credit verification without enterprise-level overhead.

DEV Community