Retrieve an invoice run

Operation ID: getInvoiceRun

Group: Accounting › Invoice Runs

Open in the interactive reference

GET /accounting/invoice-runs/{id}

Read-only: Reads and returns; changes nothing.

Retrieves an invoice run. Use the invoice run's id, not its invoiceRunNumber.

The response shows what the run covered, its status, the invoices it created and the lines that failed.

'completed' means every selected line was invoiced. 'error' means the run failed, and 'errors' lists the lines that failed. Check 'status' rather than 'invoicesCreated', because a 'completeAndError' run has created invoices and also has failed lines.

If the run's job stops without finishing, for example because it was canceled or lost, this endpoint reports 'error'. The saved status stays 'running', and GET accounting/invoice-runs returns that saved status.

To start a run, use POST accounting/invoice-runs.

Parameters

Name In Type Required Description
Api-Version header string · 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 of the invoice run you want to retrieve.

Response

200 Success

Under data (getInvoiceRunOutput):

Field Type Required Description
data object yes The requested invoice run. Example: {"id":"1c9d6b73-4a20-4e58-8f31-7b2e0c4a9d15","invoiceRunNumber":"ISR-1042","status":"completeAndError","invoicesCreated":2,"startedAt":"2026-09-30T08:14:22.000Z","finishedAt":"2026-09-30T08:15:07.000Z","trigger":"immediately","scope":["all"],"entityId":"6f1b2a84-3d97-4c25-8e60-9a4f0b7d1c53","salesOrderId":"8f14e45f-ceea-467a-9f6b-2c1d0e5a7b39","customerId":"d41d8cd9-8f00-4b20-a204-9800998ecf84","invoices":[{"id":"a2c5e881-4f37-4b09-9d16-8e3b0c7a5d24","invoiceNumber":"INV-20841","totalAmount":"1210.00","currency":"EUR"}],"errors":[{"type":"taxCode","detail":"No tax code resolves for product line SO-114-3 in DE.","customerId":"d41d8cd9-8f00-4b20-a204-9800998ecf84"}]}.
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<any> 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<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 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<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. 
{
  "data": {
    "data": {
      "id": "1c9d6b73-4a20-4e58-8f31-7b2e0c4a9d15",
      "invoiceRunNumber": "ISR-1042",
      "status": "completeAndError",
      "invoicesCreated": 2,
      "startedAt": "2026-09-30T08:14:22.000Z",
      "finishedAt": "2026-09-30T08:15:07.000Z",
      "trigger": "immediately",
      "scope": [
        "all"
      ],
      "entityId": "6f1b2a84-3d97-4c25-8e60-9a4f0b7d1c53",
      "salesOrderId": "8f14e45f-ceea-467a-9f6b-2c1d0e5a7b39",
      "customerId": "d41d8cd9-8f00-4b20-a204-9800998ecf84",
      "invoices": [
        {
          "id": "a2c5e881-4f37-4b09-9d16-8e3b0c7a5d24",
          "invoiceNumber": "INV-20841",
          "totalAmount": "1210.00",
          "currency": "EUR"
        }
      ],
      "errors": [
        {
          "type": "taxCode",
          "detail": "No tax code resolves for product line SO-114-3 in DE.",
          "customerId": "d41d8cd9-8f00-4b20-a204-9800998ecf84"
        }
      ]
    }
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}

Errors

Code Status
NOT_FOUND 400

Statuses