Skip to main content

​
Workflow Overview

The GSTR-3B filing process follows this sequence:
  1. Authenticate - Create a taxpayer session (valid for 6 hours)
  2. Get GSTR-3B Details - Retrieve existing GSTR-3B data from the GST portal
  3. Save Data - Upload your GSTR-3B data to the GST portal for validation
  4. Get Ledger Balance - Check available cash and ITC credits
  5. Offset Liability - Allocate ITC and cash towards tax liability
  6. Get Updated Details - Retrieve GSTR-3B data with payment information
  7. Generate EVC OTP - Get Electronic Verification Code OTP
  8. File Return - Submit the return with OTP verification
Status Polling: Check the GST Return Status every 10-15 seconds after saving or offsetting liabilities. Processing typically completes within 1-2 minutes. If status shows validation errors, fix the data and save again before proceeding.
Prerequisites:
  • Ensure GSTR-1 is filed for the same return period before filing GSTR-3B. GSTR-3B must reconcile with GSTR-1.
  • Ensure you have sufficient balance in your cash or ITC ledger before offsetting liabilities.
  • Ensure your Taxpayer access token is valid (6-hour validity) throughout the filing process.
1

Authenticate and Get Taxpayer Session

Before filing GSTR-3B, 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.
2

Get GSTR-3B Details

Retrieve existing GSTR-3B data from the GST portal using the Get GSTR-3B Details endpoint to see what data is already saved for the return period.This allows you to review the current state of your return and identify what needs to be updated before saving your data.

cURL Request

curl --request GET \
  --url 'https://api.sandbox.co.in/gst/compliance/tax-payer/gstrs/gstr-3b/2023/12' \
  --header 'authorization: {taxpayer-access-token}' \
  --header 'x-api-key: xxxxxxxxxxxxxx' \
  --header 'x-api-version: 1.0.0'
The response will contain any existing GSTR-3B data for the return period. Use this information to prepare your complete return data in the next step.
3

Save GSTR-3B Data

Once you have the Taxpayer access token, save your GSTR-3B data using the Save GSTR-3B endpoint.Provide all summary details including outward supplies, inward supplies, ITC eligibility, and tax payment details. The data will be saved on the GST portal for review before filing.

cURL Request

curl --request POST \
  --url 'https://api.sandbox.co.in/gst/compliance/tax-payer/gstrs/gstr-3b/2023/12' \
  --header 'authorization: {taxpayer-access-token}' \
  --header 'x-api-key: xxxxxxxxxxxxxx' \
  --header 'x-api-version: 1.0.0' \
  --header 'Content-Type: application/json' \
  --data '{
  "ret_period": "122023",
  "inward_sup": {...},
  "sup_details": {...},
  "intr_ltfee": {...},
  "inter_sup": {...},
  "itc_elg": {...},
  "gstin": "29AAACQ3770E000"
}'
The response will include a reference_id which you can use to check the status of the save operation. You can optionally poll the GST Return Status endpoint using this reference ID.
4

Get Ledger Balance

Before offsetting liabilities, retrieve the current ledger balance using the Get Balance Ledger endpoint to understand available cash and ITC credits.

cURL Request

curl --request GET \
  --url 'https://api.sandbox.co.in/gst/compliance/tax-payer/ledgers/bal/2023/12' \
  --header 'authorization: {taxpayer-access-token}' \
  --header 'x-api-key: xxxxxxxxxxxxxx' \
  --header 'x-api-version: 1.0.0'
This will provide you with the current balance in cash ledger, ITC ledger, and liability ledger, which you’ll need to properly offset liabilities in the next step.
5

Offset Liability

Offset your tax liabilities using available ITC and cash ledger balance using the Offset Liability endpoint.Specify how you want to pay taxes from cash (pdcash) and how you want to utilize ITC credits (pditc) to offset your liabilities.

cURL Request

curl --request POST \
  --url 'https://api.sandbox.co.in/gst/compliance/tax-payer/gstrs/gstr-3b/2023/12/offset-liability' \
  --header 'authorization: {taxpayer-access-token}' \
  --header 'x-api-key: xxxxxxxxxxxxxx' \
  --header 'x-api-version: 1.0.0' \
  --header 'Content-Type: application/json' \
  --data '{
  "pdcash": [...],
  "pditc": {...}
}'
After offsetting liabilities, you need to retrieve the updated GSTR-3B details that include the payment information.
6

Get Updated GSTR-3B Details

After offsetting liabilities, retrieve the updated GSTR-3B details using the Get GSTR-3B Details endpoint to obtain the complete return data including tax payment details (tx_pmt) that are required for filing.This endpoint returns the GSTR-3B data with updated payment information reflecting the liability offset you performed in the previous step.

cURL Request

curl --request GET \
  --url 'https://api.sandbox.co.in/gst/compliance/tax-payer/gstrs/gstr-3b/2023/12' \
  --header 'authorization: {taxpayer-access-token}' \
  --header 'x-api-key: xxxxxxxxxxxxxx' \
  --header 'x-api-version: 1.0.0'
The response will contain the complete GSTR-3B data including the tx_pmt (tax payment) section with offset details. Extract this data as it is required for the filing request in the next step.
7

Generate EVC OTP

To file GSTR-3B, you need to generate an EVC (Electronic Verification Code) OTP using the Generate EVC OTP endpoint.Provide the PAN (Permanent Account Number) associated with the taxpayer’s GST registration. The OTP will be sent to the registered mobile number or email.

cURL Request

curl --request POST \
  --url 'https://api.sandbox.co.in/gst/compliance/tax-payer/evc/otp?gstr=gstr-3b' \
  --header 'authorization: {taxpayer-access-token}' \
  --header 'x-api-key: xxxxxxxxxxxxxx' \
  --header 'x-api-version: 1.0.0' \
  --header 'Content-Type: application/json' \
  --data '{
  "pan": "ABCCQ3123E"
}'
The OTP will be sent to the registered contact details. You’ll need this OTP in the next step to complete the filing.
8

File GSTR-3B

Once you have the EVC OTP and have retrieved the updated GSTR-3B details (including payment information), file your GSTR-3B using the File GSTR-3B endpoint.Include the PAN and OTP as query parameters, along with the complete GSTR-3B data including all sections and tax payment details in the request body.

cURL Request

curl --request POST \
  --url 'https://api.sandbox.co.in/gst/compliance/tax-payer/gstrs/gstr-3b/2023/12/file?pan=AAACJ3770E&otp=123456' \
  --header 'authorization: {taxpayer-access-token}' \
  --header 'x-api-key: xxxxxxxxxxxxxx' \
  --header 'x-api-version: 1.0.0' \
  --header 'Content-Type: application/json' \
  --data '{
  "ret_period": "122023",
  "inward_sup": {...},
  "tx_pmt": {...},
  "sup_details": {...},
  "intr_ltfee": {...},
  "inter_sup": {...},
  "itc_elg": {...},
  "gstin": "29AAACQ3770E000"
}'
Upon successful filing, the response will confirm that GSTR-3B has been filed for the specified return period.