GST E-Invoicing API Integration: IRN, IRP, GSP

Description

Integration GST e-invoicing API integration: IRN, IRP, GSP and the signed QR code

A GST e-invoice integration sends each B2B invoice, credit note and debit note from your billing system to an Invoice Registration Portal as JSON and stores the Invoice Reference Number and signed QR code that come back, before the invoice is issued. WavX builds that connection into custom billing, ERP and e-commerce systems. Rules on this page are from government and IRP sources as read on 2 October 2026; it is not tax advice.

Discuss an integration Last updated 2 October 2026

What the integration does

Under GST e-invoicing, a covered business does not simply print an invoice. Its software first reports the invoice to an Invoice Registration Portal (IRP). The IRP validates it, registers it, and returns an Invoice Reference Number (IRN) with a digitally signed copy and a signed QR code. Only then is the invoice issued, with the IRN and QR code on it.

Four terms carry the whole mechanism:

IRP: the portal that registers invoices. The National Informatics Centre (NIC) runs the e-Invoice System at einvoice1.gst.gov.in, and GSTN has authorised further IRPs, of which IRIS IRP (einvoice6.gst.gov.in) is one.

IRN: per the IRP's FAQ, a unique 64-character hash computed from the supplier GSTIN, the financial year, the document type and the document number.

GSP: a GST Suvidha Provider, a licensed intermediary whose API your software calls when it cannot call the IRP directly.

Signed QR code: issued by the IRP and printed on the invoice. It carries the supplier and recipient GSTINs, invoice number and date, invoice value, the number of line items, the HSN code of the main item, the IRN and its date.

Billing / ERP / store back end GSP (or direct) IRP

------------------------------ --------------- ---

invoice approved -> build JSON -> authenticate, forward -> validate, register

store IRN, AckNo, signed QR <- response <- IRN + signed invoice + QR

print invoice with IRN and QR

credit note / cancellation -> same route -> new IRN / cancelled status

Applicability, as read on 2 October 2026

Rule

Source and what it says

Turnover threshold

Notification 10/2023-Central Tax (10 May 2023): taxpayers with aggregate turnover exceeding ₹5 crore, from 1 August 2023

Documents

B2B invoices, credit notes and debit notes; the API's document types are INV , CRN and DBN

B2C

Not covered by e-invoicing, per the IRP FAQ

Reporting time limit

Taxpayers with aggregate annual turnover of ₹10 crore and above must report within 30 days of the invoice date, from 1 April 2025; later attempts cannot get an IRN

HSN codes

NIC's portal states 6-digit HSN codes are mandatory for turnover above ₹5 crore

Thresholds have been lowered in steps since 2020. Have your accountant confirm the position for your business before scoping; this page describes the mechanism and is not advice.

Data that flows each way

Event or object

Direction

What your system does with it

