--- title: "Search and page the invoices of the authenticated company." method: GET path: "/core/v1/invoices" tags: ["Finance"] --- # Search and page the invoices of the authenticated company. `GET /core/v1/invoices` ## Request - Base URL: `https://api.klara.ch` - URL: `https://api.klara.ch/core/v1/invoices` - Auth: one of: - API key in header `X-API-KEY` - HTTP bearer Returns a page of the company's invoices, newest first, with optional free-text search (search-key) and status filter (status). Each row is an InvoiceSummary — a flat projection carrying the identity, amounts, dates, customer and both status fields. Retrieve the full document, including order items and attachments, with GET /core/v1/invoices/{id}.

Paging. Walk the collection with offset and limit: iterate offset=0, limit, 2×limit, … until a response returns fewer than limit rows. Ordering defaults to sort-field=ID, sort-direction=DESC, which is unique per row and therefore stable across pages — if you sort by a non-unique field instead (for example LAST_MODIFIED), rows sharing a value may shift between pages.

The two status fields mean different things. status on a row is the invoice document status; bookingStatus is the accounting payment state of its open position, supplied by luz_accounting. A fully paid invoice reads status: INVOICED with bookingStatus: PAID.

The status query parameter is the KLARA invoice-overview filter, not an equality filter on the row's status field. It matches on both the document status and the payment state, exactly as the KLARA invoice list does:Use booking-status to filter on the payment state precisely. It matches the row's bookingStatus field and nothing else, accepts the full set — including PARTLY_PAID and PARTLY_CLEARED, which status cannot express — and combines with status: ?status=INVOICED&booking-status=OPEN is the exact way to ask for "invoiced and not yet paid". Invoices that carry no booking at all (DRAFT, cancelled) have no payment state and are excluded whenever booking-status is given.

Two further behaviours worth knowing. Invoices whose order has been archived are excluded. And status=OPEN — only that one value — applies its payment-state check after the page is cut, so such a page can contain fewer than limit rows while the offsets stay stable; keep paging rather than treating a short page as the end. booking-status=OPEN does not behave that way: it is part of the query, so a short page really is the last page. Prefer it.

Read-only and idempotent. Authentication is API key + bearer JWT; the caller must hold the FINANCE permission on the company resolved from the JWT, otherwise the endpoint returns 403. ## Query parameters - `booking-status` 'OPEN' | 'PARTLY_PAID' | 'PAID' | 'PARTLY_CLEARED' | 'CLEARED' - `limit` integer - `offset` integer - `search-key` string - `sort-direction` 'ASC' | 'DESC' - `sort-field` string - `status` 'DRAFT' | 'INVOICED' | 'SENT' | 'PAID' | 'OPEN' | 'CLEARED' | 'CANCELLED' ## Response `200` A page of invoices. Empty array when nothing matches. - InvoiceSummary[] - `id` integer: Numeric primary key. Pass this to GET /core/v1/invoices/{id} to retrieve the full document. - `invoiceCode` string: Human-readable invoice code, unique per company. - `invoiceNumber` integer: Sequential invoice number. - `orderNumber` integer: Order number of the invoice's order. - `subject` string: Invoice subject / title. - `status` string: Invoice document status. One of DRAFT, INVOICED, PAID, CANCELLED. Note that SENT is reported as INVOICED for non-negative amounts, and that the status query parameter additionally accepts the payment-state values OPEN, PAID and CLEARED, which are matched against bookingStatus rather than against this field. - `bookingStatus` string: Accounting payment state of the invoice's open position, from luz_accounting: OPEN, PARTLY_PAID, PAID, PARTLY_CLEARED or CLEARED. Absent for invoices that carry no booking (DRAFT, cancelled). - `invoiceType` string: Invoice type: MANUAL or RECURRING. - `amount` number: Invoice total, on the same basis as Invoice.amount. - `documentDate` string, date: Invoice document date (ISO 8601). - `paymentDate` string, date: Payment due date (ISO 8601). - `bookingDueDate` string, date: Booking due date returned by accounting. - `customerId` integer: Id of the customer the invoice was issued to. - `customerName` string: Display name of the customer — the company name for a COMPANY customer, first and last name for a PERSON. - `customerType` string: Customer type: COMPANY or PERSON. - `bookingNumbers` string: Accounting booking numbers created for this invoice, comma-separated. Empty while the invoice is not booked. - `lastModified` string, date-time: Last modification timestamp. ## Other responses - `400`: Invalid filter or paging parameter — an unknown status, an unknown sort-field, a sort-direction other than ASC/DESC, a negative offset, or a limit outside 1–100.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. - `401`: No Authorization header found or invalid token

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. - `403`: The current user is not allowed to access this company data

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. - `429`: API rate limit exceeded

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. - `500`: Something went wrong on our side while processing the request. Please kindly contact our support.

Failures detected by a downstream service carry that service's own code, which this reference does not enumerate, so the code field may hold a value not documented here. Treat an unrecognised code as a generic failure of the status it arrives with, and do not branch on a code this reference does not list. --- [API](https://skmtc.dev/klara/apis/klara-public-api.md) · [All operations](https://skmtc.dev/klara/apis/klara-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/klara/apis/klara-public-api/revisions/490b1a879fc2?raw)