All API resources
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
/api/public/v1/gst-returnsSDK: 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
entityIdstringReturn only GST returns for this entity
statusarray of stringsReturn only GST returns in these lifecycle statuses. Repeatable, and a comma-separated list means the same thing —
?status=draft&status=filedand?status=draft,filedare 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 thancompleted.dateFromstringReturn only GST returns whose period ends on or after this NZ date
dateTostringReturn only GST returns whose period starts on or before this NZ date
dueAfterstringReturn only GST returns due on or after this NZ date
dueBeforestringReturn only GST returns due on or before this NZ date
includeFutureDraftsstringInclude draft returns whose period has not started yet (default false)
One of:
false,truepageintegerPage number (default 1)
pageSizeintegerItems per page (default 100)
Responses
200 Successful response
dataarray of objectsrequiredShow 15 child attributesHide child attributes
idstringrequiredentityIdstringrequirednamestringrequireddescriptionstringrequiredstatusstringrequiredOne of:
rejected,completed,draft,finalised,filed,filed_externally,accepted,awaiting_paymentdateFromstringrequireddateTostringrequireddueDatestringrequiredisOverduebooleanrequirednetGstPositionnumberrequirednullableunreconciledTransactionCountnumberrequiredhasAmendmentbooleanrequiredfinalisedAtstringrequirednullableirdFiledAtstringrequirednullableupdatedAtstringrequired
paginationobjectrequiredShow 6 child attributesHide child attributes
currentPagenumberrequiredpageSizenumberrequiredtotalCountnumberrequiredtotalPagesnumberrequiredhasNextPagebooleanrequiredhasPreviousPagebooleanrequired
400Invalid query parameters401Unauthorized - invalid or missing credentials403An entity-scoped token asked for an entity it is not pinned to404Workspace not found or not accessible with these credentials500Internal server error
const page = await prosaic.gstReturns.list();curl https://app.prosaic.works/api/public/v1/gst-returns \
-H "Authorization: Bearer $PROSAIC_API_KEY"List GST returns for an entity
/api/public/v1/entities/{entityId}/gst-returnsSDK: 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 stringsReturn only GST returns in these lifecycle statuses. Repeatable, and a comma-separated list means the same thing —
?status=draft&status=filedand?status=draft,filedare 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 thancompleted.dateFromstringReturn only GST returns whose period ends on or after this NZ date
dateTostringReturn only GST returns whose period starts on or before this NZ date
dueAfterstringReturn only GST returns due on or after this NZ date
dueBeforestringReturn only GST returns due on or before this NZ date
includeFutureDraftsstringInclude draft returns whose period has not started yet (default false)
One of:
false,truepageintegerPage number (default 1)
pageSizeintegerItems per page (default 100)
Responses
200 Successful response
dataarray of objectsrequiredShow 15 child attributesHide child attributes
idstringrequiredentityIdstringrequirednamestringrequireddescriptionstringrequiredstatusstringrequiredOne of:
rejected,completed,draft,finalised,filed,filed_externally,accepted,awaiting_paymentdateFromstringrequireddateTostringrequireddueDatestringrequiredisOverduebooleanrequirednetGstPositionnumberrequirednullableunreconciledTransactionCountnumberrequiredhasAmendmentbooleanrequiredfinalisedAtstringrequirednullableirdFiledAtstringrequirednullableupdatedAtstringrequired
paginationobjectrequiredShow 6 child attributesHide child attributes
currentPagenumberrequiredpageSizenumberrequiredtotalCountnumberrequiredtotalPagesnumberrequiredhasNextPagebooleanrequiredhasPreviousPagebooleanrequired
400Invalid query parameters401Unauthorized - invalid or missing credentials404Entity not found or not accessible with these credentials500Internal server error
const page = await prosaic.gstReturns.listForEntity(entityId);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
/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
entityIdstringrequiredgstReturnIdstringrequired
Responses
200 Successful response
dataobjectrequiredShow 30 child attributesHide child attributes
amountsSourcestringrequiredOne of:
finalised,calculatedtotalSalesAndIncomenumberrequirednullablezeroRatedSuppliesnumberrequirednullablenetGstSalesAndIncomenumberrequirednullabletotalGstSalesAndIncomenumberrequirednullabledebitAdjustmentsnumberrequirednullablelateClaimsAmountnumberrequirednullablelateClaimsTypestringrequirednullableOne of:
sales,purchasestotalDebitAdjustmentsnumberrequirednullabletotalGstCollectednumberrequirednullabletotalPurchasesAndExpensesnumberrequirednullabletotalGstCreditsOnPurchasesAndExpensesnumberrequirednullablecreditAdjustmentsnumberrequirednullabletotalCreditAdjustmentsnumberrequirednullabletotalGstCreditnumberrequirednullableidstringrequiredentityIdstringrequirednamestringrequireddescriptionstringrequiredstatusstringrequiredOne of:
rejected,completed,draft,finalised,filed,filed_externally,accepted,awaiting_paymentdateFromstringrequireddateTostringrequireddueDatestringrequiredisOverduebooleanrequirednetGstPositionnumberrequirednullableunreconciledTransactionCountnumberrequiredhasAmendmentbooleanrequiredfinalisedAtstringrequirednullableirdFiledAtstringrequirednullableupdatedAtstringrequired
metaobjectShow 1 child attributeHide child attributes
countnumberrequired
400Malformed GST return id401Unauthorized - invalid or missing credentials404No such GST return for this entity500Internal server error
const { data } = await prosaic.gstReturns.retrieve(entityId, gstReturnId);curl https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/gst-returns/$GST_RETURN_ID \
-H "Authorization: Bearer $PROSAIC_API_KEY"