E-invoicing: generate an IRN for a posted invoice

E-invoicing in xMatix registers a posted sales Invoice with the government Invoice Registration Portal (IRP) so that it carries an Invoice Reference Number (IRN), an acknowledgement and a signed QR code. You start it from the invoice with E Invoice Generator; a GST integration your administrator connects does the exchange with the portal and writes the result back onto the same invoice.

Everything about an invoice's e-invoice lives on the invoice itself, in the fields marked (eInvoice). There is also a separate E Invoice register entity; the shipped e-invoicing does not fill it (see The E Invoice register).

Overview

E-invoicing has two halves:

• Inside xMatix — the invoice, its e-invoice fields, the e-invoice panel that starts a request and shows the result, and the E Invoice Generator server action that builds the portal request (the IRP version 1.1 JSON) from the invoice and its lines.
• Outside xMatix — the call to the portal through your GST Suvidha Provider (GSP). xMatix does not call the portal itself. An integration flow your administrator configures picks up the request, submits it and writes the answer back.

Until that integration answers, a request waits. That is expected, not a fault.

When to use it

Use it for every posted B2B sales invoice your organisation must report through e-invoicing. Run it once per invoice, after the invoice is final: an IRN cannot be generated twice for the same invoice.

The e-way bill for the same invoice is a separate step — see E-way bills. Purchase documents, credit notes and debit notes have no e-invoice action.

How xMatix handles it

There are two ways a request starts, and they leave the invoice in different states:

Either way, your integration reacts to the status, submits to the portal and writes back. On success it fills Invoice Reference Number (eInvoice), Ack No (eInvoice), Ack Date (eInvoice), QR Code (eInvoice), Signed Invoice (eInvoice) and Response (eInvoice), and sets the status to Generated. On a rejection it writes the portal's reason into Response (eInvoice) and leaves the IRN blank.

The web panel watches the invoice while it waits:

• When the IRN, Ack No and Ack Date are all filled, it shows "E-invoice generated.", the QR code and the IRN details, and Generate is disabled from then on.
• When Response (eInvoice) gets new text and there is no IRN, it shows E-invoice not generated with the portal's reason followed by "Check the invoice details and the GSTIN's e-invoice API login, then generate again." It also sets the status back to Pending (the shipped panel setting), and Generate is available again.
• When a minute passes with no answer, it shows E-invoice generation in progress — "Your e-invoice is being generated. Please come back and check again in a little while." Generate stays disabled while the status still holds the trigger value and nothing has come back.

Prerequisites

• The invoice is Posted. On the shipped invoice pages, E Invoice Generator is shown only when Status is Posted.
• The invoice's branch (or, for a single-location company, the company's default) has a GST registration — its GSTIN becomes the seller GSTIN.
• GSTIN (the buyer's), Place of Supply and Source of Supply are filled on the invoice.
• Every line has an HSN/SAC Code. Lines for an item take it from the item; a description-only line (freight, labour) must have it typed on the line.
• Your administrator has connected the GST integration that answers e-invoice requests, and your security profile includes the actions in Permissions.

Procedure

Step 1 — Check the invoice

Open the invoice from Sales → Invoices or Finance → Invoices and confirm Status is Posted. Check the buyer GSTIN, Place of Supply, the lines' HSN/SAC Code, quantities, prices and taxes, and Reverse Charge (eInvoice) if the supply attracts reverse charge. After an IRN is generated these values must not change, so fix anything now — see Sales invoices.

Step 2 — Open the e-invoice panel

In the page header, choose E Invoice Generator. A dialog opens with a Generate button, a status line ("Select the action you want to perform.") and an empty table for the IRN, Ack No and Ack Date. If the invoice already has an IRN, the dialog opens straight on the QR code and details, with Generate disabled.

Step 3 — Generate

Choose Generate. The screen is locked with "Generating e-invoice… please don't close this window." while xMatix records the request and waits for the integration.

• Success — the status line reads "E-invoice generated."; the signed QR code appears with the IRN, Ack No and Ack Date beneath it.
• Rejected — an E-invoice not generated notice gives the portal's reason. Correct the cause (usually invoice data or the GSTIN's e-invoice API login held by the integration) and choose Generate again.
• Still waiting after a minute — close the dialog and come back later. Reopening it shows the current state.

