File GSTR-9

Workflow Overview

The GSTR-9 filing process follows this sequence:

Authenticate - Create a taxpayer session (valid for 6 hours)
Get Auto-Calculated Details - Fetch pre-calculated data from GST Department
Pull HSN Summary - Get GSTR-1 HSN data for Table 17
Save GSTR-9 - Upload your annual return data for validation
Check Status - Verify the save operation completed successfully
Get GSTR-9 Details - Retrieve saved data required for filing
Proceed to File - Mark the return ready for filing
Check Status - Verify proceed operation completed
Generate EVC OTP - Get Electronic Verification Code OTP
File GSTR-9 - Submit the annual return with OTP verification

Before you begin:

GSTR-1 and GSTR-3B for all months of the financial year must be filed
Ensure your Taxpayer access token is valid (6-hour validity) throughout the filing process
The financial year format is FY YYYY-YY (e.g., FY 2023-24)

GSTR-9 is an annual return and once filed, it cannot be revised. Review all data carefully before proceeding to file.

Authenticate and Get Taxpayer Session

Before filing GSTR-9, you must authenticate and create a taxpayer session. Follow the steps in the Generate Taxpayer Session recipe to obtain a Taxpayer access token.This access token is required for all GST Taxpayer API calls and is valid for 6 hours.

Get GSTR-9 Auto-Calculated Details

Fetch the auto-calculated table details in GSTR-9 as computed by the GST Department using the GSTR-9 Auto Calculated Details endpoint.This data is pre-populated based on your GSTR-1 and GSTR-3B filings and serves as the baseline for your annual return.

cURL Request

curl --request GET \
  --url 'https://api.sandbox.co.in/gst/compliance/tax-payer/gstrs/gstr-9/auto-calculated?financial_year=FY%202023-24' \
  --header 'authorization: {taxpayer-access-token}' \
  --header 'x-api-key: xxxxxxxxxxxxx' \
  --header 'x-api-version: 1.0.0'

When successful, you’ll receive:

table4 - Details of outward supplies (B2B, B2C, exports, etc.)
table5 - Details of exempt, nil-rated, and non-GST supplies
table6 - Input Tax Credit (ITC) details
table8 - ITC reconciliation details
table9 - Tax paid details
chksum - Checksums for each table

Review these values and use them as reference when preparing your GSTR-9 data.

Get GSTR-1 HSN Summary

Pull the HSN summary for outward supplies from your GSTR-1 filings using the GSTR-1 HSN Summary endpoint. This data is used to populate Table 17 in GSTR-9.Call this endpoint for each month of the financial year to compile the complete HSN summary.

cURL Request

curl --request GET \
  --url 'https://api.sandbox.co.in/gst/compliance/tax-payer/gstrs/gstr-1/hsn/2024/12' \
  --header 'authorization: {taxpayer-access-token}' \
  --header 'x-api-key: xxxxxxxxxxxxx' \
  --header 'x-api-version: 1.0.0'

When successful, you’ll receive:

hsn.data - Array of HSN codes with taxable value, quantity, and tax amounts
hsn_sc - HSN/SAC code
txval - Taxable value
iamt, camt, samt, csamt - Tax amounts (IGST, CGST, SGST, Cess)

Aggregate the HSN data from all 12 months of the financial year to prepare the Table 17 data for your GSTR-9 submission.

Save GSTR-9

Save your GSTR-9 data using the Save GSTR-9 endpoint. This includes outward supplies, input tax credits (ITC), and tax payments for the financial year.

cURL Request

curl --request POST \
  --url 'https://api.sandbox.co.in/gst/compliance/tax-payer/gstrs/gstr-9/save?financial_year=FY%202023-24' \
  --header 'authorization: {taxpayer-access-token}' \
  --header 'x-api-key: xxxxxxxxxxxxx' \
  --header 'x-api-version: 1.0.0' \
  --header 'Content-Type: application/json' \
  --data '{
  "gstin": "29AAACQ3770E000",
  "fp": "032024",
  "table4": {
    "b2c": { "txval": 1000, "iamt": 20, "camt": 20, "samt": 20, "csamt": 0 },
    "b2b": { "txval": 1000, "iamt": 20, "camt": 20, "samt": 20, "csamt": 0 }
  },
  "table5": {
    "zero_rtd": { "txval": 0 },
    "exmt": { "txval": 0 },
    "nil": { "txval": 0 }
  },
  "table6": {
    "supp_non_rchrg": [{ "itc_typ": "ip", "iamt": 20, "camt": 20, "samt": 20, "csamt": 0 }],
    "itc_clmd": { "iamt": 20, "camt": 20, "samt": 20, "csamt": 0 }
  },
  "table7": {
    "rule37": { "iamt": 0, "camt": 0, "samt": 0, "csamt": 0 }
  },
  "table8": {
    "itc_inwd_supp": { "iamt": 20, "camt": 20, "samt": 20, "csamt": 0 }
  },
  "table9": {
    "iamt": { "txpyble": 1000 },
    "camt": { "txpyble": 1000 },
    "samt": { "txpyble": 1000 }
  },
  "table17": {
    "items": [
      { "hsn_sc": "998232", "txval": 10000, "isconcesstional": "N", "rt": 18, "iamt": 0, "camt": 900, "samt": 900, "csamt": 0 }
    ]
  },
  "table18": {
    "items": [
      { "hsn_sc": "1203", "uqc": "BAL", "qty": 1, "txval": 10000, "isconcesstional": "N", "rt": 5, "iamt": 0, "camt": 250, "samt": 250, "csamt": 0 }
    ]
  }
}'

When successful, you’ll receive:

