Skip to main content

​
E-Invoice List API

E-Invoice List API downloads sales and purchase e-invoice lists for a return period (financial year + month). You can submit async jobs, poll for status, and download JSON for up to the last 6 months. When you need invoice-level details, fetch them by IRN. The API connects to the GST Network (NIC) e-invoicing system, so you can retrieve and reconcile e-invoice data for compliance and internal controls.

Async job processing

Submit list jobs and poll for completion when ready. Your application keeps running while jobs process in the background.

Signed JSON URL

Get a time-bound signed URL to download e-invoice lists securely. URLs expire, so download promptly.

Supply type filter

Filter by supply type (B2B, exports, SEZ) to download specific invoice categories for targeted reconciliation.

IRN drill-down

Fetch a single e-invoice by Invoice Reference Number (IRN) for invoice-level details. Party-restricted to buyer or seller.

​
How it works

1

Authenticate taxpayer session

Start by authenticating to get a taxpayer access token. You’ll need this token for all e-invoice list API calls.
2

Submit e-invoice list job

Submit a purchase or sales e-invoice list job for a specific return period with the required supply_type parameter.
3

Capture and store job ID

Save the job_id from the submission response. You’ll use it to check job status.
4

Poll job status

Poll the job status endpoint using the job_id until status = succeeded.
5

Download e-invoice list

Download the JSON data from the signed e_invoice_list_url and store it in your system.
6

Fetch invoice by IRN (optional)

Retrieve a single e-invoice by Invoice Reference Number (IRN) for invoice-level details. Restricted to transaction parties (buyer or seller).

​
What you can do

Download purchase e-invoices

Retrieve purchase e-invoice lists for AP reconciliation and vendor matching.

Download sales e-invoices

Retrieve sales e-invoice lists for AR reconciliation and sales registers.

Generate taxpayer session

Start here: authenticate to get a taxpayer access token for e-invoice list APIs.

Handle errors

See error codes and handling for invalid periods or expired windows.

​
API categories

List Purchase e-Invoices (Submit Job)

Submit an async job to list purchase e-invoices for a return period.

List Purchase e-Invoices (Job Status)

Check the status of a purchase e-invoice list job.

List Sales e-Invoices (Submit Job)

Submit an async job to list sales e-invoices for a return period.

List Sales e-Invoices (Job Status)

Check the status of a sales e-invoice list job.

Get e-Invoice by IRN

Retrieve a single e-invoice using its Invoice Reference Number.

​
API reference

​
Job submission APIs

APIPurpose
List Purchase e-Invoices (Submit Job)Submit async job to download purchase e-invoices for a return period
List Sales e-Invoices (Submit Job)Submit async job to download sales e-invoices for a return period

​
Job status APIs

APIPurpose
List Purchase e-Invoices (Job Status)Poll status and get signed download URL for purchase e-invoice list
List Sales e-Invoices (Job Status)Poll status and get signed download URL for sales e-invoice list

​
Invoice retrieval API

APIPurpose
Get e-Invoice by IRNFetch a single e-invoice by Invoice Reference Number (party-restricted)

​
Common use cases

Use E-Invoice List API when you need to:
  • Monthly AP reconciliation: Compare purchase e-invoice lists with vendor bills in ERP to identify missing or duplicate invoices.
  • Monthly AR register: Build sales registers from e-invoice lists for reporting and internal controls.
  • Supply-type segmentation: Run separate downloads by supply_type (B2B, exports, SEZ) for category-wise reporting.
  • Audit and support drill-down: Fetch a single e-invoice by IRN to resolve disputes, validate invoice values, or support tickets.
  • Automated matching: Match e-invoice lists with internal invoice master data to flag exceptions before return filing.

​
Frequently Asked Questions

E-Invoice List API downloads sales and purchase e-invoice lists for a return period (year + month). You can filter by supply type and download data via signed URLs.
The API uses an async job pattern. Submit a list job with return period and supply type, save the job_id, then poll the status endpoint until the job completes. Once it’s done, download the JSON from the signed URL. See Job-based APIs for polling best practices.
You can retrieve e-invoices for up to the last 6 months. Requests for periods beyond this window will return an error.
Supply type (supply_type) indicates the transaction category—B2B, exports, or SEZ. You must include it when submitting a list job. This determines which invoices show up in your results.
The signed e_invoice_list_url expires after a set time. Download the JSON soon after your job completes. If the URL expires, just submit a new job to get a fresh link.
Use a backoff strategy: start with shorter intervals, then gradually increase the wait time between checks. Don’t poll too aggressively or you’ll hit rate limits. See Rate Limits for details.
Yes. Instead of polling job status repeatedly, you can subscribe to job completion events via webhooks. Sandbox will notify your endpoint when the job finishes, so you can download the results immediately. See Webhooks to configure webhook subscriptions and validate signatures.
Only parties involved in the transaction can fetch invoices by IRN. If you’re listed as the buyer or seller on the e-invoice, you can retrieve it using the Get e-Invoice by IRN endpoint.