E-way bills: generate and cancel from the Invoice

An e-way bill in xMatix is a request you raise from an Invoice for the movement of the goods on it: you enter the transport details, xMatix records the request in the E-Way Bills register, and a GSP integration submits it to the e-way bill portal and writes the number back. It sits after the Invoice is ready to ship and before the goods leave; the number and date then appear on the Invoice itself.

xMatix does not call the GSP or the portal itself. Until an integration is set up to answer, a request stays Waiting for GSP. That is expected, not an error.

Overview

You work with e-way bills in two places:

• The E-Way Bill panel on the Invoice. You open it with the E Way Bill action in the Invoice page header. It shows the current status, the e-way bill number and date, the validity, the transport details, and the Generate and Cancel E-Way Bill buttons.
• The E-Way Bills register. The E-Way Bills list in the Tax Center app holds one record for each request. It shows the system's own view of every e-way bill: the source document, its status and the raw messages exchanged with the portal.

The panel and the four Invoice actions behind it are the only supported way to create and change e-way bills. The register record has Edit and Delete in its header, but editing it by hand bypasses every check described on this page.

When to use it

• You need an e-way bill for goods on a sales Invoice before they move.
• A request was rejected and you need to correct the transport details and send it again.
• A generated e-way bill was raised in error and it is still less than 24 hours old.
• You need to see which e-way bills were raised for a company or GST registration (the register).

Only the Invoice raises e-way bills. Delivery orders show an E Way Bill action too, but it is not connected to anything and pressing it does nothing. The E-Way Bill Number and E-Way Bill Date fields on a delivery order are for typing in a number obtained elsewhere.

How xMatix handles it

Every request moves through these statuses. The panel shows the label in the first column; the register's Status field holds the value in brackets.

One Invoice never has two open requests:

• Generate while a request is Waiting for GSP or Failed updates that same record and sends it back to Draft.
• Generate while a valid Generated bill exists is refused until you cancel it or it expires.
• Generate while a cancellation is pending is refused.
• Generate after Cancelled or Expired creates a new record. If the old bill was still marked Generated but past its validity, it is marked Expired at that moment.

xMatix fills the request from the Invoice: the document number is the Invoice number, the document date is the Invoice's Document Date, the value is the sum of each invoice line's amount plus its tax, and the GST registration is the Invoice branch's registration (or the company's default registration when there is no branch).

Prerequisites

• The Invoice is saved. The panel says Save the document before working with its e-way bill on an unsaved one.
• Your security profile allows the E Way Bill action on Invoice (and Cancel E-Way Bill to cancel). See Permissions.
• A GSP integration is set up to answer requests. Without it, requests stay Waiting for GSP. See Configuration.
• You know the real route distance, the transport mode and, for road transport, the vehicle number.

Procedure

Step 1 — Check the Invoice

Open the Invoice and confirm the company and branch, the customer, the Invoice number and Document Date, and the lines with their tax. These are copied into the request; you cannot change them in the panel.

Step 2 — Open the E-Way Bill panel

Choose E Way Bill in the Invoice page header. The panel opens with the current status. For a new Invoice it says Generate an e-way bill for this document.

Step 3 — Enter the transport details and generate

Choose Generate. The Generate E-Way Bill dialog asks for:

Choose Generate in the dialog. The panel shows Sending the request… and then Waiting for the GSP to generate the e-way bill… for up to a minute. Status is now Waiting for GSP (Draft).

If your administrator attached a custom form, the dialog shows that form instead; its rules are the same.

Step 4 — Read the answer

• Generated: the panel says E-way bill … generated. and shows the E-way bill number, E-way bill date and Valid until. The Invoice's E-Way Bill Number and E-Way Bill Date now hold the same values.
• Failed: the panel shows The GSP rejected the request with the portal's reason. Go to Step 5.
• No answer within a minute: the panel shows The GSP has not answered yet — Your request is saved. Please come back and check again in a little while. Reopen the panel later; it reads the latest status each time.

When a generated bill has less than 24 hours of validity left, the panel shows E-way bill expires soon with the time it is valid until.

Step 5 — Correct a rejected or pending request

Choose Generate again. The dialog is pre-filled with the last request's values, so change only what was wrong and choose Generate. The same register record is updated and goes back to Waiting for GSP.

You can do the same while a request is still Waiting for GSP, for example to fix a vehicle number before the integration picks it up.

Step 6 — Cancel within 24 hours

While a bill is Generated, the panel shows how long is left: Can be cancelled for another 5h 20m. Choose Cancel E-Way Bill, pick a Reason (Duplicate, Order Cancelled, Data Entry Mistake or Others), add Remarks (required for Others) and choose Request cancellation.

The status becomes Cancellation pending until the integration answers:

• Accepted: status Cancelled; the Invoice's E-Way Bill Number and Date are cleared, and you can generate a new one.
• Refused: the bill stays Generated and the panel shows Cancellation was not accepted with the reason.

After 24 hours the panel says The 24-hour cancellation window has closed. and the button is disabled. Cancel on the portal instead.

Step 7 — Review the register

