# List invoices List invoices for the authenticated tenant. Returns a paginated list of invoices and credit notes. Filters combine with AND. Each item includes counterparty display fields and computed overdue flags. Payment-schedule installments are not included on the list; use Get invoice. - HTTP method: `GET` - Path: `/api/v1/invoices` - URL: `https://api.invunion.com/api/v1/invoices` - Required scope: `invoices:read` - HTML docs: https://www.invunion.com/knowledge-base/api/list-invoices/ - Markdown docs: https://www.invunion.com/knowledge-base/api/list-invoices.md ## Query parameters | Name | Type | Required | Description | Allowed values | Example | | --- | --- | --- | --- | --- | --- | | `page` | integer | optional | Page number. Default 1. | | `1` | | `pageSize` | integer | optional | Page size. Default 20, maximum 100. | | `20` | | `sortBy` | string, no maximum | optional | Sort column. Default invoice_date. | `invoice_number`, `invoice_date`, `due_date`, `amount_incl_vat`, `recovery_percent`, `settled_amount`, `open_amount`, `vat_amount`, `status`, `created_at` | | | `sortOrder` | string, no maximum | optional | Sort direction. Default desc. | `asc`, `desc` | | | `status` | string, no maximum | optional | Single status or comma-separated list. overdue is computed from open amount past due, not only stored status. unmatched means unpaid or overdue. | `unpaid`, `partial`, `paid`, `cancelled`, `overdue`, `unmatched` | | | `type` | string, no maximum | optional | issued (you billed) or received (you were billed). | `issued`, `received` | | | `kind` | string, no maximum | optional | Invoice or credit note. | `invoice`, `credit_note` | | | `counterpartyId` | string, no maximum | optional | Filter by counterparty code (`account_code`). | | `CPT-042` | | `paymentMethod` | string, no maximum | optional | Expected payment channel. | `card`, `transfer`, `direct_debit`, `cash`, `check`, `crypto`, `other` | | | `search` | string, max 100 | optional | Case-insensitive match on invoice_number, recipient_name, customer_name, external_reference, or description. | | `INV-2026` | | `externalReference` | string, max 255 | optional | Exact external reference. | | `LC-SO-9081` | | `startDate` | string, no maximum | optional | Inclusive start of invoice_date (YYYY-MM-DD). | | `2026-09-01` | | `endDate` | string, no maximum | optional | Inclusive end of invoice_date (YYYY-MM-DD). | | `2026-09-30` | | `dueStartDate` | string, no maximum | optional | Inclusive start of due_date (YYYY-MM-DD). | | `2026-09-01` | | `dueEndDate` | string, no maximum | optional | Inclusive end of due_date (YYYY-MM-DD). | | `2026-10-31` | | `minRecovery` | number | optional | Minimum recovery_percent (0-100). | | `0` | | `maxRecovery` | number | optional | Maximum recovery_percent (0-100). | | `100` | | `hasOpen` | boolean | optional | If true, only invoices with open_amount > 0. | `true`, `false` | | | `overdue` | boolean | optional | If true, only invoices past their next due date with an open amount. | `true`, `false` | | ## Errors | Error | HTTP code | Description | | --- | --- | --- | | `Missing Bearer token` | `401` | The Authorization header is missing or is not a Bearer token. | | `Invalid or revoked API key` | `401` | The API key is unknown, malformed, expired, or has been revoked. | | `API key is missing scope invoices:read` | `403` | The key does not include invoices:read. A write scope does not imply the matching read scope. | | `Too many requests, please try again later` | `429` | Wait and retry. The Retry-After header is the number of seconds to wait. | | `Invalid query parameters` | `400` | A query value failed validation. details lists field and message. | | `Internal server error` | `500` | Unexpected server error. The JSON body includes correlationId. Retry with backoff. | ## Request (curl) ```bash curl --request GET \ --url https://api.invunion.com/api/v1/invoices?page=1&pageSize=20&type=issued \ --header 'accept: application/json' \ --header 'authorization: Bearer uk_live_YOUR_API_KEY' ``` ## Request (Python) ```python import requests url = "https://api.invunion.com/api/v1/invoices?page=1&pageSize=20&type=issued" headers = { "Accept": "application/json", "Authorization": "Bearer uk_live_YOUR_API_KEY", } response = requests.get(url, headers=headers) print(response.json()) ``` ## Request (Ruby) ```ruby require 'net/http' require 'json' require 'uri' uri = URI("https://api.invunion.com/api/v1/invoices?page=1&pageSize=20&type=issued") http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = true request = Net::HTTP::Get.new(uri) request['Accept'] = 'application/json' request['Authorization'] = 'Bearer uk_live_YOUR_API_KEY' response = http.request(request) puts response.body ``` ## Request (JavaScript) ```javascript const response = await fetch("https://api.invunion.com/api/v1/invoices?page=1&pageSize=20&type=issued", { method: "GET", headers: { "Accept": "application/json", "Authorization": "Bearer uk_live_YOUR_API_KEY" }, }); const data = await response.json(); ``` ## Request (Go) ```go package main import ( "fmt" "io" "net/http" ) func main() { req, err := http.NewRequest("GET", "https://api.invunion.com/api/v1/invoices?page=1&pageSize=20&type=issued", nil) if err != nil { panic(err) } req.Header.Set("Accept", "application/json") req.Header.Set("Authorization", "Bearer uk_live_YOUR_API_KEY") resp, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer resp.Body.Close() body, _ := io.ReadAll(resp.Body) fmt.Println(string(body)) } ``` ## Request (Node) ```javascript const response = await fetch("https://api.invunion.com/api/v1/invoices?page=1&pageSize=20&type=issued", { method: "GET", headers: { "Accept": "application/json", "Authorization": "Bearer uk_live_YOUR_API_KEY" }, }); console.log(await response.json()); ``` ## Success (200) ```json { "success": true, "data": { "items": [ { "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "tenant_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "counterparty_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "invoice_number": "INV-2026-0042", "kind": "invoice", "invoice_type": "issued", "status": "partial", "currency": "EUR", "amount_excl_vat": 10000, "vat_amount": 2000, "amount_incl_vat": 12000, "settled_amount": 1000, "open_amount": 11000, "recovery_percent": 8.33, "invoice_date": "2026-09-01T00:00:00.000Z", "due_date": "2026-10-01T00:00:00.000Z", "payment_expected_date": "2026-10-01T00:00:00.000Z", "payment_term_days": null, "recipient_name": "Leones Cars", "customer_name": "Leones Cars", "description": "Fleet maintenance — September 2026", "external_reference": "LC-SO-9081", "counterparty_name_display": "Leones Cars", "is_overdue": false, "next_due_date": "2026-10-01", "created_at": "2026-09-01T10:00:00.000Z", "updated_at": "2026-09-12T09:00:00.000Z" }, { "id": "8ead24f5-4b17-4092-db14-21508c3ea6d4", "tenant_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "counterparty_id": "4b7a91c2-18e4-4d6f-a8c1-9e2d5f0b73a1", "invoice_number": "INV-2026-0043", "kind": "invoice", "invoice_type": "received", "status": "paid", "currency": "USD", "amount_excl_vat": 3500, "vat_amount": 700, "amount_incl_vat": 4200, "settled_amount": 4200, "open_amount": 0, "recovery_percent": 100, "invoice_date": "2026-08-25T00:00:00.000Z", "due_date": "2026-09-09T00:00:00.000Z", "payment_expected_date": "2026-09-09T00:00:00.000Z", "payment_term_days": null, "recipient_name": "Invunion Demo", "customer_name": "Grove Street Garage", "description": "Spare parts — August 2026", "external_reference": "PO-1904", "counterparty_name_display": "Grove Street Garage", "is_overdue": false, "next_due_date": "2026-09-09", "created_at": "2026-08-25T11:20:00.000Z", "updated_at": "2026-09-09T00:00:00.000Z" } ], "total": 2, "page": 1, "pageSize": 20, "hasMore": false } } ```