> ## Documentation Index > Fetch the complete documentation index at: https://docs.recurso.dev/llms.txt > Use this file to discover all available pages before exploring further. # Get GSTR-1 Return > Assemble the GSTR-1 outward-supply return for a tax period from finalized invoices and credit notes, in readable form and in GSTN upload JSON. Builds the GSTR-1 return for one calendar month from the tenant's finalized invoices and refund credit notes: B2B supplies to registered buyers invoice-by-invoice, B2CS supplies to unregistered buyers summarised rate-wise per place of supply, CDNR credit notes issued to registered buyers, an HSN rollup, and control totals. Nothing is recomputed — every figure is the value already on the invoice or credit note, so the return reconciles to what was billed and to the ledger. The response carries the same return twice: `data` in readable field names with amounts in **minor units (paise)**, and `gov_schema` in the GSTN GSTR-1 JSON shape (official field names, amounts in rupees) ready to validate against the Returns Offline Tool before filing. The seller GSTIN in `gov_schema` comes from your [GST configuration](/api-reference/gst/get-config). For the companion summary return see [Get GSTR-3B Return](/api-reference/gst/gstr3b); for the filing workflow see the [GST returns guide](/compliance/gst-returns). ## Parameters | Parameter | Type | Required | Description | | ----------- | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `month` | integer | Yes | Calendar month of the tax period, `1`–`12` (query) | | `year` | integer | Yes | Year of the tax period, `2017`–`2100` (query) | | `entity_id` | string (UUID) | No | File for one legal entity's GSTIN (Multi-Entity Books). Omit to include all invoices under the tenant's primary / default GST configuration (query). See [List Entities](/api-reference/entities/list) | ## Example Request ```bash theme={null} curl "https://api.recurso.dev/v1/india/gstr1?month=6&year=2026" \ -H "Authorization: Bearer $API_KEY" ``` ## Response `data` holds the readable sections in paise; `gov_schema` holds the same period in rupees. A period with no finalized invoices returns empty sections and zero totals. In the example the seller is registered in Karnataka (`29`): the B2B buyer's place of supply is also `29`, so its invoice splits into CGST/SGST, while the B2CS supply to Maharashtra (`27`) attracts IGST. ```json theme={null} { "data": { "tenant_id": "2b9e1c44-7d3a-4f6b-8e21-5c0d9a7f1b33", "month": 6, "year": 2026, "b2b": [ { "gstin": "29AAACR5055K1Z5", "invoices": [ { "invoice_number": "INV-2026-000412", "date": "2026-06-05T00:00:00Z", "place_of_supply": "29", "taxable_value": 1000000, "igst": 0, "cgst": 90000, "sgst": 90000, "rate": 18 } ] } ], "b2cs": [ { "place_of_supply": "27", "rate": 18, "taxable_value": 250000, "igst": 45000, "cgst": 0, "sgst": 0 } ], "cdnr": [ { "gstin": "29AAACR5055K1Z5", "notes": [ { "note_number": "CN-2026-000031", "date": "2026-06-18T00:00:00Z", "original_invoice_number": "INV-2026-000412", "place_of_supply": "29", "taxable_value": 100000, "igst": 0, "cgst": 9000, "sgst": 9000, "rate": 18 } ] } ], "hsn_summary": [ { "hsn_code": "998314", "taxable_value": 1250000, "igst": 45000, "cgst": 90000, "sgst": 90000, "invoice_count": 2 } ], "total_taxable_value": 1250000, "total_igst": 45000, "total_cgst": 90000, "total_sgst": 90000, "invoice_count": 2, "total_credit_taxable_value": 100000, "total_credit_igst": 0, "total_credit_cgst": 9000, "total_credit_sgst": 9000, "credit_note_count": 1 }, "gov_schema": { "gstin": "29AABCT1332L1ZM", "fp": "062026", "b2b": [ { "ctin": "29AAACR5055K1Z5", "inv": [ { "inum": "INV-2026-000412", "idt": "05-06-2026", "val": 11800, "pos": "29", "rchrg": "N", "inv_typ": "R", "itms": [ { "num": 1, "itm_det": { "rt": 18, "txval": 10000, "iamt": 0, "camt": 900, "samt": 900, "csamt": 0 } } ] } ] } ], "b2cs": [ { "sply_ty": "INTER", "pos": "27", "typ": "OE", "rt": 18, "txval": 2500, "iamt": 450, "camt": 0, "samt": 0, "csamt": 0 } ], "cdnr": [ { "ctin": "29AAACR5055K1Z5", "nt": [ { "ntty": "C", "nt_num": "CN-2026-000031", "nt_dt": "18-06-2026", "val": 1180, "pos": "29", "rchrg": "N", "inv_typ": "R", "itms": [ { "num": 1, "itm_det": { "rt": 18, "txval": 1000, "iamt": 0, "camt": 90, "samt": 90, "csamt": 0 } } ] } ] } ], "hsn": { "data": [ { "num": 1, "hsn_sc": "998314", "desc": "", "uqc": "OTH", "qty": 0, "txval": 12500, "iamt": 450, "camt": 900, "samt": 900, "csamt": 0 } ] } } } ``` ## Fields ### `data` — readable return (minor units) | Field | Type | Description | | --------------------------------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tenant_id` | string (UUID) | Owning tenant | | `month` / `year` | integer | The tax period | | `b2b[]` | array | Supplies to registered buyers, grouped by buyer GSTIN: `gstin`, `invoices[]` | | `b2b[].invoices[]` | array | One row per finalized invoice: `invoice_number`, `date` (RFC 3339), `place_of_supply` (the customer's own place-of-supply state code, taken from the customer record — not derived from the GSTIN prefix), `taxable_value`, `igst`, `cgst`, `sgst` (paise), `rate` (combined GST %, e.g. `18`) | | `b2cs[]` | array | Supplies to unregistered buyers, summarised per `place_of_supply` and `rate`: `taxable_value`, `igst`, `cgst`, `sgst` | | `cdnr[]` | array | Credit notes issued to registered buyers, grouped by buyer GSTIN: `gstin`, `notes[]` | | `cdnr[].notes[]` | array | One row per credit note: `note_number`, `date`, `original_invoice_number`, `place_of_supply`, `taxable_value`, `igst`, `cgst`, `sgst`, `rate` | | `hsn_summary[]` | array | Per-HSN/SAC rollup of outward supplies: `hsn_code`, `taxable_value`, `igst`, `cgst`, `sgst`, `invoice_count` | | `total_taxable_value` | integer | Gross outward taxable value across all invoices, paise. Not net of credit notes — GSTR-1 reports notes in their own section | | `total_igst` / `total_cgst` / `total_sgst` | integer | Gross outward tax by head, paise | | `invoice_count` | integer | Finalized invoices in the period | | `total_credit_taxable_value` | integer | Taxable value reversed by CDNR notes, paise | | `total_credit_igst` / `total_credit_cgst` / `total_credit_sgst` | integer | Tax reversed by CDNR notes, paise | | `credit_note_count` | integer | Credit notes in the period | ### `gov_schema` — GSTN GSTR-1 upload JSON (rupees) | Field | Type | Description | | -------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `gstin` | string | Seller GSTIN from the GST configuration for the requested entity. Empty when none is configured — an obviously invalid filing, by design | | `fp` | string | Filing period as `MMYYYY` | | `b2b[]` | array | `ctin` (buyer GSTIN) and `inv[]`: `inum`, `idt` (`DD-MM-YYYY`), `val` (invoice value incl. tax), `pos`, `rchrg` (always `"N"`), `inv_typ` (always `"R"`), `itms[]` with `num` and `itm_det` (`rt`, `txval`, `iamt`, `camt`, `samt`, `csamt`). Omitted when empty | | `b2cs[]` | array | Rate-wise unregistered supplies: `sply_ty` (`INTER` when IGST applies, else `INTRA`), `pos`, `typ` (always `"OE"`), `rt`, `txval`, `iamt`, `camt`, `samt`, `csamt`. Omitted when empty | | `cdnr[]` | array | `ctin` and `nt[]`: `ntty` (always `"C"`), `nt_num`, `nt_dt`, `val`, `pos`, `rchrg`, `inv_typ`, `itms[]`. Omitted when empty | | `hsn` | object | `data[]` rows: `num`, `hsn_sc`, `desc`, `uqc` (always `"OTH"`), `qty`, `txval`, `iamt`, `camt`, `samt`, `csamt`. Omitted when there are no invoices | Cess (`csamt`) and reverse charge are not modelled, so they are always `0` and `"N"`. ## Errors | Status | Code | When | Fix | | ------ | ------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | `400` | `validation_failed` | `month` is missing or outside `1`–`12`, `year` is missing or outside `2017`–`2100`, or `entity_id` is not a valid UUID | Pass both period parameters as integers and a valid entity UUID | | `401` | `unauthorized` | Missing or invalid API key / session | Send `Authorization: Bearer $API_KEY` | | `500` | `internal_error` | Building the return from the period's invoices failed | Retry; contact support if it persists | | `503` | `internal_error` | GSTR-1 export is not configured on this deployment | Enable the GSTR service on the API | Errors use the standard envelope — see [Errors](/api-reference/errors). ## OpenAPI ````yaml GET /v1/india/gstr1 openapi: 3.1.0 info: title: Recurso API version: 1.0.0 description: | The Recurso billing engine REST API. Authenticate by passing your API key as a bearer token: Authorization: Bearer Obtain an API key by registering a tenant via `POST /auth/register`. All authenticated endpoints live under the `/v1` prefix. Mutating endpoints support idempotency via the `Idempotency-Key` header. license: name: MIT identifier: MIT servers: - url: https://billing.example.com description: >- Example deployment — substitute the base URL of your own Recurso deployment. security: - bearerAuth: [] tags: - name: System description: Health, version, and API metadata - name: Auth description: Tenant registration - name: Plans description: Product catalog plans - name: Customers description: Customer management - name: Subscriptions description: Subscription lifecycle - name: Invoices description: Invoices, PDFs, and Indian GST e-invoicing - name: Coupons description: Discounts - name: Usage description: Metered usage events - name: Credit Notes description: Customer credits - name: Quotes description: Quote-to-invoice lifecycle - name: Webhooks description: Webhook endpoint management and event feed - name: Analytics description: Revenue analytics - name: Checkout description: Public hosted checkout for invoices - name: Payments description: Payment order creation - name: Inbound Webhooks description: Receivers for payment-gateway callbacks (Razorpay, Stripe) - name: Customer Portal description: Customer-facing portal — magic-link auth and session-scoped data - name: Developer description: API key management - name: Account description: Tenant account settings - name: Finance description: Ledger accounts, entries, reconciliation, and revenue recognition - name: Settings description: Tax (GST) and e-invoicing (IRP) configuration - name: Consents description: Consent records for RBI-compliant recurring billing - name: Referrals description: Customer referral program - name: Gifts description: Gift subscriptions - name: Mandates description: UPI Autopay mandates - name: Offline Payments description: Virtual accounts and manually recorded payments - name: Organizations description: Multi-entity organizations grouping several tenants - name: Accounting description: QuickBooks / Xero accounting integrations - name: Churn description: Churn risk scoring and alerts - name: Cancel Flows description: Configurable retention flows shown at cancellation time - name: Dunning description: Dunning analytics and multi-channel dunning campaigns paths: /v1/india/gstr1: get: tags: - Settings summary: GSTR-1 outward-supply return for a tax period description: > Assembles the GSTR-1 return from the tenant's finalized invoices and refund credit notes for the given month: B2B (registered buyers, invoice-level), B2CS (unregistered, rate-wise), CDNR (credit notes to registered buyers), an HSN rollup, and control totals. Returns the readable sections plus a `gov_schema` object in the GSTN GSTR-1 JSON shape (official field names, amounts in rupees) ready to validate against the government offline tool before filing. operationId: getGSTR1 parameters: - name: month in: query required: true schema: type: integer minimum: 1 maximum: 12 description: Calendar month of the tax period. - name: year in: query required: true schema: type: integer minimum: 2017 maximum: 2100 description: Year of the tax period. - $ref: '#/components/parameters/EntityIdQuery' responses: '200': description: The GSTR-1 return, readable and in government JSON shape. content: application/json: schema: type: object properties: data: type: object description: >- Readable GSTR-1 sections and control totals (amounts in minor units). gov_schema: type: object description: >- GSTN GSTR-1 upload JSON (official field names, amounts in rupees). '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' components: parameters: EntityIdQuery: name: entity_id in: query required: false description: >- Legal entity to scope the tax config to (Multi-Entity Books). Omit for the tenant's primary entity / default config. schema: type: string format: uuid responses: BadRequest: description: The request body or parameters are invalid. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Missing or invalid credentials (API key or session cookie). content: application/json: schema: $ref: '#/components/schemas/Error' schemas: Error: type: object required: - error properties: error: type: object description: Structured error detail. required: - code - message properties: code: type: string description: Stable machine-readable error code. examples: - validation_failed - unauthorized - forbidden - not_found - conflict - rate_limited - internal_error - invalid_api_key - key_mode_mismatch - over_refund - invoice_not_paid - invoice_already_paid message: type: string description: Human-readable explanation. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key description: >- Tenant API key obtained from `POST /auth/register` or `POST /v1/developer/keys`. ````