# GST returns

> GST returns and their IRD box amounts, for one entity or across the workspace.

Part of the [Prosaic API reference](https://developer.prosaic.works/docs/api.md). Base URL: `https://app.prosaic.works/api/public/v1`. Authenticate with `Authorization: Bearer <API key or access token>`.

## List GST returns across the workspace

`GET /api/public/v1/gst-returns`

SDK: `prosaic.gstReturns.list(params)`

Returns paginated GST returns for every entity in the workspace the
caller can see, newest period first. The entity-scoped endpoint
(`/entities/{entityId}/gst-returns`) returns the same rows for one
entity; use `entityId` here to narrow without changing endpoint.

Each row carries the return's lifecycle status, its period, its filing due date,
its net GST position (IRD Box 15) and a count of bank transactions in the period
that are not yet reconciled.

**Box 15 is only present once the return has been calculated.** A draft that has
never been finalised reports `netGstPosition: null`. Use the entity detail endpoint
to get live, calculated box amounts for a draft.

**Period and due dates are New Zealand calendar days** (`YYYY-MM-DD`), not UTC
instants. A GST period runs from the first moment of `dateFrom` to the last moment
of `dateTo`, both in NZ time.

By default, draft returns whose period has not started yet are hidden, matching
what the Prosaic UI shows. Pass `includeFutureDrafts=true` to see them.

### Query parameters

- `entityId` (string): Return only GST returns for this entity.
- `status` (array of strings): Return only GST returns in these lifecycle statuses. Repeatable, and a comma-separated list means the same thing — `?status=draft&status=filed` and `?status=draft,filed` are equivalent. Omit for every status; nothing is filtered out by default, so completed returns appear alongside outstanding ones. To see only live work, list the seven statuses other than `completed`. .
- `dateFrom` (string): Return only GST returns whose period ends on or after this NZ date.
- `dateTo` (string): Return only GST returns whose period starts on or before this NZ date.
- `dueAfter` (string): Return only GST returns due on or after this NZ date.
- `dueBefore` (string): Return only GST returns due on or before this NZ date.
- `includeFutureDrafts` (string): Include draft returns whose period has not started yet (default false) One of: `false`, `true`.
- `page` (integer): Page number (default 1)
- `pageSize` (integer): Items per page (default 100)

### Responses

- `200`: Successful response
  - `data` (array of objects, required)
    - `id` (string, required)
    - `entityId` (string, required)
    - `name` (string, required)
    - `description` (string, required)
    - `status` (string, required): One of: `rejected`, `completed`, `draft`, `finalised`, `filed`, `filed_externally`, `accepted`, `awaiting_payment`.
    - `dateFrom` (string, required)
    - `dateTo` (string, required)
    - `dueDate` (string, required)
    - `isOverdue` (boolean, required)
    - `netGstPosition` (number, nullable, required)
    - `unreconciledTransactionCount` (number, required)
    - `hasAmendment` (boolean, required)
    - `finalisedAt` (string, nullable, required)
    - `irdFiledAt` (string, nullable, required)
    - `updatedAt` (string, required)
  - `pagination` (object, required)
    - `currentPage` (number, required)
    - `pageSize` (number, required)
    - `totalCount` (number, required)
    - `totalPages` (number, required)
    - `hasNextPage` (boolean, required)
    - `hasPreviousPage` (boolean, required)
- `400`: Invalid query parameters
  - `error` (string): Error message.
  - `code` (string): Error code for programmatic handling.
- `401`: Unauthorized - invalid or missing credentials
  - `error` (string): Error message.
  - `code` (string): Error code for programmatic handling.
- `403`: An entity-scoped token asked for an entity it is not pinned to
  - `error` (string): Error message.
  - `code` (string): Error code for programmatic handling.
- `404`: Workspace not found or not accessible with these credentials
  - `error` (string): Error message.
  - `code` (string): Error code for programmatic handling.
- `500`: Internal server error
  - `error` (string): Error message.
  - `code` (string): Error code for programmatic handling.

### Example (Node SDK)

```ts
const page = await prosaic.gstReturns.list();
```

### Example (curl)

```bash
curl https://app.prosaic.works/api/public/v1/gst-returns \
  -H "Authorization: Bearer $PROSAIC_API_KEY"
```

## List GST returns for an entity

`GET /api/public/v1/entities/{entityId}/gst-returns`

SDK: `prosaic.gstReturns.listForEntity(entityId, params)`

Returns paginated GST returns for the specified entity, newest period first.

Each row carries the return's lifecycle status, its period, its filing due date,
its net GST position (IRD Box 15) and a count of bank transactions in the period
that are not yet reconciled.

**Box 15 is only present once the return has been calculated.** A draft that has
never been finalised reports `netGstPosition: null`. Use the detail endpoint to get
live, calculated box amounts for a draft.

**Period and due dates are New Zealand calendar days** (`YYYY-MM-DD`), not UTC
instants. A GST period runs from the first moment of `dateFrom` to the last moment
of `dateTo`, both in NZ time.

By default, draft returns whose period has not started yet are hidden, matching
what the Prosaic UI shows. Pass `includeFutureDrafts=true` to see them.

### Path parameters

- `entityId` (string, required)

### Query parameters

- `status` (array of strings): Return only GST returns in these lifecycle statuses. Repeatable, and a comma-separated list means the same thing — `?status=draft&status=filed` and `?status=draft,filed` are equivalent. Omit for every status; nothing is filtered out by default, so completed returns appear alongside outstanding ones. To see only live work, list the seven statuses other than `completed`. .
- `dateFrom` (string): Return only GST returns whose period ends on or after this NZ date.
- `dateTo` (string): Return only GST returns whose period starts on or before this NZ date.
- `dueAfter` (string): Return only GST returns due on or after this NZ date.
- `dueBefore` (string): Return only GST returns due on or before this NZ date.
- `includeFutureDrafts` (string): Include draft returns whose period has not started yet (default false) One of: `false`, `true`.
- `page` (integer): Page number (default 1)
- `pageSize` (integer): Items per page (default 100)

### Responses

- `200`: Successful response
  - `data` (array of objects, required)
    - `id` (string, required)
    - `entityId` (string, required)
    - `name` (string, required)
    - `description` (string, required)
    - `status` (string, required): One of: `rejected`, `completed`, `draft`, `finalised`, `filed`, `filed_externally`, `accepted`, `awaiting_payment`.
    - `dateFrom` (string, required)
    - `dateTo` (string, required)
    - `dueDate` (string, required)
    - `isOverdue` (boolean, required)
    - `netGstPosition` (number, nullable, required)
    - `unreconciledTransactionCount` (number, required)
    - `hasAmendment` (boolean, required)
    - `finalisedAt` (string, nullable, required)
    - `irdFiledAt` (string, nullable, required)
    - `updatedAt` (string, required)
  - `pagination` (object, required)
    - `currentPage` (number, required)
    - `pageSize` (number, required)
    - `totalCount` (number, required)
    - `totalPages` (number, required)
    - `hasNextPage` (boolean, required)
    - `hasPreviousPage` (boolean, required)
- `400`: Invalid query parameters
  - `error` (string): Error message.
  - `code` (string): Error code for programmatic handling.
- `401`: Unauthorized - invalid or missing credentials
  - `error` (string): Error message.
  - `code` (string): Error code for programmatic handling.
- `404`: Entity not found or not accessible with these credentials
  - `error` (string): Error message.
  - `code` (string): Error code for programmatic handling.
- `500`: Internal server error
  - `error` (string): Error message.
  - `code` (string): Error code for programmatic handling.

### Example (Node SDK)

```ts
const page = await prosaic.gstReturns.listForEntity(entityId);
```

### Example (curl)

```bash
curl https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/gst-returns \
  -H "Authorization: Bearer $PROSAIC_API_KEY"
```

## Get a single GST return with its IRD box amounts

`GET /api/public/v1/entities/{entityId}/gst-returns/{gstReturnId}`

SDK: `prosaic.gstReturns.retrieve(entityId, gstReturnId)`

Returns one GST return, including the IRD return boxes 5 to 15.

**Where the numbers come from depends on the return's status**, and `amountsSource`
says which. A `draft` return has no persisted totals, so the boxes are calculated
live from posted journal lines and will move as coding changes — `amountsSource` is
`calculated`. Every other status reads the snapshot taken at finalisation, which is
what was, or will be, filed with IRD — `amountsSource` is `finalised`.

**Period and due dates are New Zealand calendar days** (`YYYY-MM-DD`), not UTC instants.

IRD submission keys, raw IRD response payloads and amendment original values are
internal and are never returned.

### Path parameters

- `entityId` (string, required)
- `gstReturnId` (string, required)

### Responses

- `200`: Successful response
  - `data` (object, required)
    - `amountsSource` (string, required): One of: `finalised`, `calculated`.
    - `totalSalesAndIncome` (number, nullable, required)
    - `zeroRatedSupplies` (number, nullable, required)
    - `netGstSalesAndIncome` (number, nullable, required)
    - `totalGstSalesAndIncome` (number, nullable, required)
    - `debitAdjustments` (number, nullable, required)
    - `lateClaimsAmount` (number, nullable, required)
    - `lateClaimsType` (string, nullable, required): One of: `sales`, `purchases`.
    - `totalDebitAdjustments` (number, nullable, required)
    - `totalGstCollected` (number, nullable, required)
    - `totalPurchasesAndExpenses` (number, nullable, required)
    - `totalGstCreditsOnPurchasesAndExpenses` (number, nullable, required)
    - `creditAdjustments` (number, nullable, required)
    - `totalCreditAdjustments` (number, nullable, required)
    - `totalGstCredit` (number, nullable, required)
    - `id` (string, required)
    - `entityId` (string, required)
    - `name` (string, required)
    - `description` (string, required)
    - `status` (string, required): One of: `rejected`, `completed`, `draft`, `finalised`, `filed`, `filed_externally`, `accepted`, `awaiting_payment`.
    - `dateFrom` (string, required)
    - `dateTo` (string, required)
    - `dueDate` (string, required)
    - `isOverdue` (boolean, required)
    - `netGstPosition` (number, nullable, required)
    - `unreconciledTransactionCount` (number, required)
    - `hasAmendment` (boolean, required)
    - `finalisedAt` (string, nullable, required)
    - `irdFiledAt` (string, nullable, required)
    - `updatedAt` (string, required)
  - `meta` (object)
    - `count` (number, required)
- `400`: Malformed GST return id
  - `error` (string): Error message.
  - `code` (string): Error code for programmatic handling.
- `401`: Unauthorized - invalid or missing credentials
  - `error` (string): Error message.
  - `code` (string): Error code for programmatic handling.
- `404`: No such GST return for this entity
  - `error` (string): Error message.
  - `code` (string): Error code for programmatic handling.
- `500`: Internal server error
  - `error` (string): Error message.
  - `code` (string): Error code for programmatic handling.

### Example (Node SDK)

```ts
const { data } = await prosaic.gstReturns.retrieve(entityId, gstReturnId);
```

### Example (curl)

```bash
curl https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/gst-returns/$GST_RETURN_ID \
  -H "Authorization: Bearer $PROSAIC_API_KEY"
```