Who needs e invoice API integration?
You need GST e-invoicing if you are a notified taxpayer; you need an API integration specifically when your invoices are produced by software that cannot generate IRNs on its own, or when manual uploads have become a bottleneck.
CBIC Notification 10/2023–Central Tax brought businesses whose aggregate turnover exceeded five crore rupees in any financial year from 2017-18 onwards under e-invoicing from 1 August 2023. The GSTN e-invoice FAQ explains that the system covers invoices, credit notes and debit notes issued to registered persons, supplies to SEZs, exports and deemed exports, while B2C invoices are not reported to the IRP. Whether a particular business is covered is a question for its CA; our job starts once that answer is yes.
Three situations call for a custom integration: custom billing software written years ago that has no e-invoice feature; an ecommerce or distribution backend that invoices B2B orders; or an ERP whose e-invoicing module does not fit their workflow. In all three, the goal is the same: the invoice is saved, the IRN comes back, and the printed copy carries the QR code without extra steps. For whole-system rebuilds, see billing software developer.
How the e-invoice API flow works, end to end
Your system authenticates, sends invoice JSON, receives a signed response with the IRN and QR code, stores it, and prints the QR on the invoice. Cancellations and e-way bills are separate calls on the same IRN.
Authenticate
Your software obtains a session token using credentials issued by the IRP or your GSP. Tokens expire, so the integration refreshes them automatically instead of failing mid-batch.
Generate
The invoice is converted to the schema and posted. The IRP validates key fields, checks the document is not already registered and, if all is well, returns the IRN, a 15-digit acknowledgement number and date, the signed invoice and the signed QR code.
Store and print
The GSTN FAQ is clear that the IRP returns only signed JSON, not a PDF, and does not archive it. Your software must save the response and render the QR code image on the invoice copy.
Follow-up actions
Within 24 hours you may cancel the IRN. Transport details can generate an e-way bill from the IRN. Corrections after that go through credit or debit notes and return amendments.
Because the IRN is a unique 64-character hash built from the supplier GSTIN, document type, document number and financial year, sending the same invoice twice is rejected as a duplicate. The integration therefore treats "already registered" as a signal to fetch and store the existing IRN, not as a failure.
GSP or direct IRP access: which should you choose?
Choose a GSP when you want a provider to handle connectivity, support and sometimes extra features; choose direct IRP access when you are eligible, have developers to maintain the integration and prefer fewer parties in the chain.
The GSTN e-invoice FAQ lists three modes: API integration directly with the taxpayer's system, API integration through a GSP or ASP, and the free offline bulk generation tool. GSTN's published comparison of the six Invoice Registration Portals (dated November 2023) shows that eligibility for direct access differs by portal: on some IRPs the direct API option was offered only above an aggregate turnover of 100 crore rupees, while others opened direct integration to all e-invoicing taxpayers. The same document notes that core e-invoice APIs are free of cost on the IRPs. Rules change, so we confirm current eligibility on the portal you pick before the build.
Practically, a mid-sized business with one billing system is often best served by a GSP connection, because the GSP handles the credential process and gives you a support desk. A larger group with in-house IT and several systems may prefer direct access. Either way, we keep the route behind one internal interface, so switching later changes configuration, not your invoicing code.
Mapping your invoice data to the e-invoice JSON schema
Mapping is where most of the work sits. Every field your software stores has to land in the right place in the schema, in the right format, with the right code lists.
The GSTN FAQ describes the schema (INV-01) as a single national standard based on PEPPOL and UBL, with mandatory and optional sections and cardinality rules for each field. In practice the payload has transaction details (supply type, reverse charge), document details (type, number, date), seller and buyer details including GSTINs, state codes and place of supply, optional dispatch-from and ship-to details, an item list with HSN, quantity, unit, rate, discounts, taxable value and tax amounts, value totals, and optional payment, reference, export and e-way bill sections.
The traps are predictable: unit codes that do not match the allowed list, state codes stored as names, rounding that makes item totals differ from the invoice total by a paisa, HSN codes missing on service lines that need SAC, and free-text addresses that exceed field lengths. We write a mapping document with your accountant, then build validation into your software so bad data is caught before it reaches the portal. The HSN master on the e-invoice portal is a useful reference during this step.
Testing an e invoice API integration in the sandbox
Every integration should be tested in the IRP sandbox before touching production. The NIC portal points developers to its API sandbox, and GSTN's IRP comparison lists sandbox URLs for each portal.
Sandbox testing is not a single "does it work" check. We build a test plan that covers each document type you issue, intra-state and inter-state supplies, exports, SEZ supplies, reverse charge, discounts, multiple tax rates on one invoice, invoices with and without e-way bill details, duplicate submissions, cancellation inside and after the window, and token expiry in the middle of a batch. Each case has an expected result, and the run is repeated after every change.
Production access is a separate step with its own registration, and credentials never move from test to live code by copy-paste; they live in environment settings on your server. Our API developer page explains how we structure test and live configurations for other government and payment APIs too.
Handling e-invoice API errors without blocking billing
Design for rejection from the start: every failed call should land in a visible queue with a readable reason, the invoice should stay in a clear "pending IRN" state, and a fix-and-retry path should exist for the billing team.
The GSTN FAQ notes that when validation fails, the IRP rejects the invoice with error codes describing the reason. Those messages are written for developers, so the integration translates common ones into instructions your staff can act on: "Buyer GSTIN is not active — check with the customer", "Item total does not match — check rounding on line 3". Network failures and timeouts are retried automatically with backoff; validation errors are not retried until someone fixes the data.
One case deserves special care: a timeout after the IRP actually registered the invoice. Retrying blindly produces a duplicate error. The integration handles this by checking whether an IRN already exists for that document before resubmitting and, if it does, fetching and saving it. Alerts go to WhatsApp or email when the queue grows or when an invoice approaches the 30-day reporting limit described below.
E-invoice cancellations and credit notes through the API
An IRN can be cancelled through the Cancel API within 24 hours of reporting, only in full, and not if a connected e-way bill is active or verified in transit. After that, corrections go through credit or debit notes or return amendments.
These rules come from the GSTN e-invoice FAQ, which also states that once an IRN is cancelled, that invoice number cannot be used again for another e-invoice, even inside the window, because the IRN is derived from the document number. So the integration needs to issue a fresh invoice number after a cancellation and keep the cancelled one on record with its reason code. The FAQ adds that amendments are not possible on the IRP itself; changes are made on the GST portal while filing GSTR-1, or through the amendment mechanism if GSTR-1 has already been filed.
Credit and debit notes issued under Section 34 of the CGST Act are reported as documents of their own. The FAQ says only those notes need reporting, not purely financial or commercial credit notes. Inside your software we link each note to its original invoice for your own tracking, and the UI shows staff which option is still available: cancel, or issue a note.
The 30-day reporting limit and what it means for your integration
GSTN advised that from 1 April 2025 taxpayers with an aggregate annual turnover of 10 crore rupees or more cannot report an e-invoice on the IRPs more than 30 days after the document date. The rule covers invoices, credit notes and debit notes.
For software, this turns a "we'll fix it later" backlog into a hard deadline. The integration therefore tracks each pending document's age, warns early when something has sat in the error queue for too long, and escalates to a named person well before day 30. A daily summary on WhatsApp or email lists pending documents by age so nothing is forgotten over a month-end or holiday.
If your turnover is below that threshold today, building the same safeguard costs little and keeps you ready as the business grows. Whether the limit applies to you is a compliance question for your CA; our role is to make sure the system surfaces problems while they can still be fixed.
Generating e-way bills from the same e-invoice data
If your goods need an e-way bill, the transport details can be sent along with the e-invoice or afterwards using the IRN, so dispatch paperwork comes from the same data your billing team already entered.
The e-invoice schema has an optional e-way bill section, and when it is selected certain transport fields become mandatory, as the GSTN FAQ describes. We add those fields to your dispatch screen, not the billing screen, because transporter ID and vehicle number are often known only when the truck is loaded. The integration can then request the e-way bill as a follow-up on the IRN.
Remember the dependency: while a connected e-way bill is active, the IRN cannot be cancelled. The cancel button in your software checks for that and explains the order of steps if a cancellation is needed. Businesses that move goods daily often pair this with transport management software so vehicle data is already available.
E invoice API integration for ecommerce and distribution backends
An online store or B2B ordering app should request an IRN only for orders that need an e-invoice, typically registered business buyers who entered a GSTIN, and should do it when the tax invoice is finalised rather than when the order is placed.
Store backends mix consumer orders with business orders. The integration adds a rule: if the order carries a buyer GSTIN and the business is notified for e-invoicing, generate the IRN at invoicing time; otherwise follow your normal B2C process. Checkout also validates the GSTIN format so bad data does not reach the invoice at all.
Returns in ecommerce matter too. A return processed after the 24-hour cancellation window becomes a credit note, reported through the API with its own document number. For distributors, the same logic lives inside a B2B ordering app or a distributor management system, where dealers place orders and invoices are generated centrally.
E-invoice integration with ERPs, Tally and custom software
Where your ERP or accounting package has built-in e-invoicing that fits your process, use it. Custom integration earns its keep when you run custom billing code, several systems produce invoices, or the built-in module cannot cope with your document types.
For ERPNext, Odoo or a custom ERP, we hook into the point where a sales invoice is submitted, call the IRP or GSP, and write the IRN, acknowledgement details and QR string back to the document. For custom PHP, Python, Java or .NET billing apps the pattern is the same, placed in the save or approve action. TallyPrime users usually rely on Tally's own features; where Tally sits alongside a custom order system, we make sure the invoice numbering and IRN data stay consistent between them, as described on Tally API integration.
Whichever system you run, keep one rule: exactly one system is responsible for requesting the IRN for a given invoice. Two systems both trying to register the same document is a common and avoidable source of duplicate errors.
Credentials, storage and ownership of the integration
API credentials, the signed invoices and the code all belong to you and sit in your environment. We work with access you grant, and hand over everything at the end.
E-invoice credentials are tied to your GSTIN, so they are stored in server-side configuration or a secrets manager, never in the browser or in source code. The signed JSON for each document is stored in your database with backups; the GSTN FAQ advises proper storage because signed invoices are not available for download from the IRP later. Access logs show who generated or cancelled each IRN.
At handover you receive the source code, mapping document, test plan with results, and a short runbook for common errors. You get two months of free maintenance, which matters here because schema updates and portal advisories do arrive. After that, care is available from ₹8,000/mo a month, or your in-house team can take over. General terms are on our terms page and specifics go into your quote.
How much does e invoice API integration cost and how long does it take?
Adding e invoice API integration to existing, well-structured billing software starts at ₹40,000 and takes about 2–4 weeks. Messy data, many document types or several source systems add time and cost.
The biggest variable is data quality. If your software already stores GSTINs, state codes, HSN codes and units cleanly, mapping is quick. If addresses are free text, units are typed by hand and tax is calculated only on totals, some clean-up in the billing screens is needed first. The second variable is scope: invoices alone, or credit notes, debit notes, exports, SEZ supplies and e-way bills too.
Timeline in outline: a few days to review your data and choose the access route, a week for mapping and core generate calls, a week for cancellation, notes, errors and printing, and a sandbox test cycle before production registration. Our wider ERP software development cost guide covers the case where invoicing is one module in a bigger rebuild.
E invoice API integration readiness checklist
Work through these points before development starts. Most are data and decision questions, not technical ones.
- Confirmation from your CA that e-invoicing applies and from which date.
- The document types you issue: invoices, credit notes, debit notes, exports, SEZ supplies.
- Access route decided: GSP (and which one) or direct IRP where eligible.
- Sandbox credentials requested for the chosen route.
- Clean masters: customer GSTINs, state codes, HSN or SAC codes, unit codes.
- Invoice numbering rules, including what happens after a cancellation.
- Who fixes rejected invoices, and who is alerted as the 30-day limit approaches.
- Printing templates that will carry the QR code.
- Where signed JSON will be stored and how it is backed up.
Worked example: a parts manufacturer on custom billing software
A hypothetical case to make the steps concrete. Suppose an engineering-parts manufacturer in Rajkot runs a custom PHP billing application built years ago, issues B2B invoices to dealers across Gujarat, Maharashtra and Tamil Nadu, and has been uploading JSON through the offline tool every evening.
The first week is data work: customer GSTINs are validated, state names become codes, units are mapped to the allowed list, and HSN codes are made mandatory on the item master. The team chooses a GSP connection because nobody in-house wants to manage credentials directly. Development then adds a generate call to the "approve invoice" action, stores the signed response, and prints the QR on the existing PDF template.
Cancellation is added as a button that is only visible within 24 hours and hidden if an e-way bill is active; after that the screen offers "issue credit note". A pending-IRN queue with WhatsApp alerts goes to the accounts head each morning. After sandbox tests covering intra-state and inter-state invoices, credit notes and duplicate submissions, the integration moves to production. This example is illustrative only, not a description of a real client or measured outcome.
E-invoice integrations for businesses across India
We build remotely for manufacturers, distributors and B2B sellers anywhere in India. The pattern is similar everywhere: invoices come from custom or semi-custom software, and the team wants IRNs without manual uploads.
The work suits industrial and trading regions such as Vadodara, Ankleshwar, Vapi, Pithampur, Aurangabad, Faridabad, Chennai and Morbi, along with distributors in Kolkata and Nashik. All work happens over WhatsApp, calls and screen sharing; we never need to visit your premises to connect software to an IRP.
Calls happen in English or Hindi, whichever your accounts and IT people prefer. Invoices in regional languages are fine as long as schema fields carry the required values, which your billing software controls.