Step 4 — Check the result on the invoice

Close the dialog. On the invoice's Details, Status (eInvoice) reads Generated, and Invoice Reference Number (eInvoice) and QR Code (eInvoice) are filled. The built-in invoice document prints the IRN and acknowledgement number when an IRN exists; check that your print format shows the QR code before you send the invoice — see Document reports.

Step 5 — Generate from the mobile app

Where your mobile invoice screen includes the e-invoice panel, open the posted invoice and tap Generate. This runs E Invoice Generator: it builds the request, sets Status (eInvoice) to Pending and shows "e-Invoice generation staged." The IRN and QR appear once the integration has answered and the invoice refreshes. The panel needs a connection — offline it says "e-Invoice generation is not available offline." — and a saved invoice ("Save the invoice before generating an e-Invoice.").

Step 6 — Correct or cancel after registration

xMatix does not cancel an IRN with the portal. Cancel Invoice cancels the invoice in xMatix but leaves its e-invoice fields as they are, and the EINV Cancellation fields are not filled by anything. Cancel the IRN through your GSP or the portal within the portal's cancellation window, or correct the sale with a credit note (Create Credit Note) and a new invoice.

Fields

The e-invoice fields on the Invoice. The shipped invoice page shows Status (eInvoice), Invoice Reference Number (eInvoice), QR Code (eInvoice) and Reverse Charge (eInvoice); the others can be added to the layout by your administrator.

Business rules

• One IRN per invoice. E Invoice Generator refuses with "This invoice already has an IRN; an e-invoice cannot be regenerated." The web panel disables Generate once the IRN, Ack No and Ack Date are all filled.
• The web button needs a posted invoice; the action does not check. The shipped pages hide E Invoice Generator until Status is Posted, but the server action itself does not check the invoice status. Keep it off other layouts and screens unless you add the same condition.
• HSN/SAC is required on description-only lines. Building the request fails with "E-invoice payload cannot be built." and, for each line without an item and without a code, "HSN/SAC code is required for e-invoicing on line '<line>'."
• What the built-in request contains (when E Invoice Generator runs):
  • Document type is always INV (invoice). Number and date are the invoice's Name and Document Date.
  • Supply type is EXPWP when Tax Supply Type contains "Export", SEZWP when it contains "SEZ", and B2B otherwise. With the shipped Tax Supply Type values (Within State, Outside State, Exempt) it is always B2B.
  • Seller GSTIN comes from the GST registration, buyer GSTIN from the invoice's GSTIN. State codes come from Source of Supply and Place of Supply.
  • Seller and buyer legal name, address and PIN, and each line's unit, are left blank. Your integration must add them if your GSP requires them.
  • Each line is sent as goods or a service according to its Is Service flag (blank counts as goods).
  • Discount Item lines are never sent as items. A discount that reduces taxable value is sent as each item's own discount; an after-tax discount and document-level discounts are sent as the invoice discount. Document-level charges (freight, packing) are sent as other charges. The total invoice value includes both.
  • Amounts are rounded to two decimals.
• No edit lock. Registering an IRN does not lock the invoice. Control changes to registered invoices through permissions and your correction process.
• Clone starts clean. A cloned invoice drops the IRN, Ack No, Ack Date, Status, Payload, Response, Signed Invoice, QR Code, Remarks and cancellation fields, and keeps the inputs (Supply Type Code, Port Code and similar).
• GSTR-1. The portal reports every IRN in B2B automatically. GSTR-1's Move to B2C refuses an invoice for which a Generated E Invoice register record with an IRN exists — see GSTR-1.