Login (username, password, app key, encrypted with the IRP's public key)

Your system to IRP or GSP

Receives an auth token and a session encryption key; reuses them until expiry

Invoice JSON ( TranDtls , DocDtls , SellerDtls , BuyerDtls , ItemList , ValDtls )

Your system to IRP

Builds it from the approved invoice and encrypts the payload

Irn , AckNo , AckDt , SignedInvoice , SignedQRCode

IRP to your system

Stores all five against the invoice and renders the QR code on the PDF

E-way bill details (optional, with distance)

Gets EwbNo in the same call when goods are moving

Cancel request (IRN, reason code)

Marks the invoice cancelled only when the IRP confirms

Get IRN details, by IRN or by document

Recovers the result after a timeout instead of resubmitting

The main flow, step by step

Choose the route. Direct API access if you qualify, otherwise a GSP or an ERP provider with access.

Test in the sandbox. NIC provides a sandbox, and for direct access asks for a test summary report covering success and failure cases before production. Its page says verification and IP whitelisting may take 4 to 5 days.

Authenticate. Call the Authentication API and keep the token. NIC states it is valid for 360 minutes in production and 60 in the sandbox.

Generate the IRN when the invoice is approved, not when it is drafted. The IRN cannot be changed afterwards.

Store the response and print the invoice with the IRN and signed QR code.

Handle corrections by cancelling within the window, or by credit and debit notes.

Reconcile daily. Every invoice that should have an IRN has one; anything pending is listed for a person.

Limits and rules the API documents

What NIC's documentation says

API versions

v1.04 for authentication and GSTIN APIs, v1.03 for IRN and e-way bill APIs, as listed on 2 October 2026

Transport

TLS 1.2 or higher; the request payload is encrypted with the session key; responses are signed (JWT/JWS, SHA256 with RSA)

Duplicates

A second IRN cannot be generated for the same supplier, document type, document number and financial year

Invoice size

1 to 1,000 line items; JSON payload up to 2 MB

Recipient

The recipient GSTIN must be registered and active or suspended on the document date

Cancellation

Within 24 hours of generation; not while a valid e-way bill exists; reason codes 1 to 4 (duplicate, data entry mistake, order cancelled, others)

Repeated identical requests

NIC's API FAQ says a user who keeps firing duplicate requests is blocked for one hour

Production access

At most four whitelisted static IP addresses, registered in India

Common failure modes

Timeout treated as failure. The IRP registered the invoice but the response was lost. Resubmitting returns a duplicate error. The fix is to fetch the IRN by document details first.

A new token per invoice. The token lasts hours; logging in for every call is slow and can get the user blocked.

Master data errors. A cancelled recipient GSTIN, a 4-digit HSN code, or a pin code that does not match the state fails validation. These belong in customer and item masters, checked before billing.

Totals that do not add up. Item values, tax and rounding must agree with the invoice totals the IRP recomputes.

Late reporting. An invoice left in draft past the 30-day limit cannot get an IRN.

Edits after issue. Staff change an invoice in the billing system after the IRN exists, and the printed document no longer matches the registered one. The system must lock it.

What WavX builds around it

WavX lists GST and e-invoicing APIs among the integrations for its custom software and e-commerce work. For a client who needs e-invoicing inside their own system, WavX builds:

The mapping from your invoice model to the e-invoice JSON schema, with validation before submission.

The connection to your chosen GSP, or to the IRP where you hold direct access, including token reuse and payload encryption.

IRN, acknowledgement and signed QR storage, and invoice PDFs that print them.

Cancellation, credit note and debit note flows that follow the IRP's rules.

A queue with safe retries, lookup-before-resubmit, and a daily exception list.

Posting of the same invoices to accounts; see Tally integration.

It fits inside builds such as retail billing software and custom ERP development . WavX does not publish a price for a single integration; it is quoted after scoping. For planning, the software cost estimator carries third-party integrations as a ₹60,000 feature line on top of a base build. Its output is a planning range, not a quote. GSP charges are separate and set by the GSP.

When off-the-shelf software is enough

You already bill from accounting software. Tally's plans page lists e-invoicing among TallyPrime's features. If invoices are raised there, no integration is needed.

A few invoices a month. The IRP FAQ lists direct entry on the web portal and an offline bulk upload utility alongside the API routes.

A standard store with an invoicing app. See the Shopify to Tally page for what the apps cover.

Custom integration earns its cost when invoices are created in your own software: a custom ERP, a billing system, a B2B ordering portal or a marketplace back end, where staff should not retype an invoice into another tool to get an IRN.

Frequently asked questions

Who has to generate e-invoices?

Notification 10/2023-Central Tax, as listed by the GST Council, applies e-invoicing to taxpayers with aggregate turnover exceeding ₹5 crore from 1 August 2023, and the IRIS e-invoice portal still showed that threshold when read on 2 October 2026. Whether your business is covered, and which exemptions apply, is a question for your chartered accountant.

Can I connect my software straight to the government portal?

Only some taxpayers can. NIC&#x27;s onboarding page restricts direct API access by turnover (₹100 crore and above in the previous financial year, as read on 2 October 2026) and allows at most four whitelisted Indian static IP addresses. Everyone else connects through a GST Suvidha Provider (GSP) or an ERP provider that already holds access.

Can an e-invoice be edited after the IRN is generated?

No. The IRP does not allow amendment. An IRN can be cancelled within 24 hours of generation, and not at all while an active e-way bill exists for it. After that window the correction is a credit note or debit note, which is itself reported for an IRN.

Do B2C invoices need an IRN?

The IRP&#x27;s own FAQ says B2C invoices are not covered by e-invoicing; it applies to B2B invoices, credit notes and debit notes, including the export and SEZ supply types the API accepts. Other rules can apply to B2C invoices, so confirm with your accountant.

Do you provide tax or legal advice?

No. We build the software that produces and stores the documents. Which transactions are covered, which exemptions apply and how to treat an edge case are decisions for your chartered accountant or tax adviser, and we build to their instructions.

Sources

GST Council: Notification 10/2023-Central Tax, dated 10 May 2023 · read 2 October 2026

e-Invoice System (NIC), einvoice1.gst.gov.in · read 2 October 2026

IRIS IRP (einvoice6.gst.gov.in): e-invoicing mandate under GST · read 2 October 2026

IRIS IRP (einvoice6.gst.gov.in): e-invoice FAQ · read 2 October 2026

NIC e-Invoice API sandbox: API list and versions · read 2 October 2026

NIC e-Invoice API sandbox: API overview · read 2 October 2026

NIC e-Invoice API sandbox: Authentication API · read 2 October 2026

NIC e-Invoice API sandbox: Generate IRN API · read 2 October 2026

NIC e-Invoice API sandbox: Cancel IRN API · read 2 October 2026

NIC e-Invoice API sandbox: on-boarding · read 2 October 2026

NIC e-Invoice API sandbox: FAQs on API · read 2 October 2026

Tally Solutions: TallyPrime plans · read 2 October 2026

Related

Custom ERP development

Build your own software — your way, your pricing.

WavX Solutions is here to create your own software in a fully custom way, built exactly how you work — with a pricing model that fits your business. Connect now and let&#x27;s build it.

Contact Now helpwavx@gmail.com