GSTR-1 JSON Structure Explained - Complete Field Guide 2026

Understanding GSTR-1 JSON File Structure

GSTR-1 JSON files follow a standardized structure defined by GSTN (Goods and Services Tax Network). Understanding this structure is crucial for developers building GST tools, businesses automating data processing, and accountants validating return data.

This comprehensive guide explains every section and field in GSTR-1 JSON format with practical examples.

Top-Level GSTR-1 JSON Structure

A GSTR-1 JSON file has this basic structure:

{
  "gstin": "29AABCT1332L000",
  "fp": "032024",
  "gt": 1234567.89,
  "cur_gt": 987654.32,
  "b2b": [...],
  "b2cl": [...],
  "b2cs": [...],
  "cdnr": [...],
  "cdnur": [...],
  "exp": [...],
  "at": [...],
  "atadj": [...],
  "exemp": [...],
  "hsn": [...],
  "docs": {...},
  "txpd": [...]
}

Root Fields Explained

Field	Description	Example
`gstin`	Your 15-digit GSTIN	”29AABCT1332L000”
`fp`	Filing period (MMYYYY)	“032024” for March 2024
`gt`	Gross turnover for the period	1234567.89
`cur_gt`	Cumulative turnover for FY	9876543.21

B2B Section - Business to Business Invoices

The B2B section contains all invoices issued to registered GST taxpayers.

B2B Structure

"b2b": [
  {
    "ctin": "29AABCU1332L000",
    "cfs": "Y",
    "cfs3b": "032024",
    "inv": [
      {
        "inum": "INV001",
        "idt": "01-03-2024",
        "val": 100000,
        "pos": "29",
        "rchrg": "N",
        "etin": "",
        "inv_typ": "R",
        "itms": [
          {
            "num": 1,
            "itm_det": {
              "rt": 18,
              "txval": 84745.76,
              "iamt": 0,
              "camt": 7627.12,
              "samt": 7627.12,
              "csamt": 0
            }
          }
        ]
      }
    ]
  }
]

B2B Field Definitions

Customer Level:

ctin - Customer’s GSTIN
cfs - Whether filed in 3B (Y/N)
cfs3b - Period when filed in GSTR-3B

Invoice Level:

inum - Invoice number
idt - Invoice date (DD-MM-YYYY)
val - Total invoice value including taxes
pos - Place of supply (state code)
rchrg - Reverse charge (Y/N)
etin - E-commerce GSTIN (if applicable)
inv_typ - Invoice type (R=Regular, SEWP=SEZ with payment, etc.)

Item Level:

num - Item serial number
rt - GST rate (%)
txval - Taxable value (before tax)
iamt - IGST amount
camt - CGST amount
samt - SGST amount
csamt - Cess amount

B2CL Section - B2C Large Invoices

B2CL includes B2C invoices where invoice value exceeds ₹2.5 lakhs (₹2,50,000).

B2CL Structure

"b2cl": [
  {
    "pos": "33",
    "inv": [
      {
        "inum": "INV501",
        "idt": "05-03-2024",
        "val": 295000,
        "etin": "",
        "itms": [
          {
            "num": 1,
            "itm_det": {
              "rt": 12,
              "txval": 263392.86,
              "iamt": 31607.14,
              "csamt": 0
            }
          }
        ]
      }
    ]
  }
]

Key Differences from B2B

No ctin field (customer unregistered)
Only IGST applicable (inter-state supply)
Grouped by pos (place of supply)

B2CS Section - B2C Small Invoices

B2CS contains consolidated B2C supplies where invoice value is up to ₹2.5 lakhs.

B2CS Structure

"b2cs": [
  {
    "sply_ty": "INTRA",
    "pos": "29",
    "typ": "OE",
    "rt": 5,
    "txval": 500000,
    "iamt": 0,
    "camt": 12500,
    "samt": 12500,
    "csamt": 0
  }
]

B2CS Field Definitions

sply_ty - Supply type (INTRA/INTER)
pos - Place of supply
typ - Type of supply (OE=Outward, etc.)
rt - Tax rate
txval - Total taxable value (consolidated)
Tax amounts (iamt/camt/samt/csamt)

Note: B2CS is consolidated data, not individual invoices.

CDNR Section - Credit/Debit Notes (Registered)

Credit and debit notes issued to registered customers.

CDNR Structure

"cdnr": [
  {
    "ctin": "29AABCU1332L000",
    "nt": [
      {
        "ntty": "C",
        "nt_num": "CDN001",
        "nt_dt": "10-03-2024",
        "rsn": "Sales Return",
        "p_gst": "Y",
        "inum": "INV001",
        "idt": "01-03-2024",
        "val": 10000,
        "itms": [
          {
            "num": 1,
            "itm_det": {
              "rt": 18,
              "txval": 8474.58,
              "iamt": 0,
              "camt": 762.71,
              "samt": 762.71,
              "csamt": 0
            }
          }
        ]
      }
    ]
  }
]

CDNR Fields

ntty - Note type (C=Credit, D=Debit)
nt_num - Note number
nt_dt - Note date
rsn - Reason for note
p_gst - Pre-GST (Y/N)
inum - Original invoice number
idt - Original invoice date
val - Note value

EXP Section - Export Invoices

Export of goods and services.

EXP Structure

"exp": [
  {
    "ex_tp": "WPAY",
    "inv": [
      {
        "inum": "EXP001",
        "idt": "15-03-2024",
        "val": 1000000,
        "sbpcode": "INBLR4",
        "sbnum": "12345",
        "sbdt": "14-03-2024",
        "itms": [
          {
            "rt": 0,
            "txval": 1000000,
            "iamt": 0
          }
        ]
      }
    ]
  }
]

Export Fields

ex_tp - Export type (WPAY=With payment, WOPAY=Without payment)
sbpcode - Shipping bill port code
sbnum - Shipping bill number
sbdt - Shipping bill date

HSN Section - HSN Summary

Summary of outward supplies by HSN/SAC code.

HSN Structure

"hsn": {
  "data": [
    {
      "num": 1,
      "hsn_sc": "8471",
      "desc": "Computers",
      "uqc": "NOS",
      "qty": 100,
      "val": 5000000,
      "txval": 4237288.14,
      "iamt": 0,
      "camt": 381355.93,
      "samt": 381355.93,
      "csamt": 0
    }
  ]
}

HSN Fields

hsn_sc - HSN/SAC code (4/6/8 digits)
desc - Description of goods/services
uqc - Unit of quantity (NOS, KGS, etc.)
qty - Total quantity
val - Total value including tax
txval - Taxable value
Tax amounts

DOCS Section - Document Summary

Summary of all documents issued during the period.

DOCS Structure

"docs": {
  "doc_det": [
    {
      "doc_num": 1,
      "docs": {
        "num": 1,
        "from": "INV001",
        "to": "INV500",
        "totnum": 500,
        "cancel": 5,
        "net_issue": 495
      }
    }
  ]
}

Document Types

Invoices for outward supply
Invoices for inward supply (reverse charge)
Debit notes
Credit notes
Receipt voucher
Payment voucher
Refund voucher
Delivery challan for job work

Common GSTR-1 JSON Patterns

Multiple Items in Single Invoice

"itms": [
  {
    "num": 1,
    "itm_det": {"rt": 18, "txval": 50000, ...}
  },
  {
    "num": 2,
    "itm_det": {"rt": 12, "txval": 30000, ...}
  }
]

Inter-State Supply (IGST)

"itm_det": {
  "rt": 18,
  "txval": 100000,
  "iamt": 18000,  // Only IGST
  "camt": 0,
  "samt": 0,
  "csamt": 0
}

Intra-State Supply (CGST + SGST)

"itm_det": {
  "rt": 18,
  "txval": 100000,
  "iamt": 0,
  "camt": 9000,  // 9% CGST
  "samt": 9000,  // 9% SGST
  "csamt": 0
}

Parsing GSTR-1 JSON - Best Practices

1. Validate Structure First

Always check if required fields exist:

if (!json.gstin || !json.fp) {
  throw new Error("Invalid GSTR-1 JSON");
}

2. Handle Optional Sections

Not all sections will be present:

const b2bData = json.b2b || [];
const b2clData = json.b2cl || [];

3. Flatten Nested Data

For Excel conversion, flatten the nested structure:

json.b2b.forEach(entry => {
  entry.inv.forEach(invoice => {
    invoice.itms.forEach(item => {
      // Create row with customer, invoice, and item data
    });
  });
});

4. Calculate Totals

Sum up tax amounts for validation:

let totalIGST = items.reduce((sum, item) => 
  sum + item.itm_det.iamt, 0
);

Using Our Free Converter for GSTR-1 JSON

Instead of manually parsing GSTR-1 JSON structure, use our free converter tool that automatically:

✅ Validates JSON structure
✅ Extracts all B2B, B2CL, B2CS data
✅ Flattens nested invoice items
✅ Calculates summaries
✅ Generates formatted Excel file
✅ Handles large files (up to 50MB)

Convert GSTR-1 JSON to Excel now →

Developer API Integration Tips

If you’re integrating GSTR-1 JSON in your application:

Schema Validation - Use JSON Schema to validate structure
Error Handling - Handle missing or malformed sections gracefully
Performance - Stream large files instead of loading entirely in memory
Type Safety - Use TypeScript interfaces for GSTR-1 structure
Testing - Test with various JSON samples from different months

Frequently Asked Questions

What’s the difference between GSTR-1 and GSTR-2B JSON structure?

GSTR-1 contains your sales data (outward supplies) while GSTR-2B contains your purchase data (inward supplies). GSTR-2B has sections like b2b, cdn, isd, impg with different field names.

Why is my GSTR-1 JSON missing some sections?

Sections only appear if you have data for them. If you don’t have exports, the exp section won’t exist. This is normal.

Can I edit GSTR-1 JSON manually?

Not recommended. Any syntax error will make the file invalid. Always make corrections on the GST portal and re-download.

How do I validate GSTR-1 JSON structure?

Use online JSON validators or our converter tool which automatically validates the structure during processing.

What’s the maximum size of GSTR-1 JSON files?

Technically unlimited, but files over 50MB are rare. Our converter handles files up to 50MB efficiently.

Conclusion

Understanding GSTR-1 JSON structure is valuable for:

Developers building GST compliance tools
Accountants validating return data
Businesses automating reconciliation
Auditors analyzing sales patterns

Key Takeaways:

GSTR-1 JSON has multiple sections (B2B, B2CL, B2CS, etc.)
Each section has 2-3 levels of nesting
Tax amounts split by IGST/CGST/SGST based on supply type
HSN and DOCS sections provide summaries
Automated tools save hours of manual processing

For quick conversion without dealing with complex JSON structure, use our free GSTR-1 to Excel converter.

Related Articles: