Invoice Runs

GET /accounting/invoice-runs

Group: Accounting › Invoice Runs · Operation ID: invoiceRuns

Returns a list of invoice runs. 'status' and 'scope' differ in type from GET accounting/invoice-runs/:id, which the endpoint description explains.

Lists invoice runs: what each was scoped to, when it ran and how it came out. Use it to audit billing activity or to find a run whose id you lost. Read a single run with GET accounting/invoice-runs/:id, which has the invoices and errors this list cannot.

Two fields differ from what GET accounting/invoice-runs/:id publishes. 'status' here is the stored value, not the corrected one, so a run whose worker was killed or lost reads 'running' without end, where the single-run endpoint reports 'error' instead. Treat any row that has been 'running' far longer than a run should take as unsettled, and read it through the single-run endpoint. 'scope' here is the raw stored text, the billed line types joined by semicolons into one string such as 'all', where the single-run endpoint publishes an array.

There is no 'customerId'. To find a customer's billing history, list invoices by customer instead.

Open in the interactive reference

Parameters

Name	In	Type	Required	Description
`Api-Version`	header	`"v1"`	yes	The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version `v1`.

Query surface

id — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
invoiceRunNumber — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
trigger — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
entityId — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
salesOrderId — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
startedAt — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
finishedAt — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
lastModifiedDate — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
Orderable: invoiceRunNumber, startedAt, finishedAt, lastModifiedDate
Selectable: id, invoiceRunNumber, status, invoicesCreated, trigger, scope, entityId, salesOrderId, startedAt, finishedAt, lastModifiedDate

Response

200 Success

Under data, an array of invoiceRunsRow:

Field	Type	Required	Description
`id`	string	no	The unique identifier for the invoice run.
`invoiceRunNumber`	string or null	no	The invoice run number, for example 'ISR-1042'.
`status`	string or null	no	The execution status of the run, as stored rather than corrected, so a run whose worker was killed or lost reads 'running' without end. GET accounting/invoice-runs/:id reports 'error' for such a run instead. Possible values: 'created', 'running', 'completed', 'error', 'completeAndError'.
`invoicesCreated`	number or null	no	The number of invoices the run created.
`trigger`	string or null	no	What started the run. Possible values: 'immediately', 'daily', 'monthly'.
`scope`	string or null	no	The line types billed, as the raw stored text: the billed line types joined by semicolons into one string, such as 'all'. GET accounting/invoice-runs/:id publishes this as an array instead.
`entityId`	string or null	no	The legal entity billed. See id on GET base/entities.
`salesOrderId`	string or null	no	The sales order billed. Absent on a customer- or entity-scoped run. See id on GET accounting/sales-orders/:id.
`startedAt`	string (date-time) or null	no	The date and time the run was created, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
`finishedAt`	string (date-time) or null	no	The date and time the run finished, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. Absent while the run is still working, and on a run whose worker stopped without recording one.
`lastModifiedDate`	string (date-time) or null	no	The date and time the invoice run record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.

Statuses

400 — Invalid request or business failure
401 — Missing or invalid access token
403 — Not authorized
404 — Not found
429 — Too many requests
500 — Internal server error