--- updatedAt: 2026-06-02T14:19:00.000Z agentTools: projectIndex: https://developer.onefinops.com/llms.txt --- # 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](/docs/generate-irn-with-ewaybill) endpoint instead. ## Prerequisites * An OAuth client from the Developer hub (see [Authentication](/docs/authentication)). * **EWB-portal credential** seeded against the supplier GSTIN — see [Set up EWB credentials](/docs/set-up-ewb-credentials). ## The call ```http 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: ```json { "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](/reference/getEWayBillByNumber) 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](/docs/errors). ## NIC enums ### `supplyType` | Value | Meaning | | ----- | ----------------------------- | | `O` | Outward (you're the supplier) | | `I` | Inward (you're the recipient) | ### `subSupplyType` | Code | Meaning | | ---- | ----------------------------- | | `1` | Supply | | `2` | Import | | `3` | Export | | `4` | Job Work | | `5` | For Own Use | | `6` | Job Work Returns | | `7` | Sales Return | | `8` | Others (supply a description) | | `9` | SKD/CKD | | `10` | Line Sales | | `11` | Recipient Not Known | | `12` | Exhibition or Fairs | ### `transactionType` | Value | Meaning | | ----- | --------------------------------------------------------- | | `1` | Regular | | `2` | Bill To / Ship To (buyer differs from consignee) | | `3` | Bill From / Dispatch From (seller differs from consignor) | | `4` | Combination of 2 + 3 | #### 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**: | Field | Carries | | ------------------------------------------------------------- | ----------------------------------------------------------------------------- | | `gstin`, `tradeName`, `stateCode` | the **billed** party (Bill-To on `to`, Bill-From on `from`) and its tax state | | `address1`, `address2`, `place`, `pincode`, `actualStateCode` | the **physical** ship-to / dispatch-from location and its state | **2. The party identity** — through dedicated top-level fields: | Field | When to send | | -------------------------------------------- | ------------------------------------------ | | `shipToGstin`, `shipToTradeName` | **Required** for `transactionType` 2 and 4 | | `dispatchFromGstin`, `dispatchFromTradeName` | Optional, for `transactionType` 3 and 4 | > 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: ```json "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](/reference/getEWayBillByNumber) — 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` | | | --------------- | ---- | | `1` | Road | | `2` | Rail | | `3` | Air | | `4` | Ship | `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). | `vehicleType` | | | ------------- | ------------------------------------------------------ | | `"R"` | Regular | | `"O"` | Over-Dimensional Cargo (longer validity window per km) | ## 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: ```json "transport": { "transportMode": 1, "distance": 0, "vehicleNumber": "KA01AB1234", "vehicleType": "R" } ``` **Part-A slip** — transporter assigns the vehicle later: ```json "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](/docs/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 ```json { "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](/docs/update-part-b) for the limited extension window. ## Where to next * [Update Part-B](/docs/update-part-b) — assign or change the vehicle. * [Extend validity](/docs/extend-ewb-validity) — push out `validUpto`. * [Update transporter](/docs/update-transporter) — hand the EWB to a different transporter. * [Cancel an EWB](/docs/cancel-an-ewb) / [Reject an EWB](/docs/reject-an-ewb). * [Generate IRN with E-Way Bill](/docs/generate-irn-with-ewaybill) — combined call.