reference_id - Use this to check the save status

Save this reference_id for the next step.

Check Save Status

Check the status of the save operation using the GST Return Status endpoint with the reference_id from the previous step.

cURL Request

curl --request GET \
  --url 'https://api.sandbox.co.in/gst/compliance/tax-payer/gstrs/2024/12/status?reference_id=3f0b7b96-2c56-4e34-a025-03c3577a8468' \
  --header 'authorization: {taxpayer-access-token}' \
  --header 'x-api-key: xxxxxxxxxxxxx' \
  --header 'x-api-version: 1.0.0'

Poll this endpoint every 10-15 seconds until status_cd is P (Processed).When successful, the response includes:

status_cd - P indicates processing complete
action - The action that was processed (SAVE)

If the status shows validation errors, fix the data and save again before proceeding.

Get GSTR-9 Details

Fetch the saved GSTR-9 details using the GSTR-9 Details endpoint. This data is required for the File GSTR-9 API to complete the filing.

cURL Request

curl --request GET \
  --url 'https://api.sandbox.co.in/gst/compliance/tax-payer/gstrs/gstr-9?financial_year=FY%202023-24' \
  --header 'authorization: {taxpayer-access-token}' \
  --header 'x-api-key: xxxxxxxxxxxxx' \
  --header 'x-api-version: 1.0.0'

When successful, you’ll receive the complete GSTR-9 data with checksums for all tables. Save this entire response as it needs to be passed in the File GSTR-9 request.

Proceed to File

Mark the return as ready for filing using the Proceed to File endpoint. After this step, EVC OTP can be generated for filing.

cURL Request

curl --request POST \
  --url 'https://api.sandbox.co.in/gst/compliance/tax-payer/gstrs/gstr-9/2024/03/proceed' \
  --header 'authorization: {taxpayer-access-token}' \
  --header 'x-api-key: xxxxxxxxxxxxx' \
  --header 'x-api-version: 1.0.0' \
  --header 'Content-Type: application/json' \
  --data '{
  "gstin": "29AAACQ3770E000",
  "ret_period": "032024"
}'

When successful, you’ll receive:

reference_id - Use this to check the proceed status

Save this reference_id for the next step.

Check Proceed Status

Verify the proceed operation completed successfully using the GST Return Status endpoint.

cURL Request

curl --request GET \
  --url 'https://api.sandbox.co.in/gst/compliance/tax-payer/gstrs/2024/12/status?reference_id=897c98eb-7877-4252-934d-46cb3a86c51a' \
  --header 'authorization: {taxpayer-access-token}' \
  --header 'x-api-key: xxxxxxxxxxxxx' \
  --header 'x-api-version: 1.0.0'

Poll until status_cd is P (Processed). Once complete, the return is ready for filing.

Generate EVC OTP

Generate an EVC (Electronic Verification Code) OTP using the Generate EVC OTP endpoint.Provide the PAN of the authorized signatory associated with the taxpayer’s GST registration.

cURL Request

curl --request POST \
  --url 'https://api.sandbox.co.in/gst/compliance/tax-payer/evc/otp?gstr=gstr-9' \
  --header 'authorization: {taxpayer-access-token}' \
  --header 'x-api-key: xxxxxxxxxxxxx' \
  --header 'x-api-version: 1.0.0' \
  --header 'Content-Type: application/json' \
  --data '{
  "pan": "AAACQ3770E"
}'

The OTP will be sent to the registered mobile number or email of the authorized signatory. You’ll need this OTP in the next step.

File your GSTR-9 using the File GSTR-9 endpoint.Include the financial year, PAN, and EVC OTP as query parameters. Pass the complete GSTR-9 details (obtained in Step 6) in the request body.

cURL Request

curl --request POST \
  --url 'https://api.sandbox.co.in/gst/compliance/tax-payer/gstrs/gstr-9/file?financial_year=FY%202023-24&pan=AAACQ3770E&otp=575757' \
  --header 'authorization: {taxpayer-access-token}' \
  --header 'x-api-key: xxxxxxxxxxxxx' \
  --header 'x-api-version: 1.0.0' \
  --header 'Content-Type: application/json' \
  --data '{
  "gstin": "29AAACQ3770E000",
  "isnil": "N",
  "fp": "032024",
  "table4": { ... },
  "table5": { ... },
  "table6": { ... },
  "table7": { ... },
  "table8": { ... },
  "table9": { ... },
  "table10": { ... },
  "table14": { ... },
  "table15": { ... },
  "table16": { ... },
  "table17": { ... },
  "table18": { ... }
}'

Pass the complete GSTR-9 data from the Get GSTR-9 Details response (Step 6) in the request body. This includes all tables with their checksums.

When successful, you’ll receive:

ack_num - Acknowledgment number confirming successful filing

Your GSTR-9 annual return has been successfully filed.

Authentication

GSTR-1

GSTR-3B

GSTR-9

E-Invoice

File GSTR-9

Workflow Overview

Authenticate and Get Taxpayer Session

Get GSTR-9 Auto-Calculated Details

Get GSTR-1 HSN Summary

Save GSTR-9

Check Save Status

Get GSTR-9 Details

Proceed to File

Check Proceed Status

Generate EVC OTP

File GSTR-9

Authentication

GSTR-1

GSTR-3B

GSTR-9

E-Invoice

​Workflow Overview

Authenticate and Get Taxpayer Session

Get GSTR-9 Auto-Calculated Details

Get GSTR-1 HSN Summary

Save GSTR-9

Check Save Status

Get GSTR-9 Details

Proceed to File

Check Proceed Status

Generate EVC OTP

File GSTR-9

Workflow Overview