Manufacturing & custom software · Bengaluru · Whitefish, USA
Guides

GST E-Invoicing and E-Way Bills in Custom Software: A Design Guide for Indian Businesses

How to build GST e-invoicing and e-way bills into a custom business application — data validation, IRN and QR flow, rounding, tax rate changes, failures and cancellations, vehicle changes and a test plan for go-live.

By Corposol Team··10 min read
Truck carrying steel bars along a highway in India
Photo: Freight transportation by road on open truck by Sneha G Gupta, CC BY-SA 4.0 (cropped)

Most articles about GST e-invoicing explain the law. This one is for the people responsible for the system that has to obey it: owners, finance heads and developers of a custom ERP, billing or transport application. Passing a successful test invoice to a portal is the easy part. The harder part begins on a busy Tuesday when the portal is slow, a customer's GSTIN is wrong, a truck breaks down mid-journey, and the accountant wants to know why the return doesn't match the books.

This guide concentrates on design decisions: what your data must look like, how the workflow should handle failure and what to test before going live. It isn't tax advice. Rules, thresholds and portal behaviour change, so have your tax adviser confirm the requirements and check the latest official documentation.

The moving parts in one view

ItemWhat it isWhat your software must do
E-invoiceA B2B invoice, export or similar document reported to an Invoice Registration Portal (IRP) in a standard format. Generally applies above ₹5 crore aggregate annual turnover in any year since 2017–18.Produce valid data, register it, and store the response
IRNThe unique Invoice Reference Number given by the IRPSave it permanently against the invoice
Signed QR codeA code holding key invoice details, returned by the IRPPrint it on the invoice PDF
E-way billA document for moving goods, generally where consignment value exceeds ₹50,000, subject to rules and state variationsCapture transport details, generate it, and track its validity

The important design point is that these are external events attached to your invoice, each with its own status, not printed fields. Your invoice might be approved internally but not yet registered, or registered without an e-way bill, or cancelled at the portal after you have already started dispatch. The system must show that clearly.

Get the data right before anyone presses "Save"

Most portal rejections are caused by ordinary data problems. It is far cheaper to prevent them at data entry than to repair them at the point of dispatch, when a truck is waiting and an accounts executive is being phoned by the gate.

FieldValidateTypical trap
GSTINFormat and check digit; state code matches the billing address; status confirmed through a lookup where availableA customer's cancelled GSTIN or a mistyped digit
AddressesSeparate fields for bill-to, ship-to and dispatch-from, with PIN code and stateA single text box that can't be parsed correctly
Place of supplyDetermined by clear rules, and overridable only with permissionWrong choice between CGST+SGST and IGST
HSN or SACHeld on the item master, at the number of digits your turnover requiresItem codes that nobody has cleaned up since the GST launch
Quantity unitMapped to the allowed Unit Quantity CodesLocal units such as "box" or "bundle" with no mapping
Invoice numberUnique within the financial year, within the length and character limitsA series that resets or duplicates across branches

The best way to do this is to validate masters as they're created. Mark a customer as "ready to invoice" only when the essential fields pass. For existing data, run a report listing every customer and item that would fail, then fix those records before go-live. For multi-state businesses, each GSTIN needs its own series and credentials, which is one reason multi-branch design should be decided early.

Worked example: the one-paisa rounding problem

Rounding produces surprisingly stubborn errors. Consider an invoice with three lines of ₹33.35 each, taxed at 18% between two states:

MethodCalculationIGST
Round tax on each line, then add33.35 × 18% = 6.003, rounded to 6.00; 3 × 6.0018.00
Add lines, then calculate tax100.05 × 18% = 18.009, rounded to 18.0118.01

Neither is obviously foolish, yet they differ by a paisa. If your accounting package uses one method and your invoice screen the other, your invoice, e-invoice data, ledger and return can disagree, and someone will spend hours searching for an amount smaller than the cost of finding it. The same issue can appear with discounts, and when tax is split between CGST and SGST.

