GST E-Invoicing in India 2026: How IRN, the IRP API, and QR Codes Actually Work (A Developer's Guide)

If you are building or buying billing software in India in 2026, e-invoicing is the part most people misunderstand. It is not a fancier invoice template, and it is not the same as the GST invoice you already print. E-invoicing means every qualifying B2B invoice is reported to a government portal at the moment you raise it, and that portal hands back a unique number and a signed QR code that make the invoice legally valid. Get it wrong and your customer cannot claim input tax credit, your GSTR-1 will not match, and you can land a notice.

The mechanics live behind an API that is, frankly, more awkward than it needs to be: an encryption handshake, a strict JSON schema, a hash-based reference number, and a signed QR code you have to print. Most teams underestimate it, wire it up in a hurry, and then spend weeks chasing rejected invoices. This guide walks through how the system actually works, end to end, from a developer's point of view, so you can scope it properly or sanity-check whoever is building it for you.

We build this into billing software and custom CRMs for Indian businesses, usually on Laravel or Node.js, so the notes below come from shipping it, not just reading the spec. One caveat up front: GST rules and thresholds change. Treat the specific numbers here as a 2026 snapshot and confirm the current ones with your CA and the latest NIC documentation before you go live.

What GST e-invoicing actually is (and is not)

E-invoicing does not mean you generate the invoice on a government website. You still create the invoice in your own system. What changes is that, as you issue it, you send a structured version of that invoice to the Invoice Registration Portal (the IRP). The IRP validates it, generates a unique Invoice Reference Number (the IRN), digitally signs the invoice, attaches a QR code, and returns all of that to you. Only then is it a valid e-invoice. You print the IRN and the signed QR code on the PDF you give the customer.

Two clarifications that save a lot of confusion:

• It is for B2B, exports, and credit and debit notes, not B2C. Invoices to ordinary consumers do not go through the IRP. A separate dynamic-QR rule applies to large B2C sellers, but that is a different requirement.
• The IRP is not your accounting system. It is a registrar. It does not generate your invoice for you and it is not your system of record. It validates, signs, returns, and forwards the data to the GST system. Your software still owns the invoice.

Who has to do it: the turnover threshold

E-invoicing is mandatory based on aggregate annual turnover (AATO) in any financial year since GST began. The threshold has dropped steadily, from ₹500 crore in 2020 down to ₹5 crore as of August 2023. So as a 2026 snapshot, a business with annual turnover above ₹5 crore must generate e-invoices for its B2B supplies, exports, and credit or debit notes. Below that, it is currently optional.

This matters for software design even if your client is under the threshold today, because they may cross it, and because their larger customers increasingly expect e-invoices. Build the capability so it can be switched on per GSTIN rather than rewired later. And confirm the current threshold with your accountant, because this is exactly the kind of number that moves.

The flow, end to end

Strip away the jargon and the happy path is five steps:

1. Your software builds the invoice in the official e-invoice JSON schema (schema code INV-01).
2. You authenticate with the IRP and send that JSON to the generate-IRN endpoint.
3. The IRP validates it: GSTIN checks, a duplicate check, and field and tax validations.
4. On success it returns the IRN (a 64-character hash), a digitally signed invoice, and a signed QR code.
5. You store the IRN and acknowledgement, render the QR code on the invoice PDF, and hand it to the customer.

Everything else (cancellation, e-way bills, GSTR-1 population) hangs off that core round trip. The call usually completes in well under a second when the portal is healthy, which is why it is normally done at the moment of invoicing, with a queue and retry behind it for when the IRP is slow or down.

Direct NIC API or a GSP and ASP?

You can talk to the IRP two ways. The first is NIC's API directly (the National Informatics Centre runs the main IRP). The second is through a GSP (GST Suvidha Provider) or ASP (Application Service Provider), companies that sit in front of the IRP and give you a cleaner REST API plus extras like retries, logging, and multi-IRP failover.

For almost every business we build for, a GSP is the right call. The direct NIC API requires whitelisting your server IPs, owning the encryption handshake yourself, and handling raw error codes, and it is really aimed at very large taxpayers and ERPs. A GSP (Clear, Masters India, Cygnet, and others) abstracts the painful parts, costs a modest per-invoice or subscription fee, and gets you live faster. Go direct to NIC only when volume is large enough that a per-invoice fee genuinely hurts and you have the engineering time to own the handshake. Either way the concepts below are the same; a GSP just hides some of the encryption.

How the integration actually works

1. Authentication and the encryption handshake

This is the part that surprises people. With the NIC API you do not just send an API key. You generate a random AES key (the app key), encrypt it with NIC's public certificate, and send it along with your encrypted credentials to the auth endpoint. NIC returns a session key (SEK) encrypted with your app key, plus an auth token valid for a few hours. From then on, every request payload is AES-encrypted with the SEK and every response comes back encrypted too, so you decrypt it on the way in. You cache the token until it expires and re-authenticate when it does. A GSP usually does all of this for you and just gives you a bearer token, which is one of the main reasons teams choose one.

2. The invoice JSON schema

The invoice goes up as JSON in a fixed schema with clearly defined sections: transaction details, document details (type INV, CRN, or DBN, plus number and date), seller and buyer GSTIN and addresses, an item list with HSN codes, quantities, rates, and per-item tax, and the value and tax summary. Many fields are conditional and the validations are strict: HSN codes must be valid, state codes must match the GSTIN, tax amounts must add up within a small tolerance, and the document date cannot be in the future. The schema is versioned, so pin the version you build against and watch for updates.

3. How the IRN is generated

The IRN is a 64-character hash, and it is deterministic. It is derived from your supplier GSTIN, the document type (INV, CRN, or DBN), the document number, and the financial year (in YYYY-YY form), hashed with SHA-256. Because it is deterministic, the same invoice submitted twice produces the same IRN, and the IRP rejects the second attempt as a duplicate. That property is your friend: it makes the whole operation naturally idempotent, as long as you treat the duplicate response as success instead of an error.

4. The signed QR code

On success the IRP returns a signed QR code (a signed payload, JWT-style) containing the key facts of the invoice: supplier and buyer GSTIN, invoice number and date, total value, number of line items, the main HSN, and the IRN itself, all signed by the IRP so it cannot be forged. You must render this exact QR code on the invoice you give the customer. A GST officer can scan it to verify the invoice is genuine. Printing a plain QR code you generated yourself does not count; it has to be the signed one the IRP returned.

5. E-way bills in the same call

If the supply needs an e-way bill (goods above the value threshold moving between locations), you can ask the IRP to generate it in the same request by including transport details such as transporter ID or vehicle number, distance, and mode. The IRP returns the e-way bill number alongside the IRN, so you do not make two separate trips to two separate portals. For services or low-value goods, you skip this block entirely.

Cancellations, amendments, and the 24-hour rule

An e-invoice cannot be edited once it has an IRN. What you can do is cancel it, and only within 24 hours of generation, and only in full (there is no partial cancellation). After cancelling you generate a fresh invoice. Past the 24-hour window the IRP will not let you cancel at all; you correct the situation with a credit or debit note (itself reported as an e-invoice) and amend the entry in your GSTR-1. Your software has to enforce this: show a cancel option only inside the window, and route everything after it through credit notes.

There is also a reporting time limit to design around. Since 2025, businesses above a turnover threshold (₹10 crore as the 2026 snapshot, but confirm it) cannot report an invoice to the IRP more than 30 days after its document date. Practically, that kills the habit of batching up a month of invoices and reporting them late. Report at the point of invoicing, not at month end.

Auto-population into GSTR-1 and e-way bills

The payoff for all this is that the data flows onward automatically. Once an invoice has an IRN, its details auto-populate your GSTR-1 (the outward-supplies return), so you are not re-keying sales into the GST portal. If you generated an e-way bill in the same call, that is linked too. This is the real reason e-invoicing exists from the government's side: it wants the invoice at the source so returns, input tax credit, and e-way bills all reconcile against one authoritative record. From your software's side it means a clean handoff: get the IRN right and the downstream filing mostly takes care of itself.

The mistakes that quietly break e-invoicing integrations

The spec is not hard so much as unforgiving. The bugs we see most often:

• Treating the duplicate-IRN response as a failure. A retried request returns the existing IRN details, not an error to surface to the user. Handle it as success.
• No idempotency or queue. The IRP times out sometimes. Without an idempotent job and a retry queue you either lose invoices or double-submit and confuse your own records.
• Rounding and tax tolerance. Line-item tax has to sum to the invoice total within a tiny tolerance. Float math and inconsistent rounding cause silent rejections. Store money as integers in paise and round once, deliberately.
• Stale or unhandled token expiry. The auth token expires; if you do not refresh it, every call starts failing at the same time of day.
• GSTIN and state-code mismatches. The place of supply, the GSTIN state code, and the IGST versus CGST and SGST split all have to agree, or the IRP rejects the invoice.
• Special characters and field lengths. The schema is picky about allowed characters and maximum lengths; unsanitised addresses and item names trigger validation errors.
• Testing only on sandbox, or only on prod. NIC provides a sandbox (einv-apisandbox.nic.in). Build against it, but run a few real low-value invoices through production before trusting go-live, because sandbox and prod behaviour can differ.

How we build e-invoicing into billing software

Because this is money-and-compliance code, we treat it with the same care as the rest of a billing system: money stored as integers in paise, every IRP call wrapped in an idempotent background job, and a full log of every request and response so a rejected invoice can be diagnosed without guesswork. We almost always integrate through a GSP rather than the raw NIC API, keep e-invoice generation decoupled from invoice creation (so a slow IRP never blocks the user), and store the IRN, acknowledgement number, signed QR, and status against each invoice. On Laravel that is a queued job plus an events table; on Node.js it is the same shape with BullMQ or similar. It slots straight into the MultiVendor CRM and billing stack so invoicing, e-invoicing, payments, and GST all live in one place.

Common questions about GST e-invoicing

Is e-invoicing the same as the GST invoice I already generate?

No. Your GST invoice is the document. E-invoicing is the act of reporting that document to the IRP and getting back an IRN and a signed QR code that make it official. You still create the invoice in your own software; e-invoicing adds a government round trip as you issue it. The customer gets the same-looking PDF, now with the IRN and the signed QR printed on it.

Do I need e-invoicing if I sell only to consumers (B2C)?

Generally no. E-invoicing applies to B2B supplies, exports, and credit and debit notes. Pure B2C invoices do not go through the IRP. There is a separate dynamic-QR-code requirement for large B2C sellers, but that is a different rule with its own threshold. If your turnover is above the limit and you have any B2B sales at all, those B2B invoices need e-invoicing.

Should I use a GSP or the NIC API directly?

For almost everyone, a GSP. It hides the encryption handshake, manages tokens and retries, and gets you live in days instead of weeks, for a small per-invoice or subscription fee. Go direct to NIC only at very high volume where per-invoice fees add up and you have the engineering time to own IP whitelisting and the encryption yourself.

Can I cancel or edit an e-invoice?

You cannot edit one. You can cancel it in full within 24 hours of generating the IRN; after that you must issue a credit or debit note (also an e-invoice) and amend your GSTR-1. Build the 24-hour window into the software so users are not trying to cancel invoices the IRP will refuse to cancel.

What is the IRN and where does it come from?

The IRN (Invoice Reference Number) is a unique 64-character hash the IRP generates from your GSTIN, the document type, the document number, and the financial year. It is the proof that the invoice was registered. Because it is deterministic, the same invoice always maps to the same IRN, which is what stops duplicates and makes safe retries possible.

How long does it take to add e-invoicing to existing billing software?

Through a GSP, a clean integration is usually 1 to 3 weeks depending on how tidy your existing invoice data is and how many document types (regular invoice, credit note, export, e-way bill) you need to support. Most of the time goes into mapping your data to the schema correctly and handling the error and retry cases, not the happy path.

What happens if the IRP is down when I raise an invoice?

You queue and retry. A well-built integration creates the invoice immediately, attempts the IRP call in a background job, and retries with backoff if the portal is slow or down, while staying inside the 30-day reporting window. The customer is not blocked and no invoice is lost. This is exactly why idempotency and a queue matter.

Honest summary

E-invoicing is not complicated in theory: report the invoice, get an IRN and a signed QR, print them. The difficulty is in the details the spec enforces without mercy, the encryption handshake, the strict schema, the deterministic IRN and its duplicate behaviour, the 24-hour cancellation window, and the 30-day reporting limit. Teams that respect those details ship something boring and reliable. Teams that rush them spend the next month firefighting rejected invoices and customers who cannot claim their credit.

If you are adding e-invoicing to a billing system, or building one from scratch, the safe path is a GSP, an idempotent queue, money as integers, and real production testing before go-live. The cost calculator gives a rough estimate for a build, or send us a WhatsApp message with your GSTIN setup, invoice volume, and current software, and we will reply within 24 hours with a written scope. As always, confirm the current GST rules with your CA before you ship.