Search and page the invoices of the authenticated company.
Returns a page of the company's invoices, newest first, with optional free-text search (<code>search-key</code>) and status filter (<code>status</code>). Each row is an <code>InvoiceSummary</code> — a flat projection carrying the identity, amounts, dates, customer and both status fields. Retrieve the full document, including order items and attachments, with <code>GET /core/v1/invoices/{id}</code>.<br/><br/><strong>Paging.</strong> Walk the collection with <code>offset</code> and <code>limit</code>: iterate <code>offset=0, limit, 2×limit, …</code> until a response returns fewer than <code>limit</code> rows. Ordering defaults to <code>sort-field=ID</code>, <code>sort-direction=DESC</code>, which is unique per row and therefore stable across pages — if you sort by a non-unique field instead (for example <code>LAST_MODIFIED</code>), rows sharing a value may shift between pages.<br/><br/><strong>The two status fields mean different things.</strong> <code>status</code> on a row is the invoice <em>document</em> status; <code>bookingStatus</code> is the accounting payment state of its open position, supplied by <code>luz_accounting</code>. A fully paid invoice reads <code>status: INVOICED</code> with <code>bookingStatus: PAID</code>.<br/><br/><strong>The <code>status</code> query parameter is the KLARA invoice-overview filter, not an equality filter on the row's <code>status</code> field.</strong> It matches on both the document status and the payment state, exactly as the KLARA invoice list does:<ul><li><code>DRAFT</code>, <code>CANCELLED</code> — document status only.</li><li><code>INVOICED</code>, <code>SENT</code> — invoiced and still open.</li><li><code>OPEN</code> — invoiced or paid, with <code>bookingStatus=OPEN</code>. Rows come back reading <code>status: INVOICED</code> or <code>PAID</code>, so do not expect the filter value to be echoed in the row.</li><li><code>PAID</code> — <code>bookingStatus</code> of <code>PAID</code> or <code>PARTLY_PAID</code>.</li><li><code>CLEARED</code> — <code>bookingStatus</code> of <code>CLEARED</code> or <code>PARTLY_CLEARED</code> (credit notes).</li></ul><strong>Use <code>booking-status</code> to filter on the payment state precisely.</strong> It matches the row's <code>bookingStatus</code> field and nothing else, accepts the full set — including <code>PARTLY_PAID</code> and <code>PARTLY_CLEARED</code>, which <code>status</code> cannot express — and combines with <code>status</code>: <code>?status=INVOICED&booking-status=OPEN</code> is the exact way to ask for "invoiced and not yet paid". Invoices that carry no booking at all (<code>DRAFT</code>, cancelled) have no payment state and are excluded whenever <code>booking-status</code> is given.<br/><br/><strong>Two further behaviours worth knowing.</strong> Invoices whose order has been archived are excluded. And <code>status=OPEN</code> — only that one value — applies its payment-state check after the page is cut, so such a page can contain fewer than <code>limit</code> rows while the offsets stay stable; keep paging rather than treating a short page as the end. <code>booking-status=OPEN</code> does not behave that way: it is part of the query, so a short page really is the last page. Prefer it.<br/><br/>Read-only and idempotent. Authentication is API key + bearer JWT; the caller must hold the <code>FINANCE</code> permission on the company resolved from the JWT, otherwise the endpoint returns <code>403</code>.
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
Query parameters
Payment-state filter, matched against the row's <code>bookingStatus</code> field. Allowed values: <code>OPEN</code>, <code>PARTLY_PAID</code>, <code>PAID</code>, <code>PARTLY_CLEARED</code>, <code>CLEARED</code>. Independent of <code>status</code> and combinable with it. Invoices without a booking are excluded. When omitted, invoices in every payment state are returned.
Page size. Defaults to <code>50</code>; hard cap <code>100</code>. Requests above the cap are rejected with <code>400</code>.
0-based pagination offset — the number of rows to skip before the returned page. Defaults to <code>0</code>. Combine with <code>limit</code> to walk the full collection.
Free-text search. The fields searched are documented per endpoint. Matches are case-insensitive substring matches. Maximum length 256 characters.
Sort direction. Allowed values: <code>ASC</code>, <code>DESC</code>. Defaults to <code>DESC</code>.
Field to order the result by. The accepted values are listed per endpoint; an unknown value is rejected with <code>400</code>. Each endpoint documents the default it applies, chosen so that paging with <code>offset</code> / <code>limit</code> is stable.
Invoice-overview status filter. Allowed values: <code>DRAFT</code>, <code>INVOICED</code>, <code>SENT</code>, <code>PAID</code>, <code>OPEN</code>, <code>CLEARED</code>, <code>CANCELLED</code>. When omitted, invoices in every status are returned. See the operation description — this is not a plain equality filter on the row's <code>status</code> field.
Response
A page of invoices. Empty array when nothing matches.
Example response
[
{
"id": 42,
"invoiceCode": "INV-2026-001",
"invoiceNumber": 2026001,
"orderNumber": 377,
"subject": "Consulting Q2 2026",
"status": "INVOICED",
"bookingStatus": "OPEN",
"invoiceType": "MANUAL",
"amount": 500,
"documentDate": "2026-05-28",
"paymentDate": "2026-06-27",
"bookingDueDate": "2026-06-27",
"customerId": 40,
"customerName": "A. Bassi AG",
"customerType": "COMPANY",
"bookingNumbers": "1982"
}
]Changes
No recorded changes to this operation across all 1 revision of this API.