The solution is to agree a single calculation method with your accountant, implement it in one shared service, and store the calculated line-level values rather than recalculating them later. Keep the portal's tolerance rules in mind, and add a test that compares invoice, portal and accounting totals to the paisa.

Treat tax rates as dated data

GST rates do change. The major rate rationalisation of September 2025 moved many items between slabs. If rates are hard-coded, or stored as a single value on the item, every change becomes an emergency. Instead, keep rates in a table with effective dates, by HSN or item group, with any exceptions. Each invoice line should save the rate it actually used. An invoice from before the change can then be reprinted or credited correctly a year later. Decide who is allowed to change a rate and require a review, since one wrong entry can affect every invoice issued that day.

A workflow that survives failure

A reliable design registers invoices through a queue, and shows a clear status at each point:

  1. Draft: freely editable, and without a final number.
  2. Finalised: locked internally, numbered and ready for registration.
  3. Registering: sent to the IRP. If the connection times out, the outcome is unknown.
  4. Registered: IRN, acknowledgement and signed QR are stored; the PDF can now be issued.
  5. Rejected: the portal's error is translated into a plain message and sent to the right person.
  6. Cancelled: cancelled at the portal, with a reason, by an authorised user.

Timeouts deserve special attention. If your request reached the portal but the response was lost, resending may produce a "duplicate" error even though registration succeeded. Your software should recognise this and fetch the existing IRN, not leave the invoice stuck or issue a new number. Log every request and response safely, since these logs are your evidence when something is disputed. Keep them restricted, because they include customer and commercial data.

Also define what happens during an outage. May goods leave while an invoice is pending? Who can authorise it? What does the printed document look like? Answer these questions with your tax adviser in advance. A warehouse supervisor shouldn't have to decide alone at 7 pm.

Connecting to the portal

There are three broad ways to report data, and the right one depends on volume and the system you have.

  • Portal or offline tools: workable for low volumes, but each manual step invites delays and transcription errors.
  • Through a GST Suvidha Provider or similar intermediary: your application calls the provider's API, and it deals with the connection to the IRP. This can reduce onboarding work and may add tools and support.
  • Direct API access: available to taxpayers who meet the eligibility conditions. It offers more control, but you take on more of the security and maintenance.

Whichever you pick, keep the connection behind a single internal service, so that the rest of your application simply calls "register this invoice". Should you later change provider, or when the portal changes its schema, the impact stays contained. See our guide to integrating business systems for general patterns. Guard credentials carefully and use individual, role-limited access where the portal allows it.

E-way bills: designed around the journey

E-way bills look like a variation of an invoice, but they're really about a moving vehicle. That has several design consequences:

  • Two sets of details. Consignment details and transport details (Part A and Part B) may not be known at the same time. Allow a record to wait for its vehicle number, and alert someone if it does.
  • Who generates it. It may be the supplier, the recipient or the transporter. Record which party is responsible for each movement, and hold transporter IDs in your vendor master.
  • Distance and validity. Validity depends on the distance, so accurate PIN codes and route distance matter. Show the expiry on the dispatch screen and alert the team before it passes.
  • Vehicle changes. Trucks break down, and goods get transferred between vehicles. The driver or dispatcher needs a quick way to raise it, and the office needs to be able to update the vehicle details in time.
  • Consolidated loads. A truck carrying many consignments may need a consolidated document. Without planning, this can become a very manual step for transporters.
  • Documents on the road. The driver should be able to produce the current document from an app, even with poor connectivity.

For transport businesses, it makes sense to tie these documents to the trip record in a truck management system, so that dispatch, vehicle, driver and validity can be seen on one screen.

Corrections and cancellations

This is where informal habits run into a formal system. A registered e-invoice cannot simply be edited, and it can be cancelled in full only within a limited window, currently 24 hours through the portal. Your application should enforce a clear rule: nobody edits a registered invoice. Instead, offer defined actions, each with the correct permission and approval:

