If your business crosses ₹5 crore in aggregate turnover and you raise B2B invoices from your own software, every one of those invoices has to be registered with a government portal before it is legally an invoice. That is no longer an accounting task. It is an integration your billing code has to get right, every time, including at 11pm on the last day of the month.
Most businesses never notice, because Tally or Zoho Books does it for them. This post is for the ones whose invoices start somewhere else — a custom ERP, a SaaS billing module, an order system, a marketplace backend — and who now have to decide whether to wire it in themselves, hand it to a provider, or move invoicing back into accounting software.
Who actually has to e-invoice?
Since 1 August 2023, any registered business whose aggregate turnover in any preceding financial year from 2017-18 onwards exceeded ₹5 crore must generate e-invoices for supplies to registered persons and for exports. That is Notification 10/2023 – Central Tax, which brought the threshold down from ₹10 crore. A few categories remain exempt, including banks, insurers, SEZ units and government departments.
Two details trip people up.
"Any preceding year" means once you cross, you stay in. A bad year does not take you out of scope. If you crossed ₹5 crore in 2021-22, you are e-invoicing now.
It is B2B and exports, not B2C. The IRP's own API documentation says B2C invoices are not considered. If your app sells only to consumers, this post mostly does not apply to you yet. If it sells to both, your code has to know which is which before it decides whether to call the portal — which in practice means capturing and validating the buyer's GSTIN properly, not as an optional free-text field.
What the integration actually does
The flow is simpler than the paperwork around it suggests.
- Your system builds the invoice as JSON in the government's schema.
- It authenticates and sends that JSON to an Invoice Registration Portal (IRP).
- The IRP validates it and returns an Invoice Reference Number (IRN), a digitally signed copy of the invoice, and a signed QR code.
- Your system stores all three and prints the QR code on the invoice the customer receives.
There is no longer only one IRP. Alongside NIC's portal, GSTN has empanelled several private IRPs, and an invoice registered on any of them is valid. For an engineering team that mostly matters as a resilience option: if one portal is slow on the last day of the month, there is somewhere else to send traffic, provided you have built for it.
A few specifics from the NIC API documentation shape the build:
- The IRN is a hash, not a sequence. It is a SHA-256 of the supplier's GSTIN, the document number, the document type and the financial year. The same invoice number for the same document type in the same year can only ever produce one IRN.
- Authentication is session-based and encrypted. You exchange credentials for an auth token and a session key (AES-256) that is used to encrypt each request. The authentication spec gives the token a validity of 360 minutes in production and allows a forced refresh only in the final ten minutes. Token handling across multiple servers or workers is one of the places homegrown integrations go wrong.
- Document numbers have rules. Up to 16 characters, and they cannot start with
0,/or-. If your existing numbering scheme is0001/24-25, that needs to change before go-live, not after the first rejection. - Cancellation has a 24-hour window. The cancel IRN API only accepts cancellations within 24 hours of generation, and refuses entirely if an active e-way bill exists against the invoice. After that, a mistake is fixed with a credit note, not a delete button.
Direct API, a GSP, or your accounting software?
There are four realistic routes. The right one depends almost entirely on where your invoices are born.
| Route | Who it suits | What you build | Main trade-off |
|---|---|---|---|
| Raise invoices in Tally or Zoho Books | Invoices are created by finance, not by your product | Nothing — Zoho Books and TallyPrime both act as GSPs | Your app and your books can drift apart |
| Your app via a GSP's API | Invoices are created by your product at volume | JSON mapping, retries, storage, QR rendering | A provider fee and a dependency, but they absorb portal changes |
| Your app direct to the IRP | Large taxpayers with an in-house team | Everything above plus encryption, token management and failover | You own every schema change |
| Manual upload or offline tool | Very low volumes | Nothing | Does not survive growth, and the 30-day rule makes lateness costly |
On direct access: eligibility for connecting straight to the IRP, without a GST Suvidha Provider in between, has historically been restricted to large taxpayers. We could not find a current primary source that states the threshold cleanly, and the secondary sources we found contradict each other, so check eligibility on the portal itself before planning around it. For most businesses between ₹5 crore and a few hundred crore, the realistic choice is between a GSP and an accounting package.
Our honest default: if invoices are raised by people, keep them in accounting software. If invoices are raised by your product — an order is confirmed, a subscription renews, a shipment is dispatched — integrate through a GSP, and design the code so that switching GSP is a configuration change rather than a rewrite.
The four things that actually break
The happy path takes days. These take the months.
1. Lost responses and duplicate IRNs
Your system sends an invoice, the IRP registers it, and the response never arrives — a timeout, a dropped connection, a deploy at the wrong moment. Your code retries, and gets error 2150: duplicate IRN.
NIC's own note on the most common errors puts this first, and the guidance is useful: a repeat request with the same payload returns the existing IRN details, so a correctly built retry is safe. But it also asks integrators to save every successful response, flag the invoice as registered, and never send the same payload more than twice. It warns that identical requests fired at the same instant from different threads can fail or produce token errors.
In practice this means the e-invoice call belongs in a queue with one worker per invoice, an idempotency flag in your database, and a "fetch existing IRN" path for when a retry says it already exists. Firing it from a request handler and hoping is how teams end up with invoices that are registered on the portal but not in their own system.
2. Master data that is wrong in boring ways
The same note lists the other top rejections: inactive or unsynced GSTINs, HSN codes padded with zeros to look like eight digits when the valid code is four, and PIN codes that do not belong to the state code supplied. None of these are API problems. They are customer and product master data problems that the IRP surfaces at the worst possible moment — when someone is trying to dispatch an order.
Validate the buyer's GSTIN when the customer is created, not when they are invoiced. Keep HSN codes in a controlled list matched against the portal's master codes. Check PIN against state at address entry. Most rejection volume disappears once the data is clean at the point it enters the system.
3. The 30-day reporting limit
Since 1 April 2025, businesses with aggregate annual turnover of ₹10 crore or more cannot report an invoice, credit note or debit note to the IRP more than 30 days after its date. The portal simply rejects it.
This turns a silent failure into a permanent one. An invoice stuck in a failed state for five weeks because nobody looked at an error log cannot then be registered at all. So the integration needs a visible queue of unregistered invoices, ageing, with an alert well before day 30 — something a person in finance actually sees, not a log line an engineer might notice.
4. The schema keeps moving
This is the part most build estimates leave out. The NIC sandbox announcements for 2026 alone include a relaxed validation on invoice totals for certain HSN codes in February, a set of changes to Generate IRN and e-way bill APIs announced in June and then marked withdrawn, related e-way bill changes put on hold at the end of July, and reverse-charge self-invoices added in October.
None of that is a criticism; tax systems change. But it means the integration is not a one-off build. Someone has to read those announcements, test in the sandbox, and ship changes on the government's timetable rather than yours. If that someone does not exist on your team, that is the strongest argument for a GSP, whose business is absorbing exactly this.
What a sound build looks like
If you do integrate from your own product, the shape we would argue for is:
- An invoice state machine, not a boolean. Draft, ready, submitted, registered, rejected, cancelled, credit-noted. Every transition logged with the request and response.
- A queue between invoice creation and IRP submission, with a single owner per invoice, bounded retries, and the fetch-existing path for duplicates.
- The signed invoice and signed QR stored as returned, not regenerated. Those are the legal artefacts; your PDF is a rendering of them.
- A provider interface so the GSP or IRP is swappable, and a second one is configured for the days the first is slow.
- An operations view for finance: what is unregistered, how old it is, why it was rejected, and a button to retry after fixing the data.
- Numbering and master data fixed first, before a single API call is written.
This is close to the shape of the compliance work we did for Numericalz, a UK accounting firm, where the outcome that mattered was 100% compliance on deadlines. That did not come from the screens. It came from making the state of every obligation visible and chasing it automatically before it went late — the same principle that makes the 30-day rule manageable.
When you should not build this
If your invoices are raised by a finance team in Tally or Zoho Books, do not build anything. Both register invoices with the IRP already. The work is in your process, not your code.
If you raise fewer than a few dozen B2B invoices a month from a custom system, do not build an integration either. Export them into your accounting software and register them there. The engineering cost will not pay back, and the schema changes will still arrive.
If you are tempted to build a direct IRP integration to avoid a GSP fee, be sure you have someone who will own it for years, not for the length of the project. An unmaintained e-invoice integration is a compliance risk that announces itself on the day a schema change goes live.
And if the real problem is that your product and your books disagree, fix that first. E-invoicing makes those disagreements expensive and visible — an IRN registered for an invoice your accounts do not know about is worse than no integration at all.
Where to start
Find out whether you are in scope and which thresholds apply to you — the ₹5 crore threshold for e-invoicing and the ₹10 crore threshold for the 30-day rule. Then work out where your invoices are actually born. That one answer decides most of the rest.
If they are born inside your own product and you want a second opinion on whether to integrate, which route to take, or how to make an existing integration stop failing at month-end, tell us what you are running. We build custom web applications and the operational plumbing around them, and we will tell you plainly if the answer is "keep it in Zoho Books".
Bharat Vasireddy
Founder & Digital Marketing Strategist8+ years of experience in performance marketing and web development. I help businesses scale through data-driven SEO, Google Ads, and high-performance websites.