e-Way Bill Generation, Update & Cancellation Workflow

How a shipment's transport details become a government-tracked e-Way Bill, how its Part-B transport details and validity are kept current in flight, and how it is cancelled inside a hard deadline

1. Requirements

1.1 Functional requirements

• Determine, for any of six originating document types (a sales invoice, a purchase invoice, a delivery note, a goods receipt, an internal stock-movement entry, or a subcontracting receipt), whether an e-Way Bill is required at all — driven by whether the movement crosses a state boundary, the shipment’s own declared value, and, for a within-state movement, a per-state override of both whether the rule applies and what value it triggers at.
• Generate the e-Way Bill either standalone (via the dedicated e-Way Bill service) or bundled with a companion IRN generation call (via the e-Invoice service), converging on the same downstream recording step regardless of which path produced the number.
• Support generation with only carrier identity known (“Part-A only”) when vehicle details are not yet available, deferring vehicle/transporter details to a later “Part-B update” call once they are.
• Update Part-B transport details after generation — vehicle number, transporter — without needing to cancel and regenerate the e-Way Bill.
• Extend an e-Way Bill’s validity when a shipment is delayed, constrained to a window around the current expiry; when outside that window, allow the extension to be scheduled and executed automatically once the window opens.
• Enforce a strict, government-defined cancellation window: an e-Way Bill may only be cancelled up to 24 hours after its generation.
• Detect and safely recover from a duplicate-generation attempt: when generated together with an IRN, retrieve the already-issued e-Way Bill automatically; when generated standalone, surface the conflict and let the operator locate the existing e-Way Bill by date rather than silently retrying.
• Keep a locally cached copy of the government’s own e-Way Bill data, explicitly marked stale whenever a Part-B update, transporter change, or extension is applied, and re-fetch it on demand — for printing, for attaching a PDF, or before treating a cached copy as authoritative.
• Provide manual reconciliation entry points for both generation and cancellation, for outcomes that happened outside this system.
• Auto-cancel the e-Way Bill when its originating document is itself cancelled, if configured to do so and the cancellation window has not yet closed.

1.2 Non-functional requirements

• Non-idempotent submission, only partially made safe: unlike the companion IRN artifact, a standalone e-Way Bill generation that is rejected as a duplicate is not automatically resolved — the system stops short and asks a human to reconcile.
• Bounded, immovable time windows: a 24-hour cancellation window and an 8-hour-either-side extension window are enforced client-side before any external call, matching government policy rather than internal convenience.
• Divergence tolerance: because vehicle changes and validity extensions can also happen directly on the government portal (by a transporter who was handed the e-Way Bill number), the local cache must be explicitly distrustable and re-fetchable, not assumed authoritative.
• Graceful degradation under a government-side outage: a transient failure queues the document for the same automatic retry sweep used for IRN generation, rather than requiring manual intervention.

1.3 Constraints

• Applies to six specific originating document types, each with its own mapping of which address fields represent the shipment’s origin and destination.
• A single e-Way Bill submission may describe at most 250 distinct HSN/tax-rate/unit combinations; beyond that, line items sharing the same combination are consolidated into one summarized line before submission, and only if the consolidated count still exceeds 250 does generation fail outright.
• The government service is treated as an opaque external system with a request/response contract; this document does not model its internal processing.
• A sandbox/test mode exists that redirects calls to a test endpoint and substitutes fixed test registration numbers and login material; no such value is reproduced in this document.

2. High-Level Design

2.1 Component diagram

2.2 Data flow — generation and duplicate handling

3. Deep Dive

3.1 Data model

Legal Entity (reused) — the company on whose registration the e-Way Bill is generated.

Originating Document (plain, generic documents) — six document types share one workflow: a sales invoice, a purchase invoice, a delivery note, a goods receipt, an internal stock-movement entry, and a subcontracting receipt. Only the sales invoice carries a dedicated status field tracking where it sits in the lifecycle; the other five carry the e-Way Bill number itself but no separate status field — their state is inferred from whether that number is set and from the e-Way Bill Record it points to.

e-Way Bill Record — one row per issued e-Way Bill, keyed by the e-way bill number itself. Holds:

State Threshold Override — one row per state, each carrying whether an intrastate (within-state) e-Way Bill rule applies there at all, and, if so, the value it triggers at. Only states that need a different rule from the installation’s single global threshold need a row; every other state falls back to that global value.

