GST E-Invoicing API: How to Generate IRNs from Your Own App

If your application issues B2B invoices and your business has crossed the e-invoicing turnover threshold, every one of those invoices must be reported to the government's Invoice Registration Portal and carry an IRN before it is valid. For a product team, that turns a compliance rule into an engineering question: how do you wire an e-invoicing API into your own app so IRNs are generated automatically, failures are handled sanely, and nothing ships to a customer without its QR code? This guide covers the flow, the failure modes, and the architecture decision that saves you the most pain.

Who must generate e-invoices (and how to check)

E-invoicing applies once your aggregate annual turnover (PAN-wide, across all GSTINs) crosses a government-notified threshold in any financial year from the notified base year onward — and once you are in, you stay in, even if turnover later falls. The threshold has been reduced repeatedly by notification (₹5 crore as of 2026), so treat any figure you read — including this one — as something to confirm on gst.gov.in or with your CA before you make architecture decisions around it. It covers B2B tax invoices, export invoices, and B2B credit/debit notes; plain B2C invoices are out of scope. For the applicability rules in full, see our complete guide to GST e-invoicing.

The IRP flow: what actually happens

Mechanically, e-invoicing is a reporting handshake that happens at the moment of invoice creation:

1. Your system assembles the invoice in the notified INV-01 schema — a strict JSON structure covering supplier, buyer, line items, HSN codes, tax splits, and totals.
2. The payload is submitted to an Invoice Registration Portal (IRP).
3. The IRP validates it — schema checks, GSTIN validity, duplicate detection — and on success returns an IRN (a unique hash of supplier GSTIN, document number, type, and financial year), a signed QR code, and a signed copy of the invoice.
4. You print the QR code on the invoice you give the buyer. Without it, an e-invoicing-liable B2B invoice is not a valid document.
5. The reported data flows onward to the GST system, auto-populating the relevant sections of your GSTR-1.

Note the ordering: the IRN is obtained at creation time, not at filing time. Your integration has to treat "invoice created" and "IRN obtained" as one logical step — an invoice sitting in a customer's inbox without its IRN is a compliance failure, not a pending task. Businesses above a notified turnover level also face a hard reporting window (currently 30 days from the invoice date for larger taxpayers) after which the IRP refuses the document entirely; confirm whether the window applies to you, and design as if it does.

Why you should not integrate the IRP directly

It is technically possible to register and call the IRP APIs yourself. Almost nobody should. The reasons teams regret it:

• Schema churn — the INV-01 schema, validation rules, and error codes evolve by notification. A direct integration means you own that maintenance forever.
• Error taxonomy — the IRP rejects payloads for dozens of reasons (inactive buyer GSTIN, HSN mismatches, rounding beyond tolerance, duplicate document numbers). Mapping each to a sane recovery path is a project in itself.
• Two systems to reconcile — if invoicing lives in one system and IRN generation in another, you have created a new reconciliation problem: invoices without IRNs, IRNs without booked invoices.
• Credential and session management — IRP access via GSP channels, token refresh, and environment separation is undifferentiated plumbing.

The better architecture is to integrate an accounting platform whose invoice-creation API handles IRP submission internally (Invodo does this via a licensed GSP). Your app makes one call — create the invoice — and the platform returns the invoice with its IRN and QR code, or a clear, actionable error. One call, one record, nothing to reconcile.

Handling failures: rejections, duplicates, cancellations

Design your integration around the three failure classes:

• Validation rejections — bad buyer GSTIN, missing HSN, tax calculation outside tolerance. These are your data's fault and retrying unchanged will fail identically. Surface them to a human queue with the IRP's reason, fix the master data, and resubmit. Most rejections are preventable by validating GSTINs at customer onboarding and keeping HSN codes on your product master.
• Duplicates — the IRP will refuse a document number it has already registered. If you see this, your retry logic created two submissions for one invoice; fix the idempotency handling in your integration rather than bumping the number. Our guide to idempotency, retries and webhooks covers the correct pattern.
• Cancellations — an IRN can be cancelled within 24 hours of generation (if no active e-way bill rides on it). After that window, the invoice stands and corrections must flow through a credit note. Your refund/cancellation flow needs both branches: cancel-IRN when inside the window, credit note when outside it.

One more rule worth encoding: e-invoices cannot be edited. Any "edit invoice" feature in your app must, for IRN-bearing documents, actually mean cancel-and-reissue (within the window) or credit note plus new invoice.

What the integrated flow looks like in your app

With the platform handling the IRP, your application code stays small:

1. Order or billing event fires; your backend calls the invoice-creation API with the line items, buyer reference, and an idempotency key.
2. The platform validates, assigns the invoice number, submits to the IRP, and posts the invoice to the ledger — atomically.
3. Your webhook receives either invoice ready (with IRN, QR, and document URL to attach to the order) or IRN failed (with the rejection reason for your operations queue).
4. GSTR-1 data assembles itself from the same records — nothing extra to build.

If your invoices originate from web orders specifically, the field-mapping details are in automating GST invoices from website orders; for the full architecture including batch flows, see the invoicing API integration guide.

Checklist before you go live with e-invoicing

• Confirmed current applicability threshold and your enablement status on the e-invoice portal.
• Buyer GSTINs validated at onboarding; HSN/SAC codes complete on the product master.
• Idempotency keys on every create call; no client-side retry can double-submit.
• Rejection queue wired to a human with the IRP reason visible.
• Cancellation flow branches correctly on the 24-hour window.
• Invoice templates render the signed QR code; documents are only released with it.

Let the platform carry the compliance

E-invoicing is the strongest single argument for integrating an accounting-grade API rather than assembling your own stack: the mandate is unforgiving, the rules move, and none of it differentiates your product. Invodo generates IRNs and signed QR codes as part of invoice creation, handles rejections and cancellations, and keeps the same records flowing into your ledger and GSTR-1. See how e-invoicing works in Invodo, or view pricing to get started.