Skip to main content

list-invoices 

dci list-invoices [flags]

Returns a list of all the current and historical invoices for your organization. Invoices are returned in reverse chronological order by default. Cancelled invoices and credit memos are excluded unless you filter by status:CANCELED.

CLI default view

dci list-invoices presents a curated table by default:

  • Columns: invoice (from id; a clickable link to the invoice in the DoiT console in interactive terminals), platform, issued (from invoiceDate), due (from dueDate; blank when the invoice carries no due date, e.g. credit memos), total and balance (with the invoice's currency symbol), and status.
  • --output json and explicit -C/--fields selections return the raw fields documented below.

Examples​

# Current and historical invoices, newest first.
dci list-invoices
# Invoices issued on or after 1 August 2026 00:00 UTC (epoch milliseconds).
dci list-invoices --min-creation-time 1785542400000
# Invoices still open, searched client-side across every page.
dci list-invoices --search OPEN
# Every page as JSON, for scripts.
dci list-invoices --all --output json

Flags​

FlagTypeDefaultExampleDescription
--max-resultsinteger (int64)50The maximum number of results to return in a single page. Leverage the page tokens to iterate through the entire collection.
--page-tokenstringPage token, returned by a previous call, to request the next page of results
--filterstringSupported keys: platform (an invoice platform), dueDate (milliseconds since the POSIX epoch), and status (OPEN, PAST DUE, PAID, or CANCELED). Only one status value is applied per request. Cancelled invoices and credit memos are returned only with status:CANCELED, and every other request excludes them.
--min-creation-timeinteger (int64)Min value for the invoice creation time, in milliseconds since the POSIX epoch. If set, only invoices created after or at this timestamp are returned.
--max-creation-timeinteger (int64)Max value for the invoice creation time, in milliseconds since the POSIX epoch. If set, only invoices created before or at this timestamp are returned.

Every command also accepts the CLI-wide flags for output shaping — see Output formats and Table output options.

Output​

OK - All available invoices returned.

By default dci renders the result as a table. Use --output json to get the full structure described below — see Output formats.

FieldTypeDescription
invoicesarray of objectArray of Invoices
invoices[].idstringInvoice number, identifying the invoice.
invoices[].invoiceDateinteger (int64)The time when this invoice was issued, in milliseconds since the epoch.
invoices[].platformstringPlatform identifier for invoice source. One of: "google-cloud", "amazon-web-services", "microsoft-azure", "g-suite", "office-365", "superquery", "looker", "navigator", "solve".
invoices[].dueDateinteger (int64)The last day to pay the invoice, in milliseconds since the epoch
invoices[].statusstringStatus of the invoice. CANCELED takes precedence over the payment status. One of: "OPEN", "PAST DUE", "PAID", "CANCELED".
invoices[].totalAmountnumber (double)Total invoiced amount
invoices[].balanceAmountnumber (double)Invoice balance to be paid
invoices[].currencystringCurrency code for monetary values. One of: "USD", "ILS", "EUR", "AUD", "CAD", "GBP", "DKK", "NOK", "SEK", "BRL", "SGD", "MXN", ….
invoices[].urlstringLink to invoice details page in the DoiT console. You can download the PDF invoice from the invoice details page, or programmatically via the getInvoicePdf operation (GET /billing/v1/invoices/\{id\}/pdf).
pageTokenstringPage token. Can be used to request the next page of results.
rowCountinteger (int64)Invoice rows count
Raw JSON schema
{
  "type": "object",
  "properties": {
    "invoices": {
      "type": "array",
      "description": "Array of Invoices",
      "items": {
        "type": "object",
        "description": "Summary information about an invoice.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Invoice number, identifying the invoice."
          },
          "invoiceDate": {
            "type": "integer",
            "description": "The time when this invoice was issued, in milliseconds since the epoch.",
            "format": "int64"
          },
          "platform": {
            "type": "string",
            "description": "Platform identifier for invoice source.",
            "enum": [
              "google-cloud",
              "amazon-web-services",
              "microsoft-azure",
              "g-suite",
              "office-365",
              "superquery",
              "looker",
              "navigator",
              "solve"
            ]
          },
          "dueDate": {
            "type": "integer",
            "description": "The last day to pay the invoice, in milliseconds since the epoch",
            "format": "int64"
          },
          "status": {
            "type": "string",
            "description": "Status of the invoice. `CANCELED` takes precedence over the payment status.",
            "enum": [
              "OPEN",
              "PAST DUE",
              "PAID",
              "CANCELED"
            ]
          },
          "totalAmount": {
            "type": "number",
            "description": "Total invoiced amount",
            "format": "double"
          },
          "balanceAmount": {
            "type": "number",
            "description": "Invoice balance to be paid",
            "format": "double"
          },
          "currency": {
            "description": "Currency code for monetary values.",
            "type": "string",
            "enum": [
              "USD",
              "ILS",
              "EUR",
              "AUD",
              "CAD",
              "GBP",
              "DKK",
              "NOK",
              "SEK",
              "BRL",
              "SGD",
              "MXN",
              "CHF",
              "MYR",
              "TWD",
              "EGP",
              "ZAR",
              "JPY",
              "IDR",
              "AED",
              "THB",
              "COP"
            ]
          },
          "url": {
            "type": "string",
            "description": "Link to [invoice details page](https://help.doit.com/docs/billing/invoices-and-payments/managing-invoices) in the DoiT console. You can download the PDF invoice from the invoice details page, or programmatically via the `getInvoicePdf` operation (`GET /billing/v1/invoices/{id}/pdf`)."
          }
        }
      }
    },
    "pageToken": {
      "type": "string",
      "description": "Page token. Can be used to request the next page of results."
    },
    "rowCount": {
      "type": "integer",
      "description": "Invoice rows count",
      "format": "int64"
    }
  }
}

Errors​

On failure, dci prints a single error message — with a hint when one is available — and exits with a typed code your scripts can branch on. See Errors and exit codes for the full contract.

HTTP status to exit code mapping
HTTP statusExit codeError codeMeaning
40030VALIDATION_ERRORThe arguments or request body were rejected. Review the command's flags and payload.
40110AUTHENTICATION_FAILEDNot signed in, or the API token is invalid. Run dci login or check DCI_API_KEY.
40311PERMISSION_DENIEDThe DoiT user or the active customer context does not have access.
40420RESOURCE_NOT_FOUNDThe requested resource does not exist. Check the identifier argument.
50040API_SERVER_ERRORThe API failed to process the request. Retryable; contact DoiT support if it persists.

Aliases: listinvoices