---
title: "Read Invoice"
method: GET
path: "/api/autopilot/invoices/{invoice_id}"
tags: ["autopilot"]
---

# Read Invoice

`GET /api/autopilot/invoices/{invoice_id}`

## 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/{invoice_id}`
- Auth: HTTP bearer

One invoice, draft or issued. 404 when the id is unknown *or* not the caller's.

Polls for this invoice alone (AP-036) rather than for the whole stale batch:
opening one document is one vendor call, and the rest of the account
converges on the next list read.

Carries ``credit_notes`` (AP-090) — the notes written against this invoice,
oldest first — because the link only matters where the document is being
read: a partially credited invoice is still worth its face value in the list,
and what is left of it is a question asked with the document open. The lookup
is scoped by the same ownership predicate as the read above, so it cannot
become a second way to see somebody else's documents.

## Path parameters

- `invoice_id` string, uuid, required

## Response `200`

Successful Response

- InvoiceDetail: One invoice **plus** the credit notes written against it (AP-090). Only the detail read carries them. The list is a working document set the dashboard pages through, and attaching each row's notes there would cost one query per invoice to render a link the list has no room for; opening the document is exactly the moment "what has been credited off this?" is asked. A credit note read through this route answers with an empty ``credit_notes`` and a set ``credit_note_of``: the store refuses to credit a credit note, so the list is empty by construction rather than by omission.
  - `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
  - `credit_notes` 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)