Returns one invoice run and its outcome.

GET /accounting/invoice-runs/{id}

Group: Accounting › Invoice Runs · Operation ID: getInvoiceRun

Reads one invoice run: what it was scoped to, where it got to, the invoices it created and the lines that failed. This is the poll half of POST accounting/invoice-runs.

Branch on 'status'. 'created' and 'running' mean keep polling. 'completed' means every selected line was billed. 'error' means nothing was billed and 'errors' says why. 'completeAndError' means some invoices were created and some lines failed, so check 'status' rather than assuming success once 'invoicesCreated' is non-zero.

'status' is corrected against the worker running the job. The stored status settles only when the run records a finish time, which a killed, canceled or lost worker never does, so such a run would otherwise read 'running' without end. Where that has happened this endpoint reports 'error', so a polling loop always ends.

No total amount is published for the run. Each entry in 'invoices' has its own 'totalAmount' and 'currency' instead, because a run can create invoices in several currencies and one summed figure would add unlike units.

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.
id path string yes The unique identifier for the invoice run to return.

Response

200 Success

Under data (getInvoiceRunOutput):

Field Type Required Description
data object yes The requested invoice run.
data.id string yes The unique identifier for the invoice run.
data.invoiceRunNumber string no The invoice run number, for example 'ISR-1042'. Absent while none has been assigned.
data.status string yes The execution status of the run. Possible values: 'created', 'running', 'completed', 'error', 'completeAndError'. Keep polling on 'created' and 'running'. 'completeAndError' means some invoices were created and some lines failed.
data.invoicesCreated number yes The number of invoices the run has created.
data.startedAt string no The date and time the run was created, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
data.finishedAt string 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.
data.lastModifiedDate string no The date and time the invoice run record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
data.trigger string no What started the run. Possible values: 'immediately', 'daily', 'monthly'. 'immediately' is an ad-hoc run. 'daily' and 'monthly' are scheduled.
data.scope array of string, one of "all", "oneTimeAndRecurring", "usageInArrears", "billableProducts" yes The line types the run billed.
data.entityId string no The legal entity billed. See id on GET base/entities.
data.salesOrderId string no The sales order billed. Present on a sales-order-scoped run. See id on GET accounting/sales-orders/:id.
data.customerId string no The customer billed. Absent on a run that created no invoice and recorded no error. See id on GET accounting/customers/:id.
data.progress object no The run's own progress reporting while it works. It is advisory: absent before the run starts reporting, and never a substitute for 'status'.
data.progress.title string no The phase the run is in, for example preparing data or creating invoices.
data.progress.message string no Further detail on the current phase, when the run supplies any.
data.progress.progress number no The number of items processed so far in the current phase.
data.progress.total number no The number of items to process in the current phase.
data.invoices array of object yes The invoices the run created. Each has its own currency, so there is no summed run total.
data.invoices[].id string yes The unique identifier for the invoice. See id on GET accounting/invoices/:id.
data.invoices[].invoiceNumber string no The invoice number, for example 'INV-20841'.
data.invoices[].totalAmount string (decimal) no The total amount of the invoice including tax, in the currency named by 'currency'.
data.invoices[].currency string no The currency of the invoice. Format ISO 4217, for example 'EUR'.
data.errors array of object yes The lines the run could not bill, one entry each. A non-empty array with a non-zero 'invoicesCreated' is the 'completeAndError' outcome.
data.errors[].type string yes Why the line could not be billed. Possible values: 'system', 'avalaraAddress', 'taxCode', 'none', 'taxCalculation', 'vatEntity', 'accountConfig', 'vatCustomer', 'invoiceSetupIncomplete', 'invoiceDelivery'.
data.errors[].detail string no A description of why the line failed.
data.errors[].customerId string no The customer the failing line belongs to. See id on GET accounting/customers/:id.

Errors

Code Status
NOT_FOUND 400

Statuses