# List india gst invoices

`GET /api/v1/india-gst/invoices`

The store's statutory GST tax invoices, newest first. This is the feed a GSTR-1 return is assembled from, and it is the reason this family is published: an invoice was previously reachable only by its own id, which nobody preparing a return has. THREE FILTERS, NOT THREE ROUTES. ?financial_year= is the filing period, ?order_id= reconciles one order against its document, and ?status= separates the invoices that stand from the ones that were voided. A CANCELLED INVOICE IS NOT HIDDEN by default, and must not be treated as absent. The void is part of the merchant's record: the number was really drawn from the series and a return that silently omitted it would be wrong. Amounts are integers in the MINOR UNIT of currency_code, which comes from the order the invoice was issued against. Exactly one of the cgst/sgst pair and igst is non-zero: intra-state supplies split CGST and SGST, inter-state supplies carry IGST. Each row carries its LINES, because a per-line HSN and rate breakdown is what a return needs and fetching it per invoice would be a request per document.

## Query parameters

- `financial_year` (string) — The Indian financial year as YYYY-YY, for example 2025-26 for 1 April 2025 to 31 March 2026. This is the filing period, and the invoice sequence restarts each year, so a number is only unique together with it. A value in any other shape is a 400 rather than an empty page, because "2025-2026" matching nothing would read as "this store issued no invoices that year".
- `order_id` (string) — EXACT match on one order, which is how you reconcile an order against its document. An order with no invoice returns an empty page. An order can have more than one row here over time: cancelling frees its slot, so a corrected order carries the void and the replacement.
- `status` (active | cancelled) — active is an invoice that still stands, cancelled is one that was voided. A value outside the enum is a 400 rather than an unfiltered page, so a misspelled "canceled" cannot silently return everything. OMIT IT FOR A RETURN. Unfiltered includes the voided invoices, and they belong in the merchant's record: the number was really drawn from the series.
- `limit` (integer) — Rows per page. Out of range is a 400 rather than a silent clamp, so a client asking for more than 100 learns it did not get it.
- `after` (string) — The next_cursor from the previous page. Opaque: decode nothing from it and construct nothing by hand, since its encoding is not part of this contract. Omit it to read the first page.

## Responses

- `200` — Success
- `400` — The request was refused before any state changed. `code` is one of:

`invalid_body`, a write body this route will not take. `reason` partitions it
and `field` names the key when one key is at fault.
`invalid_query`, a query parameter, including limit and after.
`invalid_text`, a NUL byte or bytes that are not valid UTF-8 anywhere in the
path, the query or the body. Strip control characters before sending.
`idempotency_key_required`, a write sent without the Idempotency-Key header.
`invalid_request`, an Idempotency-Key longer than 255 bytes.

Routes add their own codes for rules only they know. Switch with a default arm.
- `401` — No credential, or one this API does not accept. `code` is always
`unauthorized`.

THE BODY IS DELIBERATELY UNINFORMATIVE. An expired key, a revoked key, a
publishable key, a key belonging to another merchant and a key that never
existed are all refused with the same bytes, so this response cannot be used to
probe which keys exist. Check the key's state in the dashboard rather than
inferring it here.

Send the key as `Authorization: Bearer <key>` or as `X-API-Key: <key>`. It is
never accepted in a query string.
- `403` — The key lacks the read_india_gst scope. `code` is `insufficient_scope` and the message names the scope to ask the merchant for.
- `429` — Too many requests. `code` is `rate_limited`.

Two limits apply independently: one on the credential and the route family,
one on the client address. The headers describe whichever has less left, so
honouring Retry-After always clears the window that bound.
- `default` — Any status this operation does not list, in the same envelope.

A 5xx means the request may or may not have applied. Retry it with the SAME
Idempotency-Key: that is the only way to find out without risking a duplicate,
and it is what the key is for.

A few 4xx conditions arrive here rather than as a listed status because they
depend on the merchant's plan or on a module being wired: 402 when a quota or a
plan limit is reached, and 503 when a capability the route needs is not
configured on this deployment. Both carry a `code` naming which.

## Example

```bash
curl --request GET \
  --url 'https://api.mercemur.com/api/v1/india-gst/invoices' \
  --header 'Authorization: Bearer <token>'
```