> ## 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.

# File GSTR-9

> GSTR-9 is an annual GST return summarizing a taxpayer's filings, including supplies, taxes paid, ITC, and adjustments for the financial year. This recipe guides you through the complete GSTR-9 filing workflow.

## Workflow Overview

The GSTR-9 filing process follows this sequence:

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

> [!NOTE]
>
> 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`)

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

## 1. 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**](https://developer.sandbox.co.in/recipes/gst/authentication/generate_tax_payer_session.md) recipe to obtain a **Taxpayer access token**.

This access token is required for all GST Taxpayer API calls and is valid for 6 hours.

## 2. 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**](https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/taxpayer/gstr-9/auto_calculated_details.md) 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**
>
> ```bash theme={null}
> 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.

## 3. Get GSTR-1 HSN Summary

Pull the HSN summary for outward supplies from your GSTR-1 filings using the [**GSTR-1 HSN Summary**](https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/taxpayer/gstr-1/documents/get_hsn.md) 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**
>
> ```bash theme={null}
> 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)

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

## 4. Save GSTR-9

Save your GSTR-9 data using the [**Save GSTR-9**](https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/taxpayer/gstr-9/save.md) endpoint. This includes outward supplies, input tax credits (ITC), and tax payments for the financial year.

> **cURL Request**
>
> ```bash theme={null}
> 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.

## 5. Check Save Status

Check the status of the save operation using the [**GST Return Status**](https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/taxpayer/common/gst_return_status.md) endpoint with the `reference_id` from the previous step.

> **cURL Request**
>
> ```bash theme={null}
> 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)

> [!WARNING]
>
> If the status shows validation errors, fix the data and save again before proceeding.

## 6. Get GSTR-9 Details

Fetch the saved GSTR-9 details using the [**GSTR-9 Details**](https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/taxpayer/gstr-9/gstr_9_details.md) endpoint. This data is required for the File GSTR-9 API to complete the filing.

> **cURL Request**
>
> ```bash theme={null}
> 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.

## 7. Proceed to File

Mark the return as ready for filing using the [**Proceed to File**](https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/taxpayer/gstr-9/proceed.md) endpoint. After this step, EVC OTP can be generated for filing.

> **cURL Request**
>
> ```bash theme={null}
> 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.

## 8. Check Proceed Status

Verify the proceed operation completed successfully using the [**GST Return Status**](https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/taxpayer/common/gst_return_status.md) endpoint.

> **cURL Request**
>
> ```bash theme={null}
> 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.

## 9. Generate EVC OTP

Generate an EVC (Electronic Verification Code) OTP using the [**Generate EVC OTP**](https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/taxpayer/authentication/generate_evc_otp.md) endpoint.

Provide the PAN of the authorized signatory associated with the taxpayer's GST registration.

> **cURL Request**
>
> ```bash theme={null}
> 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.

## 10. File GSTR-9

File your GSTR-9 using the [**File GSTR-9**](https://developer.sandbox.co.in/api-reference/gst/compliance/endpoints/taxpayer/gstr-9/file.md) 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**
>
> ```bash theme={null}
> 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": { ... }
> }'
> ```

> [!NOTE]
>
> 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.


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