This document provides a comprehensive overview of the GSTR-1 JSON data format, its architectural requirements, and the strict validation rules necessary for successful submission to the GSTN portal. Since the GSTN has not published an official JSON schema, this specification has been reverse-engineered based on validity testing against the official GST portal, public APIs, and the "GST Offline Tool" documentation.
GSTR-1 is a mandatory return for all GST-registered businesses in India, used to report details of all outward supplies (sales).
- Monthly: For businesses with an aggregate turnover exceeding ₹1.5 crore.
- Quarterly (QRMP Scheme): For smaller businesses with turnover up to ₹5 crore.
At a high level, only a few sections are required for every filing. All others depend on the nature of transactions during the tax period.
- Mandatory (Tables 1, 2, 12, 13): GSTIN details, Financial Period, HSN Summary, and Documents Issued.
- Conditional (Table 3): Turnover summary (
gt,cur_gt). Mandatory only for FY 2017-18; omit for others. - Conditional (Tables 4 – 11, 14, 15): Required only if there are relevant transactions (e.g., B2B sales, exports, or amendments).
The following table maps common JSON keys to the official GSTR-1 table numbers. Note that Table 11B sections (atadj, etc.) are included to ensure schema compatibility for taxpayers reporting amendments to tax liability on advances.
| JSON Key | GST Table | Description | Required Status |
|---|---|---|---|
gstin, fp |
Tables 1 & 2 | Taxpayer Identification & Return Period. | MANDATORY |
gt |
Table 3 | Gross Turnover: Aggregate turnover in the preceding financial year (FY 2017-18 only). | Conditional |
cur_gt |
Table 3 | Current Gross Turnover: Cumulative aggregate turnover in the current financial year (FY 2017-18 only). | Conditional |
b2b |
Table 4 | Taxable outward supplies to registered persons. | Conditional |
b2cl |
Table 5 | B2C Large: Inter-state supplies to unregistered persons where Invoice Value > ₹1 lakh (post-Aug 2024) or > ₹2.5 lakh (pre-Aug 2024). | Conditional |
exp |
Table 6 | Exports (Overseas), including Deemed Exports and SEZ supplies. | Conditional |
b2cs |
Table 7 | B2C Small: Intra-state supplies or Inter-state < ₹1 lakh. | Conditional |
nil |
Table 8 | Nil-rated, exempted, and non-GST outward supplies. | Conditional |
b2ba, b2cla, expa |
Table 9 | Amendments to previous period B2B, B2CL, or EXP invoices. | Conditional |
cdnr, cdnur |
Table 9B | Credit and Debit Notes. | Conditional |
b2csa, cdnra |
Table 10 | Amendments to B2CS and Credit/Debit Notes. | Conditional |
at, txpd |
Table 11A | Advances received and adjusted. | Conditional |
atadj, atadja, ata, txpda |
Table 11B | Amendment of advances received and adjusted. | Conditional |
hsn |
Table 12 | HSN-wise summary of outward supplies (bifurcated into B2B and B2C segments). | MANDATORY |
doc_issue |
Table 13 | Summary of documents issued (Invoices, Credit Notes, etc.). | MANDATORY |
eco, ecoa, ecob2b, ecob2c, ecourp2b, ecourp2c, ecoab2b, ecoab2c, ecoaurp2b, ecoaurp2c |
Tables 14 & 15 | Supplies made through E-commerce Operators (Liable to collect TCS u/s 52 or pay tax u/s 9(5)). | Conditional |
The GSTN portal generates internal fields during processing. User-generated JSON files MUST NOT include these fields, as the upload will be rejected with a "Technical Error":
chksum: Hashes generated for integrity check.flag: Status indicators (e.g., "U", "N", "D").updby,cflag,cfs,fil_dt: Internal processing metadata.
The JSON standard enforces different nesting rules depending on the section:
- Nesting Rule (B2B, B2CL, CDNR): Tax and rate details must be wrapped in an
itm_detobject within theitemsarray. - Flatness Rule (EXP, B2CS): Item details (rate, taxable value, tax amounts) are flat siblings under the items array or the main object.
- Leading Property: The key
hsn_sc(SAC/HSN code) must be the first property in every HSN entry. - Mandatory Fields:
hsn_sc,desc,uqc,qty,rt,txval, andnum. - Bifurcation: Separate lists for
hsn_b2bandhsn_b2care required. - Services (SAC): For codes starting with
99(Services),qtymust be set to0or0.0whenuqcisNAorOTHto avoid validation errors on the GST portal. - Length Validation: Minimum 6 digits for taxpayers with Annual Aggregate Turnover (AATO) > ₹5 crore.
- Strings: Identifiers (
inum,ctin,gstin,pos) and dates (idt) must be double-quoted strings. - Numbers: Taxable values and tax amounts must be numeric (integers or decimals).
- Dates: Strictly
DD-MM-YYYY. - Period (
fp): StrictlyMMYYYY(e.g.,122025for Dec 2025).