GST Return Filing Status API: Active Is Not the Same as Filing

A GST return filing status API is a lookup that returns a taxpayer's recent return-filing record — which returns were filed, for which tax periods, on what dates — as opposed to a registration lookup, which only tells you the GSTIN exists and what its current status is. The two answers diverge for months at a time. Registration status is a state on the register; filing status is behaviour over time, and it is the behaviour that decides whether the input tax credit on your purchase lands in your GSTR-2B. If you only check one, you have checked the one that changes last.

Registration status and filing status are two questions

Most teams that verify GSTINs at all have built the first check: a call at onboarding, it comes back ACTIVE, the record is marked verified, everyone moves on. The mechanics of that check — and why a regex is not a substitute for it — are in our post on GSTIN verification versus format validation.

Registration status is a fact about the register: a registration was granted and has not been cancelled or suspended. Filing status is a fact about conduct: whether this taxpayer has been meeting the periodic obligation the registration carries. A registration is a door that is open; filing is whether anyone walks through it.

The asymmetry that catches people out is timing. Registration status is lagging — it changes only after an administrative process runs its course. Filing status is leading: it changes the moment a due date passes without a return. Most systems check the lagging one.

What filing-status data actually contains

Filing-status data is not a score and not a yes/no flag. It is a list of filing records, and each record carries three things that matter:

• Return type. Which return the record is for. Against an ordinary regular taxpayer you will mostly see the outward-supply return and the summary return; composition and other special categories file different forms on different frequencies.
• Tax period. The month or quarter covered — not the date of filing. Confusing the two is how a dashboard claims a vendor is current when it filed six late returns in one afternoon.
• Date of filing. When it was actually submitted. The distance between tax period and filing date is the most informative derived field in the response, and almost nobody computes it.

Return types, frequencies and due dates are set by the GST Network (GSTN) and the Central Board of Indirect Taxes and Customs (CBIC), and they have been revised more than once. Do not hard-code an assumption that every taxpayer files monthly, and confirm current return types against GSTN or CBIC guidance rather than a blog post, including this one.

GSTR-1 versus GSTR-3B, and which one your credit depends on

These two returns are not interchangeable, and the difference is directly relevant to input tax credit. GSTR-1 is the outward supplies return: the supplier reports the invoices it issued, and that reporting flows into the auto-drafted statement on the recipient's side. GSTR-3B is the summary return, where tax is declared and settled. For a buyer, GSTR-1 is about whether your invoice was reported at all; GSTR-3B is about whether the supplier is discharging the liability that reporting creates.

So a supplier filing GSTR-1 but lagging on GSTR-3B is a different risk from one that has stopped filing GSTR-1 entirely. In the first case your invoices are being reported while the supplier's own tax position deteriorates. In the second the reporting itself has stopped, which is the case that lands on you. Flag both; only one is an immediate credit problem.

We are deliberately not going to tell you what your entitlement is in either case — that is for your advisor and the current rules, and the rules here have moved. What you can safely build is a system that surfaces the distinction early with the dates attached. The finance-side consequences are in vendor GST verification and your input tax credit.

Why an ACTIVE supplier can be nine months behind

Cancellation for non-filing is the outcome of a process, and processes take time. A supplier stops filing. Notices are issued. Eventually a registration may be suspended or cancelled. Throughout that window — which can run for many months — a registration lookup returns ACTIVE, because the registration genuinely is active. Nothing is hidden. You are asking the wrong question.

Step one is where the information was available and free. Everything after it is cleanup.

Reading a filing history as a risk signal

A filing history is a time series, and the useful thing about a time series is that it has a shape. Three shapes are worth naming, because one "non-compliant" flag destroys the distinction between them.

The gap is one or two periods missing from an otherwise regular history. Often benign — a period with no activity, an amendment, a scheme you did not account for. Ask a question; do not stop a payment over it alone.

Consistent lateness is every return filed, but the interval between tax period and filing date widening cycle over cycle. This is the most under-used signal in the dataset and it is trivially derivable: per record, compute the days between period end and date filed, then look at the trend rather than the value. A lag that has gone from days to weeks across four cycles is a supplier under pressure — visible while every return is still technically present.

The sudden stop is a long, clean, on-time history that simply ends. Easiest to detect, latest filing older than one full cycle against a history with no prior gaps, and the most serious. A clean filer does not stop for no reason.

Polling cadence: what to cache and what rots

Filing data has a natural rhythm, which makes cadence easy to reason about: it only changes when somebody files something. Polling a vendor daily buys nothing over polling once per cycle, except a bill and a rate-limit problem.

The fields age at very different rates, and giving them one TTL is the standard design error:

• Legal name and registration date — effectively immutable. Cache indefinitely.
• Registration status — slow-moving but consequential. Re-check on a schedule, and always before a large release.
• Closed filing periods — immutable once filed. Append them and keep them forever. This is the part most implementations needlessly re-fetch every run.
• Current and previous period — genuinely volatile. The only part of the response with a real reason to be refreshed often.

A cadence that works for most vendor masters: one sweep per filing cycle across active vendors, a targeted re-check on anything already flagged, and a fresh call immediately before a payment release above whatever threshold finance sets. Store every response with a fetched_at timestamp, so "compliant" always reads as compliant as of a date rather than as a permanent property of the vendor.

