GST e-invoicing in production: what Indian SaaS teams hit after GSTIN lookup

The moment a B2B SaaS company in India crosses the applicable Annual Aggregate Turnover threshold for e-invoicing, the GSTIN validation API suddenly looks like the easy part. Most teams have been calling the GSTIN verification endpoint for months. It is two lines of code and a JSON response. The IRP integration is a different category of problem: generating an IRN, embedding a signed QR code, and handling the 30-day reporting window.

This is a builder's account of what the GST e-invoicing API actually requires once you go beyond GSTIN lookup, and where teams lose time they did not plan for.

The GST e-invoicing API in 2026: IRP, GSP, and ASP

The Invoice Registration Portal is not a single service. Since GSTN opened IRP access to private operators, five IRPs now operate: the original NIC-operated portal, plus IRIS IRP, Cygnet, ClearTax IRP, and EY IRP. All five validate against identical GSTN schema rules, but their uptime records and API response characteristics differ.

Above each IRP sits a two-tier middleware model. A GSP (GST Suvidha Provider) is an authorised intermediary that holds a GSTN connection licence and exposes a stable API to your application. An ASP (Application Service Provider) sits between you and the GSP, typically adding a reconciliation interface, ERP connectors, or compliance workflow on top. Most engineering teams building custom integrations go directly to a GSP and skip the ASP layer.

Bypassing the GSP entirely requires AATO above Rs. 5 crore; below that threshold, a GSP is required. Above it, you choose: direct credentials (Client ID and Client Secret, generated per GSTIN on the IRP portal) or continue via a GSP. That choice depends on invoice volume and how much schema maintenance your team wants to absorb.

The authentication trap that breaks headless billing systems

IRP API authentication is a two-step OAuth 2.0 flow: exchange credentials for a session token, then present that token per-request. The session token expires every six hours.

For a finance team clicking through a GSP's web portal, that is manageable. For an automated billing system running invoice generation at 2 AM or at month-end, it means your service must detect 401 responses and re-authenticate before retrying. Skip that logic, and invoices queue silently while the 30-day reporting window starts counting.

The April 2026 MFA mandate is worth noting for teams using GSP-mediated portal access. Portal logins for humans accessing the compliance dashboard now require OTP via SMS or email. Direct API calls using Client ID and Client Secret bypass the MFA flow entirely — those credentials authenticate without portal interaction. If your ops team accesses the GSP's web interface for exception handling, they will see MFA prompts; your automated API calls will not.

One structural implication worth planning for: direct API credentials are scoped per GSTIN, not per platform account. If your SaaS generates invoices across multiple customer GSTINs rather than solely for your own, each customer's GSTIN gets its own credential set. Credential rotation becomes a per-customer problem at scale, not a centralised platform one.

The 30-day reporting window is harder than it looks

From 1 April 2025, businesses with AATO above Rs. 10 crore face a mandatory 30-day window to register an invoice with an IRP after the invoice date. Miss it, and the IRP rejects IRN generation outright. Not a penalty, not a warning, a hard rejection. Pending GST Council rules indicate this window will tighten to three days for most taxpayers.

The downstream impact is significant: a buyer cannot claim Input Tax Credit on an invoice that never received an IRN. If your SaaS bills enterprise customers on large contracts, a missed reporting window puts your finance team in a difficult conversation with a customer's finance team — even when your system generated the invoice correctly on the date of supply.

The fix requires explicit state tracking rather than implicit retry logic. Maintain an invoice status field with defined transitions (draft, irp_submitted, irn_issued, failed), and alert at day 25 for any invoice not yet in irn_issued. Design the retry path deliberately. Do not rely on background job frameworks to surface IRP failures transparently.

What actually causes IRN generation to fail

The IRN is a 64-character SHA-256 hash of four pipe-separated fields: supplier GSTIN, financial year, document type (INV, CRN, or DBN), and invoice number. The IRP computes the same hash and rejects any duplicate. Invoice number uniqueness per GSTIN per document type per financial year is a hard requirement.

# IRN = SHA-256 of: supplierGSTIN | FY | docType | invoiceNo
echo -n "09AAACR5055K1Z0|2025-26|INV|INV-001" | sha256sum
# → 3a1b9c2e4f... (64 hex chars)

# Five fields that cause the most rejections:
#  1. Inactive or cancelled buyer GSTIN
#  2. Invoice number collision (duplicate hash)
#  3. CGST/IGST mismatch vs place of supply
#  4. Missing HSN code (mandatory for AATO > Rs. 5cr)
#  5. Schema version mismatch (GSTN updates ~quarterly)

Walking through each failure category:

• Inactive or cancelled buyer GSTIN. Buyer status must be verified against the GST common portal before submission. GSTN caches status; direct integrations that do not sync may submit against a GSTIN that was cancelled days earlier.
• Invoice number collisions. Concurrent job runs or a mid-year sequence reset can silently generate duplicate invoice numbers. The IRP rejects the second occurrence with a duplicate-hash error, which does not immediately make the root cause obvious.
• CGST/SGST versus IGST mismatch. CGST and SGST apply for intra-state transactions; IGST applies for inter-state. The schema validates tax type against the place of supply code. Billing address detection that defaults the wrong place of supply on edge-case geographies produces consistent rejections for those customers.
• Missing HSN codes. Mandatory for suppliers above Rs. 5 crore AATO. The schema returns a generic validation error that does not always identify the offending line item, which slows debugging.
• Schema version drift. GSTN updates the JSON schema roughly quarterly. Version 2.1 is current as of early 2026. Direct integrations pinned to an older schema version fail when the IRP deprecates it, typically with short notice.

The build-vs-GSP calculation

A direct IRP integration from scratch takes a typical mid-sized team two to three months: sandbox provisioning, JSON schema integration with test coverage, authentication middleware, per-rejection-type error handling, monitoring instrumentation, and initial schema version support. Then roughly four schema revisions per year to maintain.

A GSP integration (ClearTax API, IRIS ASAP, Masters India) costs approximately Rs. 50 to Rs. 500 per 100 invoices depending on volume and features. At 1,000 invoices per month, that is Rs. 500 to Rs. 5,000 per month. The GSP adds 50 to 200 milliseconds of additional latency compared to a direct IRP call at 200 to 500 milliseconds, but provides failover across multiple IRPs — resilience that a direct integration must build separately.

Above 50,000 invoices per month, a direct integration starts to make economic sense — provided the team owns schema maintenance and implements multi-IRP failover explicitly. The inflection point shifts lower if your engineering team already has strong API infrastructure and invoice volumes are growing quickly.

What to monitor once you are live

Three signals catch most production failures before they become compliance problems:

1. IRN success rate. Alert if this drops below 99 percent. A 98 percent rate on 2,000 invoices per month produces 40 manual exception cases — more than most compliance teams want to handle.
2. Token expiry before submission. Log authentication refresh events separately from invoice submission events. Combined logs make the two failure modes look identical.
3. Invoice age at IRP submission. Track median time between invoice creation and IRN issuance. If the median is three days and the reporting window is 30, you have margin. If it creeps to 20 days, one failed batch run creates a compliance exposure.

The Rs. 2 crore threshold brings in a large population of suppliers building compliance automation for the first time. The architecture decisions made now will compound: direct versus GSP, synchronous versus batch submission, per-invoice retry versus bulk resubmission. Treating the IRN as an afterthought to invoice generation, rather than as a hard dependency before the invoice is legally complete, is the single most common mistake in early integrations.