SituationTypical action in the software
Wrong invoice, spotted immediatelyCancel at the IRP within the window; cancel internally; reverse stock if needed; issue a new number
Goods returned or price reduced laterIssue a credit note, itself reported where required, linked to the original invoice
Additional amount dueIssue a debit note, linked to the original invoice
Vehicle details changed during movementUpdate the e-way bill's transport details; do not touch the invoice
Dispatch cancelled after an e-way bill was generatedCancel the e-way bill within its allowed window

Be sure that your internal cancellation and the portal stay in step. A frequent problem is an invoice cancelled in the portal but still live in the books, or the reverse. A daily report that compares the two will find this while it's still easy to fix.

Reconciliation: the report accountants will thank you for

Build a recurring comparison of four sources: your invoice register, IRP registrations, e-way bills and the outward data going into your GST return. Flag invoices missing an IRN, registered invoices absent from the books, amounts that don't match and e-way bills with no related invoice. Some taxpayers also face limits on how late older invoices can be reported, which makes a daily look at the pending queue a sensible habit rather than a month-end surprise.

Go-live test plan

TestExpected resultPass?
Same-state B2B invoice, with a discountCGST and SGST correct; IRN and QR on the PDF
Inter-state invoice with a different ship-to addressIGST correct; addresses reported correctly
Rounding scenario aboveSame total on the screen, portal, PDF and in accounts
Invalid GSTIN or unmapped unitBlocked with a clear message before submission
Connection timeout after submissionNo duplicate; existing IRN retrieved
Portal unavailable for an hourInvoices queued, then processed automatically
Cancellation inside and outside the windowInside: both cancelled. Outside: clear guidance
Credit note against a registered invoiceLinked correctly, and reported where required
Vehicle change mid-journeyUpdate succeeds; history retained
Invoice dated across a tax rate changeThe correct dated rate is applied and saved

Run these in the sandbox, followed by a small, supervised batch of real invoices with your accountant checking the results. Then set up a named owner for failed items and subscribe someone to official advisories, because schema and rule changes are a normal part of this work. Handled this way, compliance turns from a daily scramble into a dependable background process, and the same clean data improves your sales, stock and customer reporting too.

Frequently asked questions

Who must generate GST e-invoices?

E-invoicing currently applies to businesses whose aggregate annual turnover has exceeded ₹5 crore in any financial year from 2017–18 onward, for covered supplies, with exemptions for some categories. Confirm your own position with your tax adviser, because thresholds and exemptions can change.

Can our own software generate e-invoices directly?

A system can connect to the invoice registration portal through its API or through a GST Suvidha Provider, subject to eligibility and onboarding requirements. Smaller volumes may also use portal or offline tools. The best route depends on your volumes, turnover and how much control you need.

What happens if the e-invoice portal is down?

A well-designed application queues the invoice, shows that it is pending registration and retries automatically. Your business rules should state whether goods may be dispatched while it is pending, based on your tax adviser's guidance on any notified relaxations.

Can a registered e-invoice be edited?

Not directly. A registered e-invoice can be cancelled in full only within a short window, currently 24 hours on the portal, and it cannot be partly cancelled. After that, corrections are usually handled through credit or debit notes or an amendment in the return. Check the current rules.

Do e-invoices remove the need for e-way bills?

No. They are related but separate requirements. An e-way bill can often be generated using e-invoice data, and it also needs transport details such as the vehicle number. Whether one is required depends on the movement, value and goods.

  • GST e-invoicing
  • E-way bill
  • IRN
  • Custom software development
  • Indian businesses

Let's build GST-ready business software

Tell us about your process or idea. You'll get a free consultation and a clear, fixed quote — no obligation.

  • Free consultation
  • Prototype before you commit
  • Fixed, itemised quote
  • You own the software

Get a free quote

We reply within one working day. Your details are never shared.