---
title: "GSTR-1 Return API — SpireStock REST API"
description: "Preview and download the monthly GSTR-1 return as the GST portal's upload JSON: B2B, B2C large and small, exempt supplies, HSN summary and documents issued, built from your invoices with the problems the portal would reject listed first."
source: https://developers.spirestock.com/api-reference/gst-returns
---

# GSTR-1 Return API

Preview and download the monthly GSTR-1 return as the GST portal's upload JSON: B2B, B2C large and small, exempt supplies, HSN summary and documents issued, built from your invoices with the problems the portal would reject listed first.

Base URL: `https://api.spirestock.com/api/v1`. Every request needs an API key (`X-API-Key`) or a session token (`Authorization: Bearer`); see https://developers.spirestock.com/api-reference/auth.

## Endpoints

- [GET /einvoice/gstr1](https://developers.spirestock.com/api-reference/gst-returns#get-einvoice-gstr1)
- [GET /einvoice/gstr1/json](https://developers.spirestock.com/api-reference/gst-returns#get-einvoice-gstr1-json)

## GET /einvoice/gstr1

Preview the GSTR-1 return for a month, built from the same invoices as the Accounts invoices and with the same amounts to the paisa. Reports what goes into each table (4A B2B, 5 B2C large: inter-state above Rs 1 lakh, 7 B2C others, 8 exempt supplies: 0% items, 12 HSN summary split B2B/B2C, 13 documents issued), the tax totals, the problems that would make the GST portal reject the file and warnings worth checking. B2B invoices with an IRN are left out of 4A by default because the portal fills them in from the e-invoice system. Reads only: no invoice number is fixed by a preview. GST e-Invoice add-on (402 ADDON_REQUIRED without it).

Access: API key `read` scope; staff need Invoices (14) — list.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `month` | string | no | Return period, YYYY-MM. Default: the current month in IST; a future month is refused (400) |
| `include_einvoiced` | string | no | 1 to put IRN-generated B2B invoices in 4A as well (default 0) |

**Example request**

```bash
curl "https://api.spirestock.com/api/v1/einvoice/gstr1?month=2026-10" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```json
{
  "response_code": 200,
  "month": "2026-10",
  "period": "102026",
  "gstin": "23AAACT1234B1Z7",
  "include_einvoiced": false,
  "in_progress": false,
  "summary": {
    "invoices": 3,
    "b2b": 2,
    "b2b_einvoiced": 0,
    "b2cl": 0,
    "b2c_small": 1,
    "exempt_only": 0,
    "cancelled": 0,
    "skipped_empty": 0,
    "taxable_value": 98774.88,
    "igst": 2468.34,
    "cgst": 2468.34,
    "sgst": 2468.34,
    "exempt_value": 8640,
    "invoice_value": 114936
  },
  "sections": { "b2b": 2, "b2cl": 0, "b2cs": 2, "nil": 3, "hsn_b2b": 3, "hsn_b2c": 3 },
  "problem_count": 0,
  "warning_count": 1,
  "problems": [],
  "warnings": [
    { "message": "HSN 0401 has 4 digits: enough up to Rs 5 crore annual turnover, above that the portal needs 6" }
  ]
}
```

## GET /einvoice/gstr1/json

Download the GSTR-1 JSON to upload on the GST portal (Returns, GSTR-1, Prepare offline, Upload). Answers 422 with the list of problems while anything would be rejected (an invalid GSTIN, a missing or malformed HSN code, an unknown place of supply, a tax type that contradicts the place of supply, a workspace state code that disagrees with its GSTIN), and 404 when the month has no invoices. Downloading fixes every invoice number in the file. Amounts per line come from the printed invoice: taxable value and CGST + SGST, or IGST for inter-state supplies; 0% lines are reported in Table 8 as exempt. GST e-Invoice add-on.

Access: API key `read` scope; staff need Invoices (14) — list.

**Parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `month` | string | no | Return period, YYYY-MM. Default: the current month in IST |
| `include_einvoiced` | string | no | 1 to put IRN-generated B2B invoices in 4A as well (default 0) |

**Example request**

```bash
curl "https://api.spirestock.com/api/v1/einvoice/gstr1/json?month=2026-10" \
  -H "X-API-Key: YOUR_API_KEY" -OJ
```

**Example response**

```
Content-Type: application/json; charset=utf-8
Content-Disposition: attachment; filename="GSTR1_23AAACT1234B1Z7_102026.json"

{
  "gstin": "23AAACT1234B1Z7",
  "fp": "102026",
  "b2b": [
    {
      "ctin": "23BBBPS5678C1ZN",
      "inv": [
        {
          "inum": "ORD0001008-001",
          "idt": "05-10-2026",
          "val": 38312,
          "pos": "23",
          "rchrg": "N",
          "inv_typ": "R",
          "itms": [
            { "num": 1, "itm_det": { "rt": 5, "txval": 21180.8, "camt": 529.52, "samt": 529.52, "csamt": 0 } },
            { "num": 2, "itm_det": { "rt": 12, "txval": 11744.16, "camt": 704.65, "samt": 704.65, "csamt": 0 } }
          ]
        }
      ]
    }
  ],
  "b2cs": [{ "sply_ty": "INTRA", "pos": "23", "typ": "OE", "rt": 5, "txval": 21180.8, "camt": 529.52, "samt": 529.52, "csamt": 0 }],
  "nil": { "inv": [{ "sply_ty": "INTRAB2B", "expt_amt": 2880, "nil_amt": 0, "ngsup_amt": 0 }] },
  "hsn": {
    "hsn_b2b": [{ "num": 1, "hsn_sc": "0401", "desc": "Milk", "uqc": "LTR", "qty": 48, "rt": 0, "txval": 2880, "iamt": 0, "camt": 0, "samt": 0, "csamt": 0 }],
    "hsn_b2c": [{ "num": 1, "hsn_sc": "0401", "desc": "Milk", "uqc": "LTR", "qty": 48, "rt": 0, "txval": 2880, "iamt": 0, "camt": 0, "samt": 0, "csamt": 0 }]
  },
  "doc_issue": { "doc_det": [{ "doc_num": 1, "doc_typ": "Invoices for outward supply", "docs": [{ "num": 1, "from": "ORD0001008-001", "to": "ORD0001012-001", "totnum": 3, "cancel": 0, "net_issue": 3 }] }] }
}

(shortened: one B2B invoice and one row per other table shown)

422:
{
  "response_code": 422,
  "message": "Fix these 2 problems before downloading GSTR-1",
  "problems": [
    "ORD0001008-001: Paneer 5kg has no valid HSN code (blank); it needs 4, 6 or 8 digits",
    "ORD0001012-001: Charged CGST + SGST but the place of supply (27) is another state; correct the state on Demo Store's route (the State master's inter-state setting decides the tax type)"
  ]
}
```