Open the Tax Center app and choose E-Way Bills. The All EWay Bill list shows Name, Source Entity Name, Document Number, Document Date, Status, Created By, Created Date and Modified Date. Open a record to see its e-way bill details, the payloads and the raw GSP response, and the source and ownership fields.

The register's Status is the stored value. A bill past its validity still shows Generated here until someone generates a new e-way bill for the same Invoice; the panel on the Invoice already shows it as Expired.

Step 8 — Use the mobile app

Where the Invoice is available in the field app and the E-Way Bill panel is on its layout, the panel works the same way, with the same rules. Generating and cancelling need a connection: offline, the app says E-way bills are not available offline.

Fields

The register record

The record page has a header (Partner Account and Branch) and three sections. Status, Valid Upto, Total Value and the transport fields other than distance are not on the shipped record page; the Invoice panel and the list show them.

On the Invoice

Business rules

• Distance must be a whole number from 1 to 4000 km: Distance must be between 1 and 4000 km.
• Transport mode must be Road, Rail, Air or Ship: Transport mode must be one of Road, Rail, Air, Ship.
• Vehicle number is required for Road: Vehicle number is required when the transport mode is Road. When given, it must be 6–15 letters and digits after spaces and hyphens are removed.
• Transporter ID, when given, must be a 15-character GSTIN: Transporter ID must be a 15-character GSTIN.
• These checks run on the server for every request, whatever a custom Generate form marks as required.
• One open request per Invoice — see How xMatix handles it.
• Numbering: each new register record is named from the E-Way Bill numbering setting (series EW, date DDMMYYYY, six-digit counter).
• Validity: Valid Upto is the portal's value when supplied, otherwise one day per 200 km or part of 200 km from the generation date, minimum one day.
• Cancellation: only a Generated bill, only within 24 hours of its Generated Date, with a reason; Others needs remarks.
• Invoice fields: the Invoice's E-Way Bill Number and Date are set when the bill is generated and cleared when that same bill is cancelled.
• Expiry: no background job changes a bill's status when it expires. The panel works it out from Valid Upto, and the stored status changes to Expired only when a new e-way bill is generated for the Invoice.
• Retries are safe: recording the same e-way bill number twice changes nothing; recording a cancellation that is already done changes nothing.

Example

An invoice clerk ships 40 cartons of floor tiles worth ₹1,12,000 plus ₹20,160 GST on Invoice INV-27102026-000143 to a customer 430 km away by road.

1. They open the Invoice, check the lines and tax, and choose E Way Bill.
2. They choose Generate and enter Distance 430, Transport Mode Road, Vehicle Number ka 01 mn-4521, leaving the transporter fields empty because the goods go on the company's own truck.
3. The vehicle number is saved as KA01MN4521 and the request is staged as Waiting for GSP with a value of ₹1,32,160.00. A register record EW-27102026-000009 is created.
4. Two minutes later the integration records number 3410 2234 5678. The panel shows Generated, Valid until three days after the generation date (430 km is three 200 km blocks), and the Invoice shows the number.
5. An hour later the clerk notices the customer cancelled the order. They choose Cancel E-Way Bill, pick Order Cancelled and choose Request cancellation. The status is Cancellation pending and, once the integration confirms, Cancelled; the Invoice's E-Way Bill Number is cleared.

Training

Practice exercise

In a sandbox with no GSP integration:

1. Open a saved test Invoice and choose E Way Bill.
2. Choose Generate, enter Distance 0 and Transport Mode Road with no vehicle number, and choose Generate. Expected: the dialog refuses both fields.
3. Enter Distance 150 and Vehicle Number mh-12 ab 1234, and choose Generate. Expected: after about a minute the panel says The GSP has not answered yet; status Waiting for GSP.
4. Choose Generate again. Expected: the dialog is pre-filled with 150, Road and MH12AB1234.
5. Open Tax Center → E-Way Bills. Expected: one record for the Invoice, Status Draft, named EW-today's date-NNNNNN.

Quick reference

• Start from the Invoice: E Way Bill → Generate.
• Distance 1–4000 km; vehicle number required for Road.
• Waiting for GSP is normal until the integration answers.
• Failed or still waiting? Generate again; the same record is updated.
• Cancel only within 24 hours of generation, with a reason.
• The number and date on the Invoice always show the live bill.
• The register's Status can say Generated for an expired bill; trust the panel.
• Delivery orders cannot raise e-way bills.

Permissions

A user without the E Way Bill action cannot open the panel. A user who can run the action but cannot read E-Way Bill records still gets a panel built from the Invoice's own number and date: status, number and date show, but validity and transport details are empty, and Cancel E-Way Bill stays disabled because the panel cannot read the bill's generation time. Before any bill exists, such a user sees Could not load the e-way bill register.

Configuration

Integration. A GSP integration must read the requests and answer them through the Invoice actions below. Set it up under Integrations, running as a profile that holds Record E-Way Bill and Record E-Way Bill Cancellation.

Numbering. The register's names come from the document numbering setting E-Way Bill Settings (series EW, concatenation character -, date DDMMYYYY, six digits). Change it under Document numbering.

