All API resources
API reference

GST returns

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

Base URL https://app.prosaic.works/api/public/v1. Every request needs an API key or access token; see the overview.

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

  • entityIdstring

    Return only GST returns for this entity

  • statusarray 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.

  • dateFromstring

    Return only GST returns whose period ends on or after this NZ date

  • dateTostring

    Return only GST returns whose period starts on or before this NZ date

  • dueAfterstring

    Return only GST returns due on or after this NZ date

  • dueBeforestring

    Return only GST returns due on or before this NZ date

  • includeFutureDraftsstring

    Include draft returns whose period has not started yet (default false)

    One of: false, true

  • pageinteger

    Page number (default 1)

  • pageSizeinteger

    Items per page (default 100)

Responses

200 Successful response

  • dataarray of objectsrequired
    Show 15 child attributes
    • idstringrequired
    • entityIdstringrequired
    • namestringrequired
    • descriptionstringrequired
    • statusstringrequired

      One of: rejected, completed, draft, finalised, filed, filed_externally, accepted, awaiting_payment

    • dateFromstringrequired
    • dateTostringrequired
    • dueDatestringrequired
    • isOverduebooleanrequired
    • netGstPositionnumberrequirednullable
    • unreconciledTransactionCountnumberrequired
    • hasAmendmentbooleanrequired
    • finalisedAtstringrequirednullable
    • irdFiledAtstringrequirednullable
    • updatedAtstringrequired
  • paginationobjectrequired
    Show 6 child attributes
    • currentPagenumberrequired
    • pageSizenumberrequired
    • totalCountnumberrequired
    • totalPagesnumberrequired
    • hasNextPagebooleanrequired
    • hasPreviousPagebooleanrequired
  • 400 Invalid query parameters
  • 401 Unauthorized - invalid or missing credentials
  • 403 An entity-scoped token asked for an entity it is not pinned to
  • 404 Workspace not found or not accessible with these credentials
  • 500 Internal server error
Node SDK
const page = await prosaic.gstReturns.list();
curl
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

  • entityIdstringrequired

Query parameters

  • statusarray 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.

  • dateFromstring

    Return only GST returns whose period ends on or after this NZ date

  • dateTostring

    Return only GST returns whose period starts on or before this NZ date

  • dueAfterstring

    Return only GST returns due on or after this NZ date

  • dueBeforestring

    Return only GST returns due on or before this NZ date

  • includeFutureDraftsstring

    Include draft returns whose period has not started yet (default false)

    One of: false, true

  • pageinteger

    Page number (default 1)

  • pageSizeinteger

    Items per page (default 100)

Responses

200 Successful response

  • dataarray of objectsrequired
    Show 15 child attributes
    • idstringrequired
    • entityIdstringrequired
    • namestringrequired
    • descriptionstringrequired
    • statusstringrequired

      One of: rejected, completed, draft, finalised, filed, filed_externally, accepted, awaiting_payment

    • dateFromstringrequired
    • dateTostringrequired
    • dueDatestringrequired
    • isOverduebooleanrequired
    • netGstPositionnumberrequirednullable
    • unreconciledTransactionCountnumberrequired
    • hasAmendmentbooleanrequired
    • finalisedAtstringrequirednullable
    • irdFiledAtstringrequirednullable
    • updatedAtstringrequired
  • paginationobjectrequired
    Show 6 child attributes
    • currentPagenumberrequired
    • pageSizenumberrequired
    • totalCountnumberrequired
    • totalPagesnumberrequired
    • hasNextPagebooleanrequired
    • hasPreviousPagebooleanrequired
  • 400 Invalid query parameters
  • 401 Unauthorized - invalid or missing credentials
  • 404 Entity not found or not accessible with these credentials
  • 500 Internal server error
Node SDK
const page = await prosaic.gstReturns.listForEntity(entityId);
curl
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

  • entityIdstringrequired
  • gstReturnIdstringrequired

Responses

200 Successful response

  • dataobjectrequired
    Show 30 child attributes
    • amountsSourcestringrequired

      One of: finalised, calculated

    • totalSalesAndIncomenumberrequirednullable
    • zeroRatedSuppliesnumberrequirednullable
    • netGstSalesAndIncomenumberrequirednullable
    • totalGstSalesAndIncomenumberrequirednullable
    • debitAdjustmentsnumberrequirednullable
    • lateClaimsAmountnumberrequirednullable
    • lateClaimsTypestringrequirednullable

      One of: sales, purchases

    • totalDebitAdjustmentsnumberrequirednullable
    • totalGstCollectednumberrequirednullable
    • totalPurchasesAndExpensesnumberrequirednullable
    • totalGstCreditsOnPurchasesAndExpensesnumberrequirednullable
    • creditAdjustmentsnumberrequirednullable
    • totalCreditAdjustmentsnumberrequirednullable
    • totalGstCreditnumberrequirednullable
    • idstringrequired
    • entityIdstringrequired
    • namestringrequired
    • descriptionstringrequired
    • statusstringrequired

      One of: rejected, completed, draft, finalised, filed, filed_externally, accepted, awaiting_payment

    • dateFromstringrequired
    • dateTostringrequired
    • dueDatestringrequired
    • isOverduebooleanrequired
    • netGstPositionnumberrequirednullable
    • unreconciledTransactionCountnumberrequired
    • hasAmendmentbooleanrequired
    • finalisedAtstringrequirednullable
    • irdFiledAtstringrequirednullable
    • updatedAtstringrequired
  • metaobject
    Show 1 child attribute
    • countnumberrequired
  • 400 Malformed GST return id
  • 401 Unauthorized - invalid or missing credentials
  • 404 No such GST return for this entity
  • 500 Internal server error
Node SDK
const { data } = await prosaic.gstReturns.retrieve(entityId, gstReturnId);
curl
curl https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/gst-returns/$GST_RETURN_ID \
  -H "Authorization: Bearer $PROSAIC_API_KEY"