The E Invoice register

E Invoice is a separate entity designed as a register of portal submissions: source invoice, seller and buyer GSTIN, request, IRN, acknowledgement, signed invoice and QR code. The shipped e-invoicing never creates or updates E Invoice records — the results are on the invoice. The register is in no app; find it under All Entities in the App Launcher. Its list view All E Invoices shows Name, Buyer Name, IRN, GST Registration Id, Branch Id and Partner Account Id.

Records appear only if someone creates them with New (the create form asks for Name, Buyer Name, Partner Account Id and Branch Id) or your integration writes them. The one place xMatix reads them is GSTR-1's Move to B2C check. So if you want that check to protect your e-invoiced invoices, have your integration also write an E Invoice record with Invoice Id, IRN and Status Generated for each IRN. Its Status and GST Invoice Type have no values to pick on the form, so only an integration can set them.

Example

A distributor posts invoice INV-0457 for ₹1,18,000 (₹1,00,000 taxable plus 18% IGST) to a buyer in another state. The accountant opens the invoice, sees Status Posted and Place of Supply filled, and notices a freight line without an HSN/SAC code; they add 996511 to it.

They choose E Invoice Generator, then Generate. Status (eInvoice) becomes Ready For IRN. The company's GST integration picks it up, submits it through the GSP and writes back an IRN, Ack No 1124 1000 5678 and the signed QR. Six seconds later the dialog shows "E-invoice generated." with the QR code. The accountant closes it; Status (eInvoice) reads Generated, and the printed invoice shows the IRN.

Training

Practice exercise

In a sandbox with a GST integration connected (or a test flow that writes back sample values):

1. Post a sales invoice with one item line and one description-only line without an HSN/SAC code.
2. Run E Invoice Generator through the mobile panel or ask your administrator to run it directly. Expected: it is refused with "HSN/SAC code is required for e-invoicing on line '…'."
3. Add the code, open E Invoice Generator on the web and choose Generate. Expected: Status (eInvoice) becomes Ready For IRN; when the flow answers, the dialog shows the QR, IRN, Ack No and Ack Date.
4. Reopen the dialog. Expected: Generate is disabled.

Quick reference

• Only a Posted invoice shows E Invoice Generator.
• Web Generate → Ready For IRN; the direct action (mobile, API) → Pending and a built request.
• xMatix never calls the portal; the integration answers.
• Success = IRN, Ack No and Ack Date all filled.
• A failure's reason is in Response (eInvoice).
• One IRN per invoice; cancel the IRN on the portal, not in xMatix.
• Every description-only line needs an HSN/SAC Code.
• The E Invoice register stays empty unless your integration fills it.

Permissions

A user whose only profile is Sales Executive or Sales Manager can open the panel, but Generate fails with an access-denied message for the server action SetEInvoiceStatus. Add Set E-Invoice Status to the profile, or give the user a profile that has it — see Security profiles.

Set E-Invoice Status writes whichever invoice field it is told to, bypassing the protection on system fields. Grant it only to people who generate e-invoices.

Configuration