The panel on the Invoice. The E Way Bill action opens the Invoice layout E-Way Bill, which hosts the E-Way Bill widget. If that layout was customised before the widget shipped, it was left alone and may show other content. Open Studio → Layouts, choose Invoice and the E-Way Bill layout, and drag E-Way Bill onto it from the components. You can also place the widget on the Invoice record layout.

Widget properties (select the widget in the designer):

A custom Generate form. Set Generate Form Layout to an E-Way Bill Create layout and the Generate dialog shows that form instead of the built-in one, so you can add, remove, reorder or require fields without a code change. Build a dedicated layout with only the request fields: Distance Km, Transport Mode, Vehicle Number, Transporter, Transporter Name, Document Type, Sub Supply Type and Challan Type. The last three override the defaults (Tax Invoice, Supply, none). Do not use the shipped EWayBill Create layout, which is the full record form. Any other field on the form, including custom fields, is not applied, and the panel names it in Some fields were not applied. On mobile the attached layout is used only when it has a mobile design; otherwise the built-in form appears.

Integration contract

The integration uses these Invoice server actions (POST /{version}/data/Invoice/{id}/{action} with { "args": { … } }):

eWayBillId defaults to the Invoice's latest e-way bill. Pass dates as UTC ISO-8601: the 24-hour cancellation window is measured against the server's UTC clock.

What the integration does:

1. Find register records with Status Draft. The Part A payload holds the consignment JSON; the transport details are on the record.
2. Submit them to the portal, then call RecordEWayBill on the source Invoice (Source Record) with the number, or with error.
3. Find records with Status CancelRequested. Gsp Response holds {"cancelRequest": {"ewbNo", "cancelRsnCode", "cancelRmrk", "requestedAt"}}, the portal's cancel payload.
4. Submit the cancellation, then call RecordEWayBillCancel.

Gsp Response holds the raw portal response after a successful generation, {"error": "…", "response": …} after a failure or a refused cancellation, the pending cancel request while a cancellation waits, and {"cancelledDate": …, "response": …} once cancelled.

Common problems

The panel stays on "Waiting for GSP"

No integration has answered the request. Check the integration's run. Generate stays available while waiting, so you can correct details; the same record is updated each time.

"E-way bill … is already generated for this document. Cancel it before generating a new one."

A valid bill exists for the Invoice. Cancel it within 24 hours, or wait until it expires, before generating another.

"Cancellation of e-way bill … is still pending."

You asked to cancel and the integration has not answered. Wait for the answer before generating again.

"An e-way bill can only be cancelled within 24 hours of generation."

The portal's rule. Cancel it on the portal.

"Only a generated e-way bill can be cancelled."

The latest request for the Invoice is not in Generated status, for example it is still waiting, failed or already cancelled.

Failed, with a reason

The portal rejected the request. Correct the Invoice or the transport details and choose Generate again.

"Some fields were not applied"

The custom Generate form has fields the request cannot carry. Remove them from that layout.

The E Way Bill dialog shows IRN or QR fields instead of e-way bill details

The Invoice's E-Way Bill layout was customised before the widget shipped. Place the E-Way Bill widget on it, as described in Configuration.

The panel shows a number but no validity or transport details

Your profile cannot read E-Way Bill records, so the panel falls back to the Invoice's own number and date and cannot offer cancellation. Ask your administrator for read access.

The register says Generated but the bill has expired

The stored status changes only when a new e-way bill is generated for the Invoice. The panel on the Invoice shows Expired as soon as Valid Upto has passed.

Pressing E Way Bill on a delivery order does nothing

Delivery orders cannot raise e-way bills. Raise it from the Invoice, or type a number obtained elsewhere into the delivery order's E-Way Bill Number and Date.

Common questions

Does xMatix connect to the e-way bill portal?

No. xMatix records the request, validates the transport details and keeps the register, but a GSP integration does the submission and writes the answer back. Until one is configured, requests wait. This keeps the number on the Invoice tied to what the portal actually issued: the number appears only when the integration records it, and it is cleared only when the portal accepts the cancellation.

Can I raise an e-way bill without an Invoice?

No. The Invoice is the only document with a working e-way bill action. Delivery orders have fields for an e-way bill number and date that you can fill in by hand, and an E Way Bill action that is not connected, but nothing in xMatix generates an e-way bill for a delivery order or a transfer. Raise the e-way bill from the Invoice that covers the goods.

How is the validity worked out?

If the integration passes the portal's validity, xMatix uses it. Otherwise it counts one day for every 200 km of the distance you entered, or part of 200 km, with a minimum of one day, from the generation date. A 430 km trip therefore gets three days. Always check the validity the portal returns, because special cargo and other cases follow different rules.

Why does the value differ from the Invoice total?

The e-way bill value is the sum of each invoice line's amount plus that line's tax, rounded to two decimals. Charges held at document level rather than on lines are not added, so an Invoice with freight or other document charges shows a higher total than its e-way bill.

Related topics

• E-invoicing
• GST registrations
• Invoicing and payments
• Delivery orders
• Document numbering
• Connect a system
• E-Way Bill entity reference
• Bill — entity reference
• Invoice — entity reference