Module Configuration Singleton (reused) — beyond the shared credential/session fields, this workflow reads: whether the feature is enabled at all; the single global e-Way Bill value threshold; whether a companion e-Way Bill should be generated automatically alongside a sales invoice’s IRN, and separately whether it should be generated automatically on submission of an applicable document even without a companion IRN; whether to auto-cancel on document cancellation and under what reason; whether generated data should be re-fetched immediately and whether a PDF should be attached automatically; and whether the shared retry sweep is enabled.

External Call Log (reused) — every attempt against the government service, masked and logged.

3.2 Threshold algorithm — what makes an e-Way Bill required

A special economic zone counterparty is always treated as inter-state regardless of the physical source/destination states — it is the one category-driven override in an otherwise state-and-value calculation. Two further gates sit outside this diagram and are checked before it ever runs: the movement must actually carry goods (a line whose classification code is a services code does not count), and the two parties’ registration numbers must differ — a transfer between two addresses under the same registration is excluded outright, the same same-registration rule the IRN workflow applies to invoices.

3.3 Generation, Part-A/Part-B, and duplicate handling

A companion e-Way Bill is generated through the e-Invoice service, in the same call that issues the IRN, whenever the invoice is taxable throughout, is not a return or a rate-adjustment document, is not an export, and does not already have an e-Way Bill. Every other case — the other five document types, or a sales invoice excluded from that bundling — generates standalone through the dedicated e-Way Bill service.

Whether transporter identity alone, or full vehicle detail, is required at generation time depends on what is already known: if a transporter’s own registration identifier is on file, the government service accepts generation with that identity alone — a “Part-A only” e-Way Bill, carrying no validity period yet, because a validity period cannot be computed without a distance and a mode of transport. If no transporter identity is on file, full vehicle and transport-mode details are mandatory at generation time instead, and the e-Way Bill is generated complete with a validity window from the start.

Duplicate handling differs sharply between the two generation paths:

• Bundled with an IRN: if the government service reports that an e-Way Bill was already generated for this specific IRN, the system automatically fetches that existing e-Way Bill by IRN and adopts it — no operator involvement required.
• Standalone: if the government service reports that an e-Way Bill was already generated for this document number, the system does not attempt automatic recovery. It surfaces a hard failure directing the operator to a dedicated date-based lookup tool, which queries the government service for e-Way Bills generated on a given date and matches by document number and active status before adopting one into the local record.
• A third variant exists specifically for the IRN-bundled path when the underlying IRN itself cannot be found in the government’s e-Way Bill data (a narrow case where the IRN was issued through a different route than this system expects): the system falls back to generating the e-Way Bill standalone instead of continuing to insist on the bundled path.

3.4 Part-B update, transporter update, and extension

Three distinct operations modify an e-Way Bill after it exists, none of them requiring cancellation and regeneration:

• Vehicle info update: submits updated vehicle number, place and reason for change. Blocked once the e-Way Bill’s own validity has already lapsed — an e-Way Bill past its validity must be extended, not vehicle-updated.
• Transporter update: reassigns which transporter is attached to the e-Way Bill, using the same validity check.
• Extension: requires a remaining distance no greater than the distance originally declared, and a reason drawn from a fixed government list. It is only permitted within an eight-hour window on either side of the current expiry time. Outside that window, an extension request cannot be submitted immediately — the caller instead schedules it, storing the full extension payload on the e-Way Bill Record, and a daily background sweep executes every scheduled extension whose window has since opened, once per day.

All three operations mark the e-Way Bill Record’s cached data explicitly stale immediately after the call succeeds, rather than trying to merge the change into the cached copy locally — the next consumer that needs the full record (a print, a PDF attachment, a validity check) triggers a fresh fetch instead of trusting a locally reconstructed guess.

3.5 Cancellation and window enforcement

An e-Way Bill can be cancelled only within 24 hours of its own generation time — checked client-side against the stored creation timestamp before any cancellation call is attempted, mirroring the equivalent IRN rule. A cancellation reason is required and mapped to a fixed government reason code. On success, the e-Way Bill Record is updated with the cancellation flag, reason, remark and timestamp, the originating document’s own e-Way Bill number is cleared, and any attached PDF copy is deleted since it now represents a cancelled artifact.

An e-Way Bill generated through the sandbox fallback path together with an IRN is cancelled through that same e-Invoice service rather than the standalone e-Way Bill service — cancellation must go back through whichever service actually issued the number.

3.6 Status lifecycle

3.7 API contract (illustrative)

POST /GENEWAYBILL or POST /invoice (bundled with IRN)
  -> { ewayBillNo / EwbNo, ewayBillDate / EwbDt, validUpto / EwbValidTill }
  -> Part-A only: number issued, no validity fields present yet

