Generate IRN with E-Way Bill

When the consignment moves on the same invoice, you can issue the IRN and the linked E-Way Bill in a single call to POST /v1/einvoices/generate. NIC creates both, returns the IRN plus ewbNumber / ewbDate / ewbValidTill in the same response, and the IRP credential is reused — no separate EWB-portal credential is needed for the EWB leg.

Use the combined call when:

• The IRN and EWB are for the same physical movement and transport details are known up front.
• You want a single idempotent call to manage in your job runner instead of two coupled writes.
• You don't want to onboard EWB-portal credentials for this GSTIN.

If transport details aren't known at IRN time (transporter assigned later, vehicle not yet allocated, Part-A first then Part-B), generate the IRN alone now and follow up with POST /v1/ewaybills/generate passing the returned irn.

Prerequisites

• An OAuth client from the Developer hub (see Authentication).
• An IRP credential seeded against the seller GSTIN — see Set up IRN credentials. The same credential is used for the EWB leg in this combined call.
• Production only: the seller GSTIN must be enrolled on both the IRP and the EWB portals at NIC. Otherwise NIC commits the IRN, ignores the eWayBillDetails block, and returns ewbNumber: null.

Sandbox limitation

NIC's sandbox runs the IRP and EWB portals as two disjoint enrolment sets. No sandbox GSTIN is enrolled on both portals. The practical effect:

• The IRP accepts your eWayBillDetails block (it appears verbatim in the signed JWS NIC returns), but
• NIC silently skips EWB generation and the response has ewbNumber: null regardless of distance, vehicle, or transporter values.

For sandbox testing, use the two-step variant: call POST /v1/einvoices/generate (omit the eWayBillDetails block), capture the returned irn, then call POST /v1/ewaybills/generate with "irn": "<that-irn>" in the body. The standalone EWB path uses an EWB-portal sandbox credential and does issue a real ewbNumber. In production, once your live GSTIN has both portal enrolments, the combined call returns the EWB details populated in the same response.

eWayBillDetails field reference

NIC enforces the same conditional rules as the standalone EWB call — see Generate an EWB for the underlying state machine.

Three common shapes

Road with vehicle assigned (Part-A + Part-B in one shot)

"eWayBillDetails": {
  "distance": 980,
  "transportMode": "1",
  "vehicleNumber": "KA01AB1234",
  "vehicleType": "R",
  "transporterId": "29ABCDE1234F1Z5"
}

NIC issues a fully active EWB with ewbValidTill derived from distance.

Road, transporter assigns vehicle later (Part-A only)

"eWayBillDetails": {
  "distance": 980,
  "transportMode": "1",
  "transporterId": "29ABCDE1234F1Z5",
  "transporterName": "Acme Logistics",
  "transportDocumentNumber": "LR-2026-7788",
  "transportDocumentDate": "2026-05-14"
}

Omit vehicleNumber / vehicleType and supply the transporter plus the lorry-receipt details. The transporter later fills Part-B via Update Part-B.

Rail / Air / Ship

"eWayBillDetails": {
  "distance": 1240,
  "transportMode": "2",
  "transporterId": "29ABCDE1234F1Z5",
  "transportDocumentNumber": "RR/CHN/2026/0451",
  "transportDocumentDate": "2026-05-14"
}

vehicleNumber and vehicleType are not applicable; the transport document number + date (RR, AWB, BL) are mandatory.

Full request

POST /v1/einvoices/generate HTTP/1.1
Host: api.in.onefinops.com
Authorization: Bearer eyJhbGciOi...
gstin: 29ABCDE1234F1Z5
Content-Type: application/json
X-Request-Id: 4f1d8a2c-…

