GST Returns

See if a business actually files — period by period.

POST/v1/gst/returns

₹1.00

per successful call · incl. GST · failed calls ₹0

Need this plus more? Add it to a Business360 call →GST returns is a Business360 module. Combine it with others and pay only for what succeeds, capped at ₹10.00.

What it does

Returns GSTR-1 and GSTR-3B filing status for the last 12 return periods, with filing dates and a summary of missed or late periods.

Input: GSTIN
Output: GSTR-1 / GSTR-3B filing status, last 12 periods

Use cases

Supplier risk scoring
ITC eligibility checks
Lending pre-screens

Request

POST /v1/gst/returns

curl https://api.apiserver.in/v1/gst/returns \
  -H "Authorization: Bearer as_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"gstin":"24AAHCS9156P1ZL"}'

const res = await fetch("https://api.apiserver.in/v1/gst/returns", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.APISERVER_KEY ?? "as_test_YOUR_KEY"}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "gstin": "24AAHCS9156P1ZL"
  }),
});

const { success, data, meta, error } = await res.json();
console.log(meta.charged, meta.amount_inr); // failed calls are never charged

import os, requests

res = requests.post(
    "https://api.apiserver.in/v1/gst/returns",
    headers={
        "Authorization": f"Bearer {os.getenv('APISERVER_KEY', 'as_test_YOUR_KEY')}",
    },
    json={
        "gstin": "24AAHCS9156P1ZL",
    },
    timeout=10,
)
body = res.json()
print(body["meta"]["charged"], body["meta"]["amount_inr"])

<?php
$ch = curl_init('https://api.apiserver.in/v1/gst/returns');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . (getenv('APISERVER_KEY') ?: 'as_test_YOUR_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'gstin' => '24AAHCS9156P1ZL',
    ]),
]);
$body = json_decode(curl_exec($ch), true);
echo $body['meta']['charged'] ? 'charged' : 'not charged';

Request body fields
Field	Type	Description
gstinrequired	string	15-character GSTIN. Validated locally (state code, embedded PAN, mod-36 checksum) before any source is called.
periods	integer	How many recent return periods to include (1–12).

Response

Sample response for a fictional sandbox entity. Click any key to copy its JSON path.

{  : true,  : "as_req_01J9X2K7R8M4V6T2Q9W3E5Y1ZB",  : "gst.returns",  : "2026-10-01",  : {    : "24AAHCS9156P1ZL",    : "monthly",    : [      {        : "2026-08",        : {          : "filed",          : "2026-09-10",          : "2026-09-11"        },        : {          : "not_filed",          : null,          : "2026-09-20"        }      },      {        : "2026-07",        : {          : "filed",          : "2026-08-10",          : "2026-08-11"        },        : {          : "not_filed",          : null,          : "2026-08-20"        }      },      {        : "2026-06",        : {          : "filed",          : "2026-07-10",          : "2026-07-11"        },        : {          : "filed",          : "2026-07-18",          : "2026-07-20"        }      },      {        : "2026-05",        : {          : "filed",          : "2026-06-10",          : "2026-06-11"        },        : {          : "filed",          : "2026-06-18",          : "2026-06-20"        }      },      {        : "2026-04",        : {          : "filed",          : "2026-05-10",          : "2026-05-11"        },        : {          : "filed",          : "2026-05-18",          : "2026-05-20"        }      },      {        : "2026-03",        : {          : "filed",          : "2026-04-10",          : "2026-04-11"        },        : {          : "filed",          : "2026-04-18",          : "2026-04-20"        }      },      {        : "2026-02",        : {          : "filed",          : "2026-03-10",          : "2026-03-11"        },        : {          : "late",          : "2026-03-27",          : "2026-03-20"        }      },      {        : "2026-01",        : {          : "filed",          : "2026-02-10",          : "2026-02-11"        },        : {          : "filed",          : "2026-02-18",          : "2026-02-20"        }      },      {        : "2025-12",        : {          : "filed",          : "2026-01-10",          : "2026-01-11"        },        : {          : "filed",          : "2026-01-18",          : "2026-01-20"        }      },      {        : "2025-11",        : {          : "filed",          : "2025-12-10",          : "2025-12-11"        },        : {          : "filed",          : "2025-12-18",          : "2025-12-20"        }      },      {        : "2025-10",        : {          : "filed",          : "2025-11-10",          : "2025-11-11"        },        : {          : "filed",          : "2025-11-18",          : "2025-11-20"        }      },      {        : "2025-09",        : {          : "filed",          : "2025-10-10",          : "2025-10-11"        },        : {          : "filed",          : "2025-10-18",          : "2025-10-20"        }      }    ],    : {      : 12,      : 21,      : 1,      : 2,      : "2026-06"    }  },  : {    : true,    : 1,    : 341,    : "live",    : 1,    : "2026-10-03T09:12:00+05:30",    : "live"  }}

Field dictionary — data

Response data fields
Field	Type	Description
gstin	string	—
filing_frequency	"monthly" \| "quarterly"	Return filing frequency
periods	object[]	Most recent first
↳period	string	Return period, YYYY-MM
↳gstr1	object	—
↳status	"filed" \| "late" \| "not_filed"	—
↳filed_on	string \| null	—
↳due_date	string	—
↳gstr3b	object	—
↳status	"filed" \| "late" \| "not_filed"	—
↳filed_on	string \| null	—
↳due_date	string	—
summary	object	—
↳periods	integer	—
↳filed_on_time	integer	—
↳filed_late	integer	—
↳not_filed	integer	—
↳last_filed_period	string \| null	—

Errors

Every error uses the same envelope and is billed ₹0 — `meta.charged` is always false.

Errors this endpoint can return
HTTP	Code	What it means	Retry	Billed
400	VALIDATION_FAILED	Something in the request isn't in the right shape — usually an ID with a typo or a missing field.	no	₹0
401	AUTH_INVALID_KEY	We couldn't find a valid API key on this request.	no	₹0
402	WALLET_INSUFFICIENT_BALANCE	Your wallet doesn't have enough for this call, so we didn't run it.	no	₹0
404	RECORD_NOT_FOUND	The source has no record for this ID.	no	₹0
429	RATE_LIMITED	You sent requests faster than your key's limit.	yes	₹0
503	PROVIDER_UNAVAILABLE	All upstream sources for this check were down, even after fallback.	yes	₹0
504	PROVIDER_TIMEOUT	The upstream source took too long to answer.	yes	₹0

₹1.00

GST Returns · incl. GST · failed calls ₹0

Get early access