Designing the check into payment release

This is the part that changes the return on the whole exercise, and it is a workflow decision rather than an integration one. Onboarding-time verification is table stakes and nearly worthless as a filing check, because what you are trying to detect is a change that happens afterwards. Onboarding tells you a vendor was filing on the day you signed them; the exposure is created every time you release money after that.

So put the check at payment release. When a run is assembled, each line has a vendor and each vendor has a GSTIN; the check either returns clean or returns one of the shapes above. Clean lines release. Flagged lines move to a review queue with the filing history attached, so the reviewer sees dates and periods rather than a red icon.

Where this lands architecturally depends on what owns the vendor master. If that is an ERP, the check belongs in the release workflow rather than in a spreadsheet beside it; we cover that in GST vendor onboarding automation in an ERP. If you are prototyping before committing engineering, a general-purpose automation tool is a legitimate first draft — the trade-offs are in n8n versus Zapier versus custom automation.

Rate limits, retries and idempotency at scale

One vendor is a GET request. Eight thousand vendors every cycle is a distributed-systems problem with a little tax domain attached. Four things carry most of the weight.

Batch, do not loop. A synchronous for-loop over a vendor master is the design that gets throttled halfway through and leaves a half-updated table with no record of where it stopped. If your provider offers a job-based endpoint, use it: submit, poll, ingest the result set as a unit. The spreadsheet-versus-API trade-off for one-off cleanups is in bulk GSTIN verification, Excel versus API.

Respect the limits your provider publishes, not the ones you assume. Rate limits vary by provider and plan and they change; read the current documentation rather than a number from an article. Use exponential backoff with jitter on 429 and 5xx, honour Retry-After when present, and cap total attempts so an upstream outage cannot become a retry storm.

Make retries idempotent. The call is a read, so repeating it is naturally safe; the danger is on your side. If ingestion writes an alert, opens a ticket or sends a notification, a retried batch does it twice. Key writes on (GSTIN, return type, tax period) and upsert, so re-processing converges instead of accumulating — and dedupe alerts on the underlying finding, not on the run.

Checkpoint per GSTIN, not per run, so a failed sweep resumes instead of restarting. On a large master that is the difference between a five-minute recovery and paying for eight thousand lookups twice. Registration and filing data is a product we run ourselves — gstinapi.com — and the current limits and field list live in its documentation rather than in this post, precisely because those numbers move.

What to do when the check itself fails

Every implementation eventually meets this at an awkward moment: the upstream is down or timing out and a payment run is waiting. Decide it in advance, because deciding at 4pm on a release day reliably produces "just push it through".

The sound default is that an unavailable check is neither a pass nor a fail. It is an unknown, and unknowns route to a human.

• Hold narrowly. Hold the lines you could not check, not the whole run. A blanket failure mode guarantees the control gets disabled.
• Fall back to cache with its age visible. Last cycle's result is often fine for a routine release, provided the reviewer can see it is last cycle's. Silent fallback is the dangerous version.
• Escalate on a timer. If checks have been failing longer than an interval you set, that is an incident someone should be told about, not a queue that quietly grows.
• Document the override. Store who released a held payment, when, and on what basis, alongside the last known filing data. That audit trail is most of the reason to build the control.
• Never write a failed check as a clean result. An exception is not a verification. Store the error state distinctly, or you will eventually have a vendor marked compliant on the strength of a 503.

Common questions

What is a GST return filing status API? It is an API that returns a taxpayer's recent GST return filing record for a given GSTIN — typically the return type, the tax period covered and the date each return was filed. It answers whether a business has been meeting its periodic return obligations, which is a different question from whether its registration currently exists and is active.

Can a GSTIN be active but not filing? Yes, and this is the normal case rather than an edge case. Cancellation for non-filing follows an administrative process that takes time, so a registration can read ACTIVE for many months while returns go unfiled. Checking registration status alone will not surface this; you have to look at the filing record itself.

Is GSTR-1 or GSTR-3B more important for input tax credit? They tell you different things. GSTR-1 is the outward supplies return, where a supplier reports the invoices it issued, and that reporting flows into the recipient's auto-drafted statement. GSTR-3B is the summary return where tax is declared and settled. A supplier who has stopped filing GSTR-1 is the more direct reporting risk for a buyer. Confirm how current rules apply with your own advisor.

How often should I check supplier filing status? Tie it to the filing cycle and to exposure rather than the calendar: one sweep per cycle across active vendors, an immediate re-check on anything flagged, and a fresh call before any payment release large enough to matter. Daily polling adds cost and rate-limit pressure without adding information, because the data only changes when a return is filed.

Where should the check live, onboarding or payment? Both, doing different jobs. Onboarding confirms a supplier was in good standing when you signed them and stops unsuitable records being activated. Payment release is where the check has leverage, because it is the last moment you can choose not to send money. A process that only checks at onboarding records a fact about a day that has already passed.

What should happen when the filing-status check is unavailable? Treat it as unknown rather than as a pass. Hold only the affected payment lines, allow a clearly labelled fallback to the cached result with its age shown, escalate if the outage persists, and record any human override with its justification. Writing a failed call into your records as a clean verification is the failure mode to design against.