> ## Documentation Index
> Fetch the complete documentation index at: https://developer.sandbox.co.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Generate GST e-Invoices with IRN, signed QR codes, and E-Way Bills via India's Invoice Registration Portal (IRP).

# GST e-Invoice API

GST e-Invoice is a GST-compliant invoice registered with the Invoice Registration Portal (IRP) and assigned an IRN (Invoice Reference Number). Use this API to generate IRNs, receive the IRP-signed invoice JSON and QR code, download PDFs, cancel or fetch e-Invoices, and create or retrieve E-Way Bills linked to the IRN.

This API integrates with India's Invoice Registration Portal (IRP) for GST e-invoicing. API credentials are created on the e-Invoice portal and mapped to your GSP.

> [!NOTE]
>
> Sandbox supports dual-IRP routing via the `x-source` header. Route e-Invoice calls to either [NIC 1](https://einvoice1.gst.gov.in/) (`primary`) or [NIC 2](https://einvoice2.gst.gov.in/) (`secondary`). Retry the alternate IRP if one is unavailable.

> **[Dual-IRP routing](https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/e-invoice/authenticate.md)**
>
> Route requests to [NIC 1](https://einvoice1.gst.gov.in/) or [NIC 2](https://einvoice2.gst.gov.in/) using the `x-source` header. Retry with the alternate IRP if one is unavailable.

> **[Complete e-Invoice lifecycle](https://developer.sandbox.co.in/recipes/gst/e-invoice/generate_e_invoice.md)**
>
> Generate, fetch, cancel e-invoices, and create/retrieve E-Way Bills linked to IRN.

> **[Signed invoice & QR code](https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/e-invoice/generate_e_invoice.md)**
>
> Receive IRP-signed invoice and QR code for compliance and audit requirements.

> **[PDF generation](https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/e-invoice/generate_e_invoice_pdf.md)**
>
> Generate e-Invoice PDFs using the signed invoice and QR code data.

> [!NOTE]
>
> **Prerequisites:** To use GST e-Invoice API, you need: (1) API credentials created on the [e-Invoice portal](https://einvoice1.gst.gov.in/), (2) credentials mapped to your GSP, and (3) a Sandbox API key for PDF generation.

## How it works

**1. Create API credentials on e-Invoice portal**

Register on the e-Invoice portal and create API credentials. Map these credentials to your GSP (Goods and Services Tax Suvidha Provider). See [Create API credentials](https://developer.sandbox.co.in/api-reference/gst/compliance/guides/e-invoice/authentication/create_api_credentials.md) for detailed instructions.

**2. Authenticate with Sandbox**

Call the [Sandbox authentication endpoint](https://developer.sandbox.co.in/api-reference/authenticate.md) to obtain a Sandbox access token (JWT). This token is used for Sandbox-specific operations like PDF generation.

**3. Authenticate with e-Invoice IRP**

Call the [e-Invoice authentication endpoint](https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/e-invoice/authenticate.md) with your e-Invoice credentials. Set the `x-source` header to `primary` ([NIC 1](https://einvoice1.gst.gov.in/)) to route to the primary IRP. This returns an e-Invoice session token valid for the IRP. See the [Generate e-Invoice session recipe](https://developer.sandbox.co.in/recipes/gst/authentication/generate_e_invoice_session.md) for implementation details.

**4. Handle IRP failover (if needed)**

If the primary IRP is unavailable or times out, retry the e-Invoice authentication with `x-source: secondary` to route to [NIC 2](https://einvoice2.gst.gov.in/). Use the same approach for all subsequent taxpayer API calls.

**5. Generate e-Invoice**

Post your invoice object to the [Generate e-Invoice endpoint](https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/e-invoice/generate_e_invoice.md). On success, receive the IRN, signed invoice JSON, and signed QR code. Optionally generate an E-Way Bill in the same call. See the [Generate e-Invoice recipe](https://developer.sandbox.co.in/recipes/gst/e-invoice/generate_e_invoice.md) for a complete walkthrough.

**6. Generate e-Invoice PDF**

Call the [Generate PDF endpoint](https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/e-invoice/generate_e_invoice_pdf.md) with the IRN, signed invoice, and signed QR code. This endpoint uses your Sandbox JWT (not the e-Invoice token) since PDF generation is a Sandbox service.

**7. Fetch e-Invoice**

Retrieve an e-Invoice by IRN using [Get e-Invoice](https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/e-invoice/get_e_invoice.md) or by document type, number, and date using [Get e-Invoice by document data](https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/e-invoice/get_e_invoice_by_document_data.md). See the [Get e-Invoice recipe](https://developer.sandbox.co.in/recipes/gst/e-invoice/get_e_invoice_using_taxpayer_api.md) for examples.

**8. Cancel e-Invoice (if needed)**

[Cancel an e-Invoice](https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/e-invoice/cancel_e_invoice.md) by IRN within the cancellation window when required.

**9. Generate E-Way Bill for transportation**

[Generate](https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/e-invoice/generate_e_way_bill.md) or [fetch E-Way Bills](https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/e-invoice/get_e_way_bill.md) linked to the IRN for logistics and transportation compliance.

## API endpoints

### Authentication

| API | Purpose |
| :- | :- |
| [Sandbox Authentication](https://developer.sandbox.co.in/api-reference/authenticate.md) (POST /authenticate) | Obtain Sandbox JWT for PDF generation and other Sandbox services |
| [e-Invoice Authentication](https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/e-invoice/authenticate.md) (POST /gst/compliance/e-invoice/tax-payer/authenticate) | Obtain e-Invoice session token from IRP. Supports `x-source` header |

### e-Invoice operations

| API | Purpose |
| :- | :- |
| [Generate e-Invoice](https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/e-invoice/generate_e_invoice.md) (POST /gst/compliance/e-invoice/tax-payer/invoice) | Generate IRN with signed invoice and QR code. Supports `x-source` header |
| [Get e-Invoice by IRN](https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/e-invoice/get_e_invoice.md) (GET /gst/compliance/e-invoice/tax-payer/invoice/\{irn}) | Fetch e-Invoice details by IRN. Supports `x-source` header |
| [Get e-Invoice by document data](https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/e-invoice/get_e_invoice_by_document_data.md) (GET /gst/compliance/e-invoice/tax-payer/invoice) | Fetch e-Invoice by document type, number, and date. Supports `x-source` header |
| [Cancel e-Invoice](https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/e-invoice/cancel_e_invoice.md) (POST /gst/compliance/e-invoice/tax-payer/invoice/\{irn}/cancel) | Cancel an e-Invoice by IRN. Supports `x-source` header |
| [Generate e-Invoice PDF](https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/e-invoice/generate_e_invoice_pdf.md) (POST /gst/compliance/e-invoice/pdf/generate) | Generate PDF from signed invoice and QR. Uses Sandbox JWT |
| [Search GSTIN](https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/e-invoice/search_gstin.md) (POST /gst/compliance/e-invoice/tax-payer/gstin/search) | Look up GSTIN details in IRP database (not GSTN) |

### E-Way Bill (from e-Invoice)

| API | Purpose |
| :- | :- |
| [Generate E-Way Bill](https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/e-invoice/generate_e_way_bill.md) (POST /gst/compliance/e-invoice/tax-payer/invoice/\{irn}/e-way-bill) | Generate E-Way Bill linked to IRN. Supports `x-source` header |
| [Get E-Way Bill](https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/e-invoice/get_e_way_bill.md) (GET /gst/compliance/e-invoice/tax-payer/invoice/\{irn}/e-way-bill) | Retrieve E-Way Bill details by IRN. Supports `x-source` header |

## Common use cases

Use GST e-Invoice API when you need to:

* Generate GST e-invoices (IRN) and store signed invoice + QR for compliance and audit
* Provide "Download invoice PDF" functionality to customers and finance teams
* Cancel wrongly issued e-invoices by IRN within the cancellation window
* Fetch e-invoices by IRN or by document reference for reconciliation and support
* Generate and retrieve E-Way Bills linked to IRN for logistics and transportation
* Validate GSTIN details via IRP lookup before invoicing

## Frequently Asked Questions

> **What is GST e-Invoice?**
>
> GST e-Invoice is a GST-compliant invoice registered with India's Invoice Registration Portal (IRP). Each e-Invoice receives a unique Invoice Reference Number (IRN) and is digitally signed by the IRP. The signed invoice and QR code serve as proof of registration for compliance and audit purposes. See [Create API credentials](https://developer.sandbox.co.in/api-reference/gst/compliance/guides/e-invoice/authentication/create_api_credentials.md) to get started.

> **How does GST e-Invoice API work end-to-end?**
>
> The workflow is: create e-Invoice API credentials and map them to your GSP, authenticate with Sandbox for a JWT, authenticate with the IRP for a session token, submit invoice data to generate the IRN with signed invoice and QR code, then optionally generate a PDF and manage fetch, cancel, or E-Way Bill actions. All taxpayer endpoints support dual-IRP routing via `x-source`. See the [Generate e-Invoice recipe](https://developer.sandbox.co.in/recipes/gst/e-invoice/generate_e_invoice.md) for a complete example.

> **What is the x-source header in Sandbox e-Invoice APIs?**
>
> The `x-source` header enables dual-IRP routing in Sandbox e-Invoice APIs. Set `x-source: primary` to route requests to [NIC 1](https://einvoice1.gst.gov.in/) (the primary IRP) or `x-source: secondary` to route to [NIC 2](https://einvoice2.gst.gov.in/) (the secondary IRP). If omitted, requests default to `primary`. This header is supported on all taxpayer endpoints, including [authentication](https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/e-invoice/authenticate.md), generate, fetch, cancel, and E-Way Bill operations.

> **What credentials are required to call e-Invoice Authentication?**
>
> e-Invoice Authentication requires credentials created on the e-Invoice portal: your GSTIN, username, and password. These credentials must be mapped to your GSP (Goods and Services Tax Suvidha Provider). The [Create API credentials guide](https://developer.sandbox.co.in/api-reference/gst/compliance/guides/e-invoice/authentication/create_api_credentials.md) provides step-by-step instructions for setting up these credentials.

> **Why does e-Invoice PDF generation use Sandbox JWT instead of the e-Invoice token?**
>
> e-Invoice PDF generation is a Sandbox service, not an IRP service. The IRP provides the signed invoice JSON and QR code data, but does not offer PDF generation. Sandbox renders the PDF from this data, so the [Generate e-Invoice PDF](https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/e-invoice/generate_e_invoice_pdf.md) endpoint requires a Sandbox JWT for authentication rather than the IRP session token.

> **Can I generate an E-Way Bill from an e-Invoice IRN?**
>
> Yes, GST e-Invoice API supports generating E-Way Bills linked to an existing IRN. Use the [Generate E-Way Bill](https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/e-invoice/generate_e_way_bill.md) endpoint with the IRN to create an E-Way Bill for transportation. You can also [retrieve E-Way Bill details](https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/e-invoice/get_e_way_bill.md) by IRN. Both endpoints support dual-IRP routing via the `x-source` header.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.