Skip to main content

​
GSTR-9 API

GSTR-9 is the GST annual return filed once per financial year for each GSTIN. It reports consolidated purchases, sales, input tax credit (ITC), and tax paid. Use these APIs to fetch GSTN-prepared summaries, review Section 8A ITC, save a draft, proceed to filing, generate an EVC OTP, submit the return, and track status on the GST portal.

​
Key capabilities

Auto-calculated annual totals

Fetch GSTN-prepared annual summaries for reconciliation of purchases, sales, and tax liability.

Section 8A ITC review

Review portal-populated ITC figures used for annual input tax credit reporting.

Draft save and proceed workflow

Save prepared values as a GSTN draft, then run portal validations before filing.

EVC OTP filing and status tracking

Generate an EVC OTP, submit the annual return, and poll return status until confirmation.

​
How it works

1

Initiate taxpayer session

Authenticate and start a taxpayer session using the Generate Taxpayer Session recipe.
2

Fetch current GSTR-9 draft

Get the latest draft for the target financial year using Get GSTR-9 details.
3

Fetch auto-calculated annual totals

Retrieve GSTN auto-calculated values using Get auto-calculated details.
4

Fetch Section 8A details

Review portal-populated ITC figures using Get Section 8A details.
5

Prepare HSN mapping (if needed)

Use Get HSN to build and validate HSN/SAC summaries when required for annual reporting.
6

Save draft

Submit prepared values with Save GSTR-9 to store the return as a draft.
7

Proceed to filing

Run GSTN validations with Proceed GSTR-9.
8

Generate EVC OTP, file, and track status

Request Generate EVC OTP, submit File GSTR-9, then poll Get GST return status.

​
Recipes and guides

File GSTR-9

Step-by-step recipe to file GSTR-9 using the full API workflow.

Error handling guide

Handle GSTN errors, retries, and common validation failures across all GST APIs.

Track GST return status

Poll return status to confirm filing or identify pending actions.

​
API categories

Draft and summaries

Fetch the current draft and auto-calculated annual totals for reconciliation.

ITC and Section 8A

Review portal-populated ITC figures for annual input tax credit reporting.

Filing actions

Save drafts, proceed to filing, generate an EVC OTP, and submit the annual return.

Status and utilities

Track filing status and look up HSN codes for summary preparation.

​
API reference

​
Draft and summary endpoints

​
Filing action endpoints

​
Status and utility endpoints

​
Common use cases

Use the GSTR-9 API when you need to:
  • Consolidate FY sales and purchases in your ERP, then draft and file GSTR-9 for each GSTIN.
  • File GSTR-9 in bulk for many GSTINs with a consistent draft-save-proceed-file flow and audit logs.
  • Compare auto-calculated values and Section 8A ITC against internal books to spot variances before filing.
  • Build a filing timeline UI that polls return status and alerts users when GSTR-9 is filed or needs action.
  • Validate HSN codes and build HSN-level summaries using HSN utilities to reduce classification errors.

​
FAQs

GSTR-9 is the GST annual return that consolidates purchases, sales, input tax credit, and tax paid for a financial year. Regular taxpayers registered under GST must file it annually unless exempted by government notification. Some taxpayer categories have different annual return requirements or may be exempt. You can file once all periodic returns for the financial year are complete. See File GSTR-9 for the API workflow.
Start a taxpayer session for the GSTIN. Fetch the current draft and auto-calculated annual totals from GSTN. Review Section 8A ITC details and prepare HSN mappings if needed. Save the draft with Save GSTR-9, then run validations. Generate an EVC OTP with Generate EVC OTP, file the return, and poll GST return status until confirmation.
Auto-calculated details are GSTN-prepared annual summaries based on periodic returns filed during the year. The GSTR-9 API retrieves these values as a reconciliation baseline. Compare them with your internal books to identify discrepancies before populating the draft. Access them via Get auto-calculated details.
Section 8A contains ITC figures auto-populated by the GST portal from supplier returns for the financial year. GSTR-9 reporting depends on these values for annual ITC reconciliation. Review Section 8A details using Get Section 8A details and compare with claimed ITC to identify mismatches before filing.
Filing can take time to reflect on the GST portal while GSTN processes it. Poll Get GST return status until the status confirms filing. If the status stays pending beyond expected timeframes, check for GSTN errors in the response and consult the error handling guide.
EVC (Electronic Verification Code) OTP filing requires generating an OTP sent to the registered mobile number or email of the authorized signatory. Call Generate EVC OTP, then pass the OTP to File GSTR-9 to submit the return.
Make sure all tables are populated and HSN codes match the GST tariff using Get HSN. Ensure auto-calculated values and Section 8A ITC reconcile with internal records. Before proceeding, confirm that no mandatory fields are missing. GSTN will reject the proceed step if validations fail. See the error handling guide for common validation errors.
GSTN errors can occur due to portal downtime, session expiry, or validation failures. The GSTR-9 API returns standardized error codes. Retry transient errors (5xx, timeouts) with exponential backoff. For validation errors (4xx), parse the error details and correct the request payload. Refer to the error handling guide for error code mappings and recommended retry strategies.