E-Invoice Status API: Tracking IRN and Cancellation

"E-invoice status API" gets used for two genuinely different things, and picking the wrong one wastes weeks. One is per-invoice IRN status — was an IRN generated for this document, and has it since been cancelled — which lives on the Invoice Registration Portal and requires IRP or GSP access. The other is per-taxpayer e-invoicing eligibility — is this GSTIN required and enabled to issue e-invoices at all — which is part of the public taxpayer record and is what a GSTIN verification API returns.

A large manufacturer tracking IRN generation and cancellation needs the first. Anyone screening suppliers or customers before they transact needs the second. Most compliance stacks need both, wired together. This page explains each, and where the boundary sits.

Two different questions people call "e-invoice status"

Rows one and two are filing-grade operations on a taxpayer's own invoices. Rows three and four are counterparty due diligence, which anyone can perform on any GSTIN. Our API answers rows three and four — taxpayer_data.einvoiceStatus in the response documented in the API reference — and does not generate, cancel or look up IRNs. Being clear about that boundary is more useful than pretending the categories are one product.

The IRP APIs that answer the IRN question

Whether you go direct to an IRP or through a GSP, the same operations are exposed, and a tracking system for a manufacturer typically uses four of them.

• Generate IRN. Submit the invoice payload in the notified e-invoice schema; receive the IRN, the acknowledgement number, the acknowledgement date and the signed QR code. This is the moment your own record must be written.
• Get IRN. Fetch the registered invoice by its IRN. This is your confirmation path when a generation response was lost to a timeout.
• Get IRN by Document Details. Look the IRN up by document type, document number and document date instead. This is the call that rescues you when your side has no IRN stored — the timeout case above — because it lets you ask "did this document already register" using data you definitely have.
• Cancel IRN. Cancel within the 24-hour window, with a reason code and remark.

The 24-hour cancellation window and what it means for tracking

An IRN can be cancelled on the IRP within 24 hours of generation. Past that, the IRP will not cancel it and the commercial correction has to be made through a credit note reflected in your returns instead. Note also that cancellation is all-or-nothing: an e-invoice cannot be partially cancelled or amended on the IRP, so a corrected invoice means cancel-and-reissue inside the window, or a credit note outside it.

The design consequence is specific. A nightly reconciliation job is too slow to be your cancellation control, because the window can open and close between two runs. What you want instead is:

• An event written the moment a cancellation is requested internally, with the IRN generation timestamp attached so the remaining window is computable.
• An alert when a cancellation request arrives with less than, say, two hours left — that is a human escalation, not a queued job.
• An automatic branch to the credit-note path when the window has closed, so the correction is never silently dropped.

The e-invoicing obligations that sit behind all of this — who must issue e-invoices, and the reporting time limit for uploading documents to the IRP — are covered in the e-invoicing threshold guide.

Checking whether a counterparty is e-invoicing enabled

This is the half of the problem a verification API does solve, and it is the half most stacks skip.

If a supplier is required to issue e-invoices and instead sends you a plain tax invoice with no valid IRN, that document is not a compliant invoice — and your input tax credit against it is exposed. You will not learn this from the invoice itself; you learn it from the supplier's GSTIN record. One call returns it:

curl -H "x-api-key: YOUR_API_KEY" \
  https://gstinapi.com/api/get-taxpayer-info/27AAACR5055K1Z7

# taxpayer_data.einvoiceStatus  -> whether this taxpayer is enabled for e-invoicing
# taxpayer_data.status          -> Active / Cancelled / Suspended
# filing_data                   -> recent GSTR filing history

Wire that into two places: supplier onboarding, so the expectation is set before the first invoice, and a periodic re-check, because a supplier who was below the threshold last year may be above it now. The onboarding side is covered in GST verification for vendor onboarding, and the recurring side in automated daily vendor GSTIN monitoring.

A tracking architecture for a large manufacturer

At manufacturing volumes — thousands of invoices a day across multiple plants and GSTINs — the architecture that holds up looks like this:

1. One outbound queue per GSTIN. Different registrations have different credentials and different rate ceilings; sharing one queue across them turns a problem at one plant into an outage everywhere.
2. Write-ahead of the IRN request. Persist the document with a pending_irn state before calling the IRP, so a crash mid-call leaves a record you can reconcile rather than an invoice nobody knows about.
3. Store IRN, Ack No and Ack Date against your own document number on success. This mapping is the entire basis of later reconciliation; without it you are matching on amounts and dates, which does not scale.
4. Reconcile on a schedule — every document in pending_irn older than a few minutes gets a Get IRN by Document Details call to resolve its true state.
5. Track the cancellation window as a first-class timer, as described above.
6. Screen counterparties separately with GSTIN verification, on a cadence, so the inbound side of the ledger is covered too.
7. Alert on the gap metric: documents issued minus IRNs confirmed, per GSTIN, per day. A non-zero, growing gap is the single number that tells you something is wrong upstream.

Choosing between an IRP, a GSP and a verification API

Most manufacturers end up with a GSP for the outbound e-invoicing path and a lightweight verification API for inbound counterparty screening, because the two jobs have different volumes, different budgets and different failure consequences. Buying one product for both usually means overpaying for screening or underserving the filing path. The related build decisions are in adding e-invoicing to billing software and checking e-invoice status in bulk.

Frequently asked questions