POST /VEHEWB              update vehicle info    -> updated record, marks cache stale
POST /UPDATETRANSPORTER   update transporter     -> marks cache stale
POST /EXTENDVALIDITY      extend validity        -> new validUpto, marks cache stale
POST /CANEWB              cancel                 -> cancellation timestamp
GET  /GetEwayBill?ewbNo=  fetch current government-side data (resolves staleness)
GET  /GetEwayBillsByDate  locate an e-Way Bill by date and document number (manual recovery)

3.8 Error handling and retry

• Transient failures feed the same shared, module-wide retry-pending flag and five-minute sweep described for IRN generation — a transient failure on one document defers every other pending e-Way Bill generation until the sweep clears the flag, not just the document that failed.
• A duplicate-generation reported by the portal but unknown to the local record — “generated for the same document number” — is deliberately not auto-resolved on the standalone path, unlike the IRN workflow’s duplicate handling. The operator is pointed at a date-based lookup rather than the system guessing which existing e-Way Bill to adopt, because the standalone endpoint’s error carries no e-Way Bill number to fetch directly, only a description.
• Already-cancelled-on-the-portal: a cancellation call reporting that the e-Way Bill was not generated by this registration, or is already cancelled, is treated as a successful cancellation rather than an error, stamped with the current time as a best-effort value since the government service does not return the original cancellation timestamp in that response.
• Manual reconciliation: both generation and cancellation accept an operator-entered outcome for situations outside this pipeline’s own reach — most commonly, a transporter generating or updating the e-Way Bill directly on the government portal using the number handed to them, without this system’s involvement at all.

4. Scale and Reliability

• Load pattern: tracks physical dispatch volume rather than invoicing volume specifically, since five of the six originating document types are not invoices at all — a stock movement or a goods receipt can trigger generation just as a sales invoice can.
• Divergence is structural, not exceptional: because a transporter can act directly on the government portal using only the e-Way Bill number, the cached record is expected to drift out of date routinely, not only on error paths. The explicit staleness flag and on-demand re-fetch exist because continuous synchronization was never attempted — this system deliberately treats the government service as the sole source of truth and its own cache as disposable.
• Two independent scheduled sweeps, different cadences: the five-minute transient-failure sweep and the once-daily scheduled-extension sweep serve different failure classes and do not share logic beyond both reading from the e-Way Bill Record — a shipment whose extension was scheduled because it fell outside the eight-hour window will not have that extension executed until the next daily run, which can be up to 24 hours after the window reopened.
• Item-count consolidation has a ceiling of its own: consolidating by HSN/rate/unit combination handles a long line-item list gracefully up to a point, but a shipment whose combinations — not just its line count — exceed 250 still fails outright with no further fallback.
• Part-B changes are fire-and-invalidate, not fire-and-merge: every update marks the cache stale rather than attempting to reconcile the change into the cached data locally, trading a small amount of extra latency on the next read for never risking a locally-reconstructed record that quietly disagrees with the government’s own.
• Monitoring: a rising count of documents parked in auto-retry signals the same government-side struggle the IRN workflow would show; a rising count of stale, never-re-fetched e-Way Bill Records is a distinct signal worth watching separately, since it points at cached data silently going unused rather than a call failure.

5. Trade-off Analysis

6. What to Revisit as the System Grows

• Automatic recovery for the standalone duplicate path: if the government service’s “already generated for this document number” error is ever paired with a returned e-Way Bill number or a queryable reference, the manual date-lookup step could be replaced with the same automatic adoption the IRN-bundled path already has.
• Faster scheduled-extension execution: a once-daily sweep is a coarse cadence given an eight-hour immediate window; running the sweep on a shorter interval (or triggering it opportunistically when a scheduled extension’s window opens) would shrink the worst-case delay from nearly a day down to whatever that shorter interval is.
• Per-state threshold coverage auditing: since a state without an override row silently falls back to the global threshold, a periodic check flagging states whose actual policy has diverged from the global default — before a shipment is misclassified because of it — would close a quiet correctness gap rather than an obvious one.
• Proactive staleness resolution: today the cache only refreshes when something explicitly asks for fresh data; a background sweep that opportunistically refreshes e-Way Bill Records nearing their validity expiry (when a transporter is most likely to have made portal-side changes) would reduce how often a stale read is served to an end user in the meantime.
• HSN/rate/unit combination limits as volumes grow: the 250-combination ceiling after consolidation has no fallback today; a bulk-shipment use case that regularly approaches it would need either a raised limit (if the government service ever permits one) or an explicit split-shipment workflow, neither of which exists yet.