{
  "documentDetails": {
    "type": "INV",
    "number": "INV/2026/00001",
    "date": "2026-05-14"
  },
  "transactionDetails": {
    "taxScheme": "GST",
    "supplyType": "B2B"
  },
  "seller": {
    "gstin": "29ABCDE1234F1Z5",
    "legalName": "Acme Pvt Ltd",
    "address1": "12 Industrial Area",
    "location": "Bengaluru",
    "pincode": 560001,
    "stateCode": "29"
  },
  "buyer": {
    "gstin": "27FGHIJ5678K1Z2",
    "legalName": "Globex Pvt Ltd",
    "address1": "8 MG Road",
    "location": "Mumbai",
    "pincode": 400001,
    "stateCode": "27",
    "placeOfSupplyStateCode": "27"
  },
  "items": [{
    "serialNumber": "1",
    "productDescription": "Consulting services",
    "isService": "Y",
    "hsnCode": "998314",
    "quantity": 1,
    "unit": "NOS",
    "unitPrice": 10000,
    "totalAmount": 10000,
    "assessableAmount": 10000,
    "gstRate": 18,
    "igstAmount": 1800,
    "totalItemValue": 11800
  }],
  "valueDetails": {
    "assessableValue": 10000,
    "igstValue": 1800,
    "totalInvoiceValue": 11800
  },
  "eWayBillDetails": {
    "distance": 980,
    "transportMode": "1",
    "vehicleNumber": "KA01AB1234",
    "vehicleType": "R",
    "transporterId": "29ABCDE1234F1Z5"
  }
}

Response

The standard IRN response with the EWB fields populated:

{
  "irn": "a1b2c3d4e5f6...",
  "ackNumber": 112324567890123,
  "ackDate": "2026-05-14T11:42:18.000Z",
  "status": "ACT",
  "signedInvoice": "eyJhbGciOi...",
  "signedQRCode": "eyJhbGciOi...",
  "ewbNumber": 112345678901,
  "ewbDate": "2026-05-14T11:42:19.000Z",
  "ewbValidTill": "2026-05-15T23:59:59.000Z",
  "message": "E-Invoice generated successfully"
}

Persist both irn and ewbNumber against your invoice. From here every read / update / cancel works the same as if the EWB had been generated standalone:

• Read the EWB: GET /v1/ewaybills/ewbnumber?ewbNumber={ewbNumber} with the gstin header.
• Update Part-B, extend validity, cancel or reject — see Update Part-B, Extend validity, Cancel an EWB, Reject an EWB, Update transporter.

When the IRN is created but EWB is null

NIC's behaviour when the IRP accepts the IRN but skips the EWB is to commit the IRN and return ewbNumber: null without surfacing an error. This can happen because:

• The seller GSTIN is not enrolled on the EWB portal (the sandbox case above).
• Distance failed NIC's PIN-to-PIN validation. The standalone EWB call returns the explicit code 4013 : The distance between the pincodes given is too high or low; the combined call does not surface that error — it drops the EWB block silently.
• The EWB portal was briefly unreachable on NIC's side.

In all these cases the IRN is valid and persisted — do not cancel it. Retry only the EWB by calling POST /v1/ewaybills/generate with "irn": "<the-returned-irn>" in the body. That path validates against the EWB portal and surfaces NIC's actual error code if generation still fails.

A full IRP failure (validation, duplicate, credentials) behaves identically to the plain IRN call — see the error table on Generate an IRN.

Cancelling a combined IRN + EWB

Cancelling the IRN does not cancel the linked EWB, and NIC will not let you cancel the IRN while an active EWB exists for it. POST /v1/einvoices/cancel on such an IRN returns NIC 2230 "This IRN cannot be cancelled because e-way bill has been generated, you can cancel e-way bill and then try cancelling IRN". The IRN and the EWB are two independent documents; there is no cascade.

Cancel them in order:

1. Cancel the EWB first with POST /v1/ewaybills/cancel (body: ewbNumber, cancelReasonCode, cancelRemark). NIC allows EWB cancellation within 24 hours of generation, and only while it has not been verified in transit.
2. Then cancel the IRN with POST /v1/einvoices/cancel, within 24 hours of IRN generation.

The combined call generates the EWB through the IRP credential, but cancelling that EWB needs an EWB-portal credential for the same GSTIN (seed one via POST /v1/ewb-credentials). If you never onboarded an EWB credential, you can read the EWB back but cannot cancel it until that credential is seeded — so the IRN stays uncancellable too. See Cancel an EWB and Cancel an IRN.

Where to next

• Generate an IRN
• Generate an EWB
• Update Part-B
• Cancel or reject an EWB