What Is a GST JSON Upload?
Nobody wants to type the same invoice twice.
A GST JSON upload is how invoice data reaches the GST portal from your billing software, as a file rather than one invoice at a time. Your software, or the government’s own offline utility, packs the invoice details into a JSON file, and you upload that instead of keying each bill in again.
One thing worth settling early. If your accounting software offers you an XML export, that file is meant for another accounting system. The portal reads JSON, and so does the e-invoice system.
How to Upload a JSON File to the GST Portal
Five steps, and the last one is the one people miss.
Step 1: Generate the file
Your billing software produces the JSON directly, or you feed a CSV into the government’s offline utility and let it build one. Either way you finish with a single file rather than a spreadsheet. The utility and its manual come from the GST portal’s downloads page.
Step 2: Check the size before you go
The portal will not take a JSON above 5 MB, and an offline return holds at most 19,000 line items. You are not limited to one file though, since multiple JSON files can be uploaded for the same tax period, which is how a heavy month gets filed.
Step 3: Upload it under Prepare Offline
Sign in, open the return for that period, and choose Prepare Offline rather than the online form. People get lost here, because the online form sits beside it and looks like the obvious route.
Step 4: Wait for the status
The portal queues the file rather than reading it on the spot, so nothing appears the moment you upload. Refresh to see whether it came back clean or flagged.
Step 5: File the return separately
Uploading is not filing. The data sits saved inside your GSTR-1 until you file it, a separate step you sign off with a DSC or EVC, carrying its own deadline.
What “Processed with Error” Actually Means
This is the status that panics people, and it should not.
It means the portal accepted the file, validated every line, and rejected some. The clean lines are already saved. Only the rejected ones need attention, and a downloadable error report names each one, which you open in the offline utility.
You do not re-upload the whole month. Fix the flagged lines, build a fresh file containing just those, and send it again.
The usual culprits are dull: a GSTIN that does not exist, an invoice number reused from an earlier month, a date that falls outside the return period, a place of supply that contradicts the tax you charged on the line.
Cleaner source data is the only real cure, which is the argument for letting software carry invoices end to end rather than rekeying them between systems.
Working from a GST return filing checklist catches most of them before the file is even built.
GST JSON Upload Example
A poultry supplier in Namakkal sits down on the 9th to file August’s GST return.
| Field | What happened |
|---|---|
| Invoices | 4,180 B2B invoices, roughly 16,000 line items |
| File | One JSON, generated straight from the billing data |
| Problem | Over the 5 MB cap, so the portal would not take it |
| Fix | Split into two files and uploaded separately |
| Result | Processed with Error on eleven lines, corrected and re-sent |
Note: this is an invented example for illustration only. File sizes depend on how many line items each invoice carries.
JSON Upload vs Typing Invoices on the Portal
Past a certain invoice count the file stops being a choice.
| Aspect | JSON upload | Typing on the portal |
|---|---|---|
| Volume | Thousands of lines | A few dozen at most |
| Source | Your billing data | Re-keyed by hand |
| Errors | Listed in a report | Found later, if at all |
| Cap | 5 MB, 19,000 line items | None, but time runs out |
The cap is the dividing line. Below a few hundred invoices the portal form is fine; above it, one mistyped GSTIN costs more time than the export saved.
Check the Numbers Before You Upload
In the filings we see, the damage is rarely done at the portal. It is done weeks earlier, at a counter where a GSTIN was typed with a digit missing and nobody looked again.
Petpooja Invoice works at that earlier stage, before any of those numbers reach a JSON file. It calculates GST automatically on every invoice, so the figures reaching your return were right when the bill was raised. Its GST reports for compliance and auditing keep tax payable, input tax credit and cash ledger balance in view as the month runs.
Open those reports a week before the deadline and see whether they agree with the month you actually had.
Frequently Asked Questions
No. The portal and the e-invoice system both read JSON, and an XML export from your accounting software is meant for another accounting system rather than for filing.
5 MB for the file, and an offline return holds at most 19,000 line items. Past either limit you split the data across more than one file.
No. The lines that passed are saved and only the rejected ones need fixing, which the downloadable error report lists individually.
Only if your billing software cannot produce the JSON itself. Where it can, you export from your own system and upload straight to the portal.
No, and this catches people every quarter. Uploading saves the data against your return, while filing is a separate step you complete with a DSC or EVC.
