Vendor Return Filing Status API

• HTTP Method	POST
  URL	https://my.gstzen.in/api/vendor-return-filing-status/
  Content Type	application/json
  Authentication Type	Token

• Headers

  Token

  f15da0e8-e4d0-11ed-b5ea-0242ac120002

  You can find your GSTZen API key at bottom of your profile page.

• Request Payload

  {
    "gstin": "27AAAAA0000A1Z5",
    "period": "Yearly",
    "year": 2025
  }

• Example Request (cURL)

  curl -X POST \
    "https://my.gstzen.in/api/vendor-return-filing-status/" \
    -H "Content-Type: application/json" \
    -H "Authorization: Token <YOUR_API_TOKEN>" \
    -d '{
      "gstin": "27AAAAA0000A1Z5",
      "period": "Yearly",
      "year": 2025
    }'

  Replace <YOUR_API_TOKEN> with your GSTZen API key from the bottom of your profile page.

• Response Payload (Success)

  {
    "status": 1,
    "message": "Data retrieved successfully from portal",
    "period": "Yearly",
    "year": 2025,
    "validation": {
      "num_valid_gstins": 2,
      "num_invalid_gstins": 0,
      "errors": []
    },
    "data": [
      {
        "gstin": {
          "number": "27AAAAA0000A1Z5",
          "name": "Company Name",
          "registration_date": "2017-07-01",
          "cancellation_date": null
        },
        "financial_years": {
          "2024-25": {
            "gstr1_list": [
              {
                "gstin": "27AAAAA0000A1Z5",
                "return_type": 1,
                "return_type_name": "GSTR1",
                "return_period": "2024-04-01",
                "status": "Filed",
                "mode_of_filing": "ONLINE",
                "date_of_filing": "2024-04-20",
                "acknowledgement_number": "ARN123456"
              }
            ],
            "gstr3b_list": [
              {
                "gstin": "27AAAAA0000A1Z5",
                "return_type": 2,
                "return_type_name": "GSTR3B",
                "return_period": "2024-04-01",
                "status": "Filed",
                "mode_of_filing": "ONLINE",
                "date_of_filing": "2024-04-22",
                "acknowledgement_number": "ARN123457"
              }
            ]
          }
        }
      }
    ]
  }

  Response Fields:

  • data: Array of filing status data for each GSTIN
  • validation: Summary of GSTIN validation results

• Error Responses

  • Insufficient Access (HTTP 403)

    {
      "status": 0,
      "message": "Your GSTZen account does not have valid subscription to Vendor Return Filing Status API. Please contact GSTZen support for further assistance. CODE: 40100 - No valid subscription"
    }

  • Validation Error (HTTP 400)

    {
      "status": 0,
      "message": "'gstin' field is required (GSTIN number)"
    }

• Request Schema

  {
    "gstin": "string (required)",
    "period": "string (required, enum: ['Yearly', 'Monthly'])",
    "year": "integer (required, e.g., 2025)"
  }

  Fields:

  • gstin: Single GSTIN number to check
  • period: Filing period type - "Yearly" or "Monthly"
  • year: Financial year (integer, e.g., 2025 for FY 2024-25)

• Response Schema

  {
    "status": "integer (1 = success, 0 = error)",
    "message": "string",
    "period": "string",
    "year": "integer",
    "validation": {
      "num_valid_gstins": "integer",
      "num_invalid_gstins": "integer",
      "errors": "array of objects"
    },
    "data": [
      {
        "gstin": {
          "number": "string",
          "name": "string",
          "registration_date": "string (ISO date or null)",
          "cancellation_date": "string (ISO date or null)"
        },
        "financial_years": {
          "YYYY-YY": {
            "gstr1_list": [
              {
                "gstin": "string",
                "return_type": "integer",
                "return_type_name": "string",
                "return_period": "string (ISO date)",
                "status": "string",
                "mode_of_filing": "string",
                "date_of_filing": "string (ISO date or null)",
                "acknowledgement_number": "string"
              }
            ],
            "gstr3b_list": [
              {
                "gstin": "string",
                "return_type": "integer",
                "return_type_name": "string",
                "return_period": "string (ISO date)",
                "status": "string",
                "mode_of_filing": "string",
                "date_of_filing": "string (ISO date or null)",
                "acknowledgement_number": "string"
              }
            ]
          }
        }
      }
    ]
  }

  Key Fields:

  • status: 1 for success, 0 for error
  • data: Array of filing status objects, one per GSTIN
  • validation: Summary of GSTIN validation results
  • financial_years: Key format is "YYYY-YY" (e.g., "2024-25")