• The GST integration. Configure a flow on your GSP's connector in the Integration Hub that reacts when an invoice's Status (eInvoice) becomes Ready For IRN (web) or Pending (mobile/API). It submits the request, then writes the IRN, Ack No, Ack Date, QR Code, Signed Invoice and Response back to the same invoice and sets the status to Generated. On failure, it writes the reason to Response (eInvoice) and leaves the IRN blank. A flow triggered by Ready For IRN finds Payload (eInvoice) empty, so it must build the request itself or run E Invoice Generator first. Test it against your GSP's sandbox before going live. See Connect a system and Outbound integrations.
• The e-invoice panel. E Invoice Generator opens the Invoice dialog layout named EInvoice, which holds the e-invoice panel. In the layout designer you can change its settings: the action it runs on Generate (Set E-Invoice Status), the field and trigger value (Status (eInvoice) = Ready For IRN), the success and error values (shipped: none on success, Pending on error), the field holding the error text (Response (eInvoice)), the IRN, Ack No, Ack Date and QR fields, the wait time (60,000 ms), the check interval (3,000 ms) and the QR size (180 px). If you change the trigger value, change your integration's trigger to match.
• Where the button appears. E Invoice Generator is in the page header of the InvoiceView and InvoiceViewFinance layouts, with a condition that shows it only when Status is Posted. Keep that condition if you move the button.
• Print format. Add Invoice Reference Number (eInvoice), Ack No (eInvoice), Ack Date (eInvoice) and QR Code (eInvoice) to your invoice print format — see Document reports.
• GST registration. The seller GSTIN comes from the branch's GST registration or the company default — see GST registrations.
• Mobile. Add the e-invoice panel to the mobile invoice layout to offer Generate in the field app. It always runs E Invoice Generator and needs a connection.

Common problems

Generate keeps saying "E-invoice generation in progress"

The status holds the trigger value (Ready For IRN) and nothing has come back. Check that the integration flow is enabled, triggered by that status, and that its last runs succeeded — see Sync health. Once the flow writes a result, the panel updates the next time it is opened.

"E-invoice not generated" with a portal reason

The integration wrote the portal's rejection to Response (eInvoice). Fix what it names — usually a GSTIN, place of supply, HSN/SAC code or value, or the e-invoice API login for your GSTIN — and choose Generate again.

"The IRP did not return a reason."

The integration reported a failure without text. Check the flow's run history for the GSP's answer.

The portal rejects missing names, addresses, PIN or unit

The built-in request leaves seller and buyer legal name, address and PIN and the line unit blank. Your integration must add them before submitting.

"HSN/SAC code is required for e-invoicing on line '…'"

A line without an item has no HSN/SAC code. Open the line, enter HSN/SAC Code, save and generate again.

"This invoice already has an IRN; an e-invoice cannot be regenerated."

The invoice is already registered. To correct it, cancel the IRN on the portal or issue a credit note and a new invoice.

Generate fails with an access-denied message

Your profile has E Invoice Generator but not Set E-Invoice Status. Ask your administrator to add it (see Permissions).

I can't find E Invoice Generator on the invoice

The invoice is not Posted, or your profile lacks the action. Post the invoice first.

The E Invoice list is empty

That is expected: the shipped e-invoicing records everything on the invoice. Use the invoice's e-invoice fields, or filter the invoice list on Status (eInvoice).

Common questions

Does xMatix connect to the e-invoice portal itself?

No. xMatix builds the request and records the result, but the call to the portal goes through a GST integration your administrator configures on a GSP connector. Without that integration, a request stays at Ready For IRN or Pending indefinitely and no IRN appears. This keeps your portal credentials and GSP choice in your integration, not in the invoice screens.

Can I edit an invoice after its IRN is generated?

xMatix does not lock it automatically. Registering an IRN only blocks a second e-invoice request. Edits that change values would make the invoice disagree with what the portal registered, so restrict editing of posted invoices through permissions and correct mistakes with a credit note and a new invoice, cancelling the IRN on the portal where the rules allow.

Why does the web panel show Ready For IRN but the mobile app Pending?

They start the request differently. The web panel only sets the trigger status for your integration. The mobile panel runs E Invoice Generator, which also builds the request into Payload (eInvoice) and sets Pending. Your integration should react to both values.

Are credit notes e-invoiced?

Not from xMatix. The e-invoice action exists on sales invoices only, and the built-in request always uses document type INV. Report credit notes through your GSP's own process.

Related topics

• Sales invoices
• E-way bills
• GSTR-1 — outward supplies
• GST registrations
• Tax Center troubleshooting
• Connect a system
• E Invoice — entity reference
• Invoice — entity reference