A GSTR-1 JSON file is the structured data file the GST portal actually reads when you file your outward supply return; everything you see filled in on screen, or in an Excel working sheet before that, eventually has to be converted into this format before the portal will accept it. Most sellers only think about the JSON when an upload fails, which is the worst time to be learning its structure for the first time.
This guide breaks down what sections a GSTR-1 JSON file actually contains, why the portal uses this format instead of a plain spreadsheet, the errors that show up most often during upload or validation, and a short checklist to run before you upload.
Why the Portal Uses JSON, Not Excel or CSV
JSON (JavaScript Object Notation) can represent nested, variable-length data cleanly: one invoice can have one or many line items, each with its own HSN code, tax rate, and value, all within a single record. A flat spreadsheet forces every invoice line onto its own row and loses the invoice-level grouping that GSTR-1 needs. The portal's own offline utility, and most GST software including OneBooks GST, work internally with this nested structure and only expose you to a spreadsheet-like view on screen.
Anatomy of a GSTR-1 JSON File
A GSTR-1 JSON is organised into distinct sections, each corresponding to a table in the return. Not every section will be present if you have nothing to report in that category for the period.
| Section (JSON key) | What it contains |
|---|---|
| b2b | Invoices to registered buyers (GSTIN-to-GSTIN supplies), grouped by recipient GSTIN |
| b2cl | B2C large invoices: interstate supplies to unregistered buyers above the applicable invoice value threshold |
| b2cs | B2C small: all other unregistered-buyer supplies, summarised by state and tax rate rather than invoice-by-invoice |
| cdnr | Credit and debit notes issued against registered buyers |
| cdnur | Credit and debit notes issued against unregistered buyers, where applicable |
| exp | Export invoices, with or without payment of tax |
| hsn | HSN-wise summary of outward supplies for the period |
| doc_issue | Document summary: invoice, credit note, and debit note serial number ranges, including cancelled ones |
How to Generate a Valid GSTR-1 JSON
- Consolidate your sales for the period, including marketplace imports from Amazon, Flipkart, Meesho, or other channels, and direct invoices.
- Classify each transaction correctly as B2B, B2C large, or B2C small, since misclassification is the single largest source of downstream JSON errors (see our GSTR-1 B2B vs B2C guide for the classification rules).
- Reconcile document numbering so the doc_issue section reflects your actual invoice series, including any cancelled numbers.
- Generate the export using GSTR-1 automation, which produces a portal-ready JSON alongside CSV, Excel, and Tally XML exports.
- Validate the file against the portal's offline tool or upload it directly and review the validation summary before you finalise the return.
Common Upload and Validation Errors on the GST Portal
| Error category | Likely cause | Fix |
|---|---|---|
| Invalid GSTIN format | A B2B invoice recipient GSTIN has a typo, wrong checksum digit, or extra whitespace | Re-verify the GSTIN against the buyer's registration certificate or the GST portal's search tool and correct it before regenerating the JSON |
| Duplicate invoice number | Two invoices in the same financial year share a number, often from merging two sales channels with overlapping series | Use channel-prefixed invoice series, for example FK- for Flipkart and AMZ- for Amazon, to avoid collisions |
| Invoice value and B2C classification mismatch | An interstate unregistered invoice above the threshold was tagged as B2C small instead of B2C large | Re-run classification; verify the current B2C large threshold on www.gst.gov.in since it can change |
| HSN summary total doesn't tie to invoice total | HSN-wise values were calculated separately from invoice-level values and drifted apart | Generate the HSN summary from the same invoice data set, not a separate manual entry |
| File processed with errors, nothing visible on screen | The portal accepted the upload but flagged specific records; the error report has to be downloaded separately | Always download and read the error report after upload rather than assuming a successful upload means an error-free one |
Verifying the JSON Before You Upload
- Check that total invoice count in doc_issue matches your actual invoice register for the period.
- Confirm B2B GSTINs against a recent GSTIN validation, especially for new buyers added during the period.
- Reconcile total taxable value and tax amount in the JSON against your sales register or GSTR-1 automation summary before export.
- Check credit/debit notes reference the correct original invoice number.
- Keep a copy of the generated JSON and the validation report for your records.
JSON, Offline Utility, and Direct Upload
You can either upload the JSON directly through the GST portal's online return filing screen, or run it through the offline utility tool first for an extra validation pass before uploading. For larger sellers with high invoice volumes, the extra validation step is worth the few minutes it takes, since it catches structural errors before they consume a filing attempt. If you are still resolving a specific number mismatch rather than a file structure error, see how to fix a GST mismatch.
Amending a Filed GSTR-1 After the JSON Was Accepted
A JSON uploading successfully and the portal accepting it does not mean the underlying data was correct, only that it was structurally valid. If you spot an error after filing, for example an invoice value that was entered wrong or a buyer GSTIN that turned out to be inactive, the correction path is generally to amend the specific invoice in a later period's GSTR-1 filing rather than editing and re-uploading the original JSON. Each amendment generates its own JSON entry in the amendment table (typically prefixed differently in the export, such as b2ba for amended B2B invoices) for that later period, so your JSON preparation workflow needs to be able to find and re-export the original invoice with its amendment flag set, not just recreate it from scratch.
Keeping an audit trail across periods
Because a single invoice can appear in one period's original JSON and a later period's amendment JSON, it helps to keep both filings and their JSON exports on file together, tagged by invoice number, rather than only keeping the most recent version. This matters most when a buyer disputes an input tax credit months after the original sale, and you need to show exactly when and how an invoice was corrected.
Frequently Asked Questions
What is a GSTR-1 JSON file used for?
It is the structured data file the GST portal reads to populate and validate your GSTR-1 return. It contains all your outward supply details organised into sections like B2B, B2C, credit/debit notes, and HSN summary.
Why can't I just upload an Excel file instead?
The portal's filing system is built around the nested JSON structure. Excel and CSV exports exist for your internal use, review, and for import into accounting software, but the portal itself requires JSON.
What does 'processed with error' mean after uploading?
It means the portal accepted the file but found issues with one or more records inside it. Download the error report from the portal to see exactly which invoices or sections need correction.
Why do I get a duplicate invoice number error when my invoices look fine?
This usually happens when sales from two channels, such as two marketplaces or a marketplace plus direct sales, use overlapping invoice number series. Use distinct prefixes per channel.
Do I need to generate a fresh JSON every time I fix an error?
Yes. After correcting the underlying data, regenerate the export rather than editing the JSON file directly, since manual edits can break its structure.
Can OneBooks GST generate the GSTR-1 JSON for me?
Yes, GSTR-1 preparation in OneBooks GST includes B2B, B2C, credit/debit notes, HSN summary, and document summary, with export to GSTR-1 JSON along with CSV, Excel, and Tally XML formats.
