Generate an E-Way Bill

An E-Way Bill (EWB) is the digital transit document India's GST system requires for goods movement above ₹50,000. Generate one with POST /v1/ewaybills/generate.

This endpoint generates a standalone EWB from a full payload — supplier, recipient, items, totals, transport details. If you've already generated an IRN and want NIC to mint the EWB from the IRN's invoice data, use the dedicated Generate IRN with E-Way Bill endpoint instead.

Prerequisites

• An OAuth client from the Developer hub (see Authentication).
• EWB-portal credential seeded against the supplier GSTIN — see Set up EWB credentials.

The call

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

Send the full payload:

{
  "supplyType": "O",
  "subSupplyType": "1",
  "documentType": "INV",
  "documentNumber": "DC/2026/0044",
  "documentDate": "2026-05-14",
  "transactionType": 1,
  "from": {
    "gstin": "29ABCDE1234F1Z5",
    "tradeName": "Acme Pvt Ltd",
    "address1": "12 Industrial Area",
    "place": "Bengaluru",
    "pincode": 560001,
    "stateCode": 29,
    "actualStateCode": 29
  },
  "to": {
    "gstin": "27FGHIJ5678K1Z2",
    "tradeName": "Globex Pvt Ltd",
    "address1": "8 MG Road",
    "place": "Mumbai",
    "pincode": 400001,
    "stateCode": 27,
    "actualStateCode": 27
  },
  "totals": {
    "totalValue": 10000,
    "cgstValue": 0,
    "sgstValue": 0,
    "igstValue": 1800,
    "cessValue": 0,
    "cessNonAdvolValue": 0,
    "totalInvoiceValue": 11800
  },
  "transport": {
    "transportMode": 1,
    "distance": 980,
    "vehicleNumber": "KA01AB1234",
    "vehicleType": "R"
  },
  "items": [{
    "productName": "Consulting services",
    "hsnCode": "998314",
    "quantity": 1,
    "unit": "NOS",
    "cgstRate": 0,
    "sgstRate": 0,
    "igstRate": 18,
    "taxableAmount": 10000
  }]
}

documentNumber is capped at 16 characters (alphanumerics and / - only); longer or otherwise invalid values are rejected by NIC with "Invalid Invoice Number".

Distance

distance (km) is mandatory and drives the EWB validity window. NIC validates it against its own pin-to-pin road-distance reference for the source and destination pincodes.

• Don't know the exact road distance? Send distance: 0. NIC then auto-calculates the pin-to-pin distance, applies it, and computes validity from it. The value NIC used is returned on generation and on the Get E-Way Bill response — read it back and store it if you need it.
• If NIC has no distance on file for the route, distance: 0 is rejected with "The distance between the given pincodes are not available in the system. Please provide distance". This happens for a small number of pincode pairs NIC has not mapped. Retry the same request with the actual road distance between the two pincodes: a positive value up to 4000 km, from your own logistics data or a maps distance API. For these unmapped routes NIC accepts the value you supply (the ~10% tolerance below applies only where NIC has a reference distance).
• Supplying your own value? Keep it within roughly 10% above NIC's calculated distance. A value outside that tolerance is rejected with "The distance between the pincodes given is too high".
• Don't omit the field and don't use a fixed placeholder like 999. Omitting it returns "Invalid Approximate Distance"; a hardcoded constant fails the pin-to-pin check on most routes. 0 is the correct "let NIC decide" value.

These distance errors are NIC validations surfaced as 502 upstream.failure with the NIC message passed through verbatim — see Errors.

NIC enums

supplyType

subSupplyType

transactionType

Bill-To/Ship-To and Bill-From/Dispatch-From

Use these when the party that is billed differs from the party/location the goods physically move to or from — common in drop-shipping, branch transfers, and third-party warehousing.

NIC carries two distinct things for each split:

1. The physical location — through the to/from party object using the two state codes:

2. The party identity — through dedicated top-level fields:

If you set transactionType to 2 or 4 without shipToGstin, NIC rejects the request with "ship to from gstin is mandatary", surfaced as 422 GST_SHIP_TO_GSTIN_REQUIRED. The state-code split alone is not sufficient; the ship-to GSTIN is mandatory.

A Bill-To/Ship-To is the recipient billing at one registration and receiving the goods at another. NIC distinguishes the two GSTINs explicitly:

• toGstin = the recipient's billing-location GSTIN (who is invoiced), with toTradeName and stateCode (the billing/tax state).
• shipToGstin = the GSTIN of the location where the goods are shipped (who actually receives them), with shipToTradeName.
• The delivery address itself goes on to's address1/place/pincode + actualStateCode (the physical state).

So a Bill-To/Ship-To movement (transactionType: 2) looks like:

"transactionType": 2,
"to": {
  "gstin": "27FGHIJ5678K1Z2",
  "tradeName": "Globex Pvt Ltd (Head Office)",
  "stateCode": 27,
  "address1": "Warehouse 7, Roorkee Industrial Estate",
  "place": "Roorkee",
  "pincode": 247667,
  "actualStateCode": 5
},
"shipToGstin": "05AAACG2140A1ZL",
"shipToTradeName": "Globex Roorkee Warehouse"

Here Globex is billed in Maharashtra (stateCode: 27) but the goods are delivered to Uttarakhand (actualStateCode: 5): NIC uses actualStateCode and the address for distance, validity, and route, stateCode for the tax treatment, and shipToGstin to identify the consignee at the delivery location.

Bill-From/Dispatch-From (transactionType: 3) is the mirror image on the from object: from.gstin is the seller's billing-location GSTIN, from's address + actualStateCode is where the goods are actually dispatched from, and dispatchFromGstin is the GSTIN of that dispatch location (dispatchFromGstin / dispatchFromTradeName are optional for type 3).

Combination (transactionType: 4) applies both splits, and like type 2 it requires shipToGstin (plus an optional dispatchFromGstin).

NIC does not return shipToGstin / dispatchFromGstin on a later Get E-Way Bill — persist them yourself if you need to read them back.

The pincode must belong to the state in actualStateCode (NIC validates actFromStateCode↔fromPincode and actToStateCode↔toPincode). For a regular movement (transactionType: 1), keep stateCode and actualStateCode equal.

transportMode and vehicleType

transportMode is a JSON integer (not a string). It is optional — supply it only with Part-B vehicle/transport-document details. See Part-A vs Part-B.

Part-A vs Part-B

NIC splits the EWB into:

• Part-A — the consignment metadata (parties, items, totals).
• Part-B — the vehicle assignment.

Send exactly one of these transport shapes:

Full EWB (Part-A + Part-B) — vehicle is known now:

"transport": {
  "transportMode": 1,
  "distance": 0,
  "vehicleNumber": "KA01AB1234",
  "vehicleType": "R"
}

Part-A slip — transporter assigns the vehicle later:

"transport": {
  "distance": 0,
  "transporterId": "29ABCDE1234F1Z5",
  "transporterName": "Blue Dart Logistics"
}

⚠️

For a Part-A-only slip you must omit transportMode, vehicleNumber and vehicleType entirely. If you send transportMode (e.g. 1 for road) without a vehicle number, NIC rejects the request with "Vehicle number is required" — this is the single most common cause of failed Part-A generation. transportMode is not needed for a Part-A slip.

transporterId rules:

• Must be a GSTIN or NIC TRANSIN that is registered on the NIC E-Way Bill system. An unregistered value is rejected with "Invalid Transporter Id".
• Must be different from both the supplier (from.gstin) and recipient (to.gstin) GSTINs.

The transporter completes Part-B later via Update Part-B. A Part-A slip has no validity window until Part-B is added (validUpto is null on the response).

For non-road modes (rail / air / ship), supply transportMode plus transportDocumentNumber and transportDocumentDate (LR / RR / AWB / BL number and date) — vehicleNumber does not apply.

Successful response

{
  "ewbNumber": 112345678901,
  "ewayBillDate": "2026-05-14T11:50:18.000Z",
  "validUpto": "2026-05-15T23:59:59.000Z",
  "status": "ACT"
}

Validity periods

NIC computes validity from the consignment distance:

• Up to 100 km → 1 day.
• Each additional 100 km (or part) → +1 day.
• Over-Dimensional Cargo (vehicleType: "O") → 1 day per 20 km.

validUpto is the absolute expiry timestamp. After it lapses you cannot retroactively revive the EWB — see Extend validity for the limited extension window.

Where to next

• Update Part-B — assign or change the vehicle.
• Extend validity — push out validUpto.
• Update transporter — hand the EWB to a different transporter.
• Cancel an EWB / Reject an EWB.
• Generate IRN with E-Way Bill — combined call.