E-Invoice API Developer Portal: Registration to First IRN

Why this portal is different

India has two tax API estates and they behave nothing alike. GSTN runs the core GST system APIs — registration, returns, ledgers, payments — and issues production credentials only to empanelled GST Suvidha Providers. NIC runs the Invoice Registration Portal, which mints Invoice Reference Numbers, and it lets eligible taxpayers register directly.

That difference exists because of what e-invoicing is. Generating an IRN is an operation a business performs on its own invoices, at high volume, in real time, inside its own billing system. Routing every one of those through an intermediary would have added cost and latency to an operation that is already on the critical path of issuing an invoice. So NIC opened direct access, with eligibility and IP controls instead of empanelment.

The background on why the GSTN side works the way it does is in the GST developer portal guide, and the full comparison of access routes is in GST API for developers.

Eligibility: the day-one blocker

E-invoicing applies above an aggregate turnover threshold that has stepped down repeatedly since introduction, catching progressively smaller businesses each time. If your GSTIN is not enabled for e-invoicing, API registration will not proceed, and no amount of retrying the form changes that.

Check first, before you write any code. The e-invoice portal exposes a status check for any GSTIN, and the same information comes back in a verification lookup — the e-invoicing flag is part of the public taxpayer record. Two things worth knowing about that flag:

• It is computed on aggregate turnover at PAN level, not per registration. All your state GSTINs become e-invoicing applicable together.
• Enablement can lag eligibility. Crossing the threshold does not flip the flag instantly, and a business can be legally required to issue e-invoices while the portal has not yet enabled it. There is a self-enablement path on the portal for exactly this case.

Step 1: the sandbox

Develop against the sandbox first. It is genuinely good — the schemas match production, the validation is the same, and the error codes you will fight in production are the error codes you get here.

You register as a test user with an eligible GSTIN, receive sandbox credentials and a client ID and secret, and call the sandbox host. Budget real time for schema validation rather than connectivity: the e-invoice JSON schema is large, strictly validated, and unforgiving about field presence, types and conditional requirements. The majority of sandbox failures are schema rejections, not auth problems.

Step 2: production credentials

Once your integration works in the sandbox, you create production credentials on the live e-invoice portal. The sequence:

1. Log in to the e-invoice portal with your GSTIN's portal credentials — the ones the business uses, not anything created for the sandbox.
2. Open the API registration section. This is where you declare that you intend to call the APIs directly rather than through a GSP or ERP partner.
3. Create an API user. You set a username and password specifically for API calls. These are distinct from your portal login and are what your code will send.
4. Whitelist your IP addresses. You register the public IPs your servers will call from. Requests from anywhere else are rejected regardless of credentials.
5. Record the client ID and secret issued for production and store them as secrets, not in source control.

Step 3: authentication and the token

Authentication exchanges your credentials for a short-lived token that subsequent calls carry. Two characteristics shape how you should implement it.

Tokens are short-lived but not per-request. Validity is measured in hours — six is typical — and the system expects you to cache and reuse. Authenticating before every IRN request is the most common self-inflicted throttling problem on this API. Cache the token, store its expiry, refresh a few minutes early, and make the refresh safe under concurrency so a burst of invoices does not trigger a stampede of auth calls.

Payloads are encrypted. The e-invoice APIs use application-level encryption on top of transport security, with a session key established at authentication. This is unusual if you are coming from ordinary REST APIs and is worth allocating implementation time to rather than discovering late. Use a maintained client library for your language where one exists.

Step 4: your first IRN

With a token in hand, generating an IRN is a POST of the invoice payload. What comes back is the IRN itself, a signed QR code and a signed invoice — the artefacts you must carry on the document you issue.

Three behaviours to design around from the start:

• Duplicate detection. Submitting the same document number for the same GSTIN and financial year returns the existing IRN rather than creating a second one. Treat this as success in your retry path — it is what makes safe retries possible.
• A 24-hour cancellation window. An IRN can be cancelled within 24 hours of generation and not after. Past that, you issue a credit note instead. Build both paths; you will need them. Ours is covered in debit and credit notes under GST.
• No amendment. There is no edit operation. A wrong e-invoice is cancelled and regenerated within the window, or corrected by credit note outside it.

If you are wiring this into an existing billing system rather than building fresh, the sequencing concerns — where IRN generation sits relative to invoice numbering and document issue — are covered in e-invoicing integration for billing software.

Direct registration vs going through a GSP

Direct is not always right. The deciding factor is whose invoices you are generating.

Put simply: if you are a business generating your own invoices, register directly. If you are building software that generates invoices for other businesses, a partner is almost always the better economics once you count credential management across many client GSTINs.

The gotchas that cost the most time

1. Egress IPs that move. Covered above, and worth repeating because it is the number-one cause of failed go-lives. Fix your egress before you register.
2. Re-authenticating per call. Cache the token. This is throttling you can avoid entirely with ten lines of code.
3. Treating schema errors as transport errors. A rejected payload is not a retryable failure — retrying an invalid invoice a hundred times only burns your rate limit. Separate validation failures from transient ones and route them differently.
4. Assuming counterparty GSTINs are valid. An e-invoice carrying a cancelled or malformed recipient GSTIN gets rejected by the IRP, at the worst possible moment. Verify recipient GSTINs at master-data entry rather than at invoice generation — a validated input at the point of capture prevents the failure entirely, and a periodic status re-check catches the ones that lapse afterwards.
5. Deadline-day load. The IRP is busiest at month end. Build backoff and a queue rather than retrying tightly, and do not schedule bulk regeneration for the last day of the month.

Frequently asked questions