---
title: "List Invoices"
method: GET
path: "/api/autopilot/invoices"
tags: ["autopilot"]
---

# List Invoices

`GET /api/autopilot/invoices`

## Request

- Base URL: `https://api.taxcompass.it` (the document declares no server; this is the origin it was published from)
- URL: `https://api.taxcompass.it/api/autopilot/invoices`
- Auth: HTTP bearer

The caller's invoices, newest first; ``year`` narrows to one tax year.

Unlike ``/incassi``, an absent ``year`` means *every* year rather than the
current one. The ledger is read per year because the estimate it feeds is a
per-year number, whereas the invoice list is a working document set: a draft
written on 28 December and issued in January would vanish from its own list
on New Year's Day if the default narrowed it.

The read polls first (AP-036), so what it returns already reflects anything
SdI answered while no webhook reached us. The poll is bounded and throttled
in the store, and ``year`` is deliberately not passed down to it: a filtered
view is still a whole account's worth of in-flight documents, and letting the
filter decide what converges would make an invoice's status depend on which
tab the user happens to have open.

## Query parameters

- `year` integer, nullable

## Response `200`

Successful Response

- InvoiceRead[]
  - `client_id` string, uuid, nullable
  - `ateco` string, nullable
  - `issue_date` string, date, nullable
  - `due_date` string, date, nullable
  - `causale` string, nullable
  - `lines` InvoiceLineOutput[]
    - `description` string, required
    - `unit_price` string, required
    - `quantity` string
    - `unit` string, nullable
  - `id` string, uuid, required
  - `year` integer, required
  - `number` integer, nullable
  - `doc_type` string
  - `status` 'draft' | 'sending' | 'issued' | 'delivered' | 'not_delivered' | 'rejected' | 'error' | 'imported'
  - `total_amount` string
  - `bollo_applied` boolean
  - `credit_note_of` string, uuid, nullable
  - `client_label` string, nullable
  - `created_at` string, date-time, nullable
  - `updated_at` string, date-time, nullable
  - `payment` InvoicePayment: The payment side of one invoice — computed by ``services.invoice_payments``. Only ever computed on the server, from the ledger: a paid flag on the document would be a second copy of a fact the incassi table already holds, and the two would disagree the first time someone deleted a payment. * ``due`` — the invoice total minus the credit notes *issued* against it (a draft credit note has told the customer nothing yet, so it owes nothing less). * ``credited`` — that credit-note sum. * ``paid`` — net cash collected against this invoice: its own payments plus the refunds recorded against its credit notes (which are stored negative). * ``outstanding`` — what the customer still owes, never below zero. * ``overpaid_by`` — what arrived beyond ``due``, never below zero. * ``last_payment_date`` — the latest *incoming* payment (a refund is not a payment). * ``days_overdue`` — whole days past ``due_date`` while something is still owed; ``None`` when nothing is owed or the invoice has no due date.
    - `state` 'unpaid' | 'partly_paid' | 'paid' | 'overpaid' | 'credited', required
    - `due` string, required
    - `credited` string
    - `paid` string
    - `outstanding` string
    - `overpaid_by` string
    - `last_payment_date` string, date, nullable
    - `days_overdue` integer, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/taxcompass/apis/taxcompass-api.md) · [All operations](https://skmtc.dev/taxcompass/apis/taxcompass-api/llms.txt) · [OpenAPI document](https://skmtc.dev/taxcompass/apis/taxcompass-api/revisions/fef5fc6a9b91?raw)