Finance

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>.

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

Query parameters

booking-status'OPEN' | 'PARTLY_PAID' | 'PAID' | 'PARTLY_CLEARED' | 'CLEARED'
Example:OPEN

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.

limitinteger
Example:50

Page size. Defaults to <code>50</code>; hard cap <code>100</code>. Requests above the cap are rejected with <code>400</code>.

offsetinteger

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.

search-keystring
Example:müller

Free-text search. The fields searched are documented per endpoint. Matches are case-insensitive substring matches. Maximum length 256 characters.

sort-direction'ASC' | 'DESC'
Example:DESC

Sort direction. Allowed values: <code>ASC</code>, <code>DESC</code>. Defaults to <code>DESC</code>.

sort-fieldstring

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.

status'DRAFT' | 'INVOICED' | 'SENT' | 'PAID' | 'OPEN' | 'CLEARED' | 'CANCELLED'
Example:OPEN

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.

idinteger

Numeric primary key. Pass this to <code>GET /core/v1/invoices/{id}</code> to retrieve the full document.

invoiceCodestring

Human-readable invoice code, unique per company.

invoiceNumberinteger

Sequential invoice number.

orderNumberinteger

Order number of the invoice's order.

subjectstring

Invoice subject / title.

statusstring

Invoice <strong>document</strong> status. One of <code>DRAFT</code>, <code>INVOICED</code>, <code>PAID</code>, <code>CANCELLED</code>. Note that <code>SENT</code> is reported as <code>INVOICED</code> for non-negative amounts, and that the <code>status</code> query parameter additionally accepts the payment-state values <code>OPEN</code>, <code>PAID</code> and <code>CLEARED</code>, which are matched against <code>bookingStatus</code> rather than against this field.

bookingStatusstring

Accounting payment state of the invoice's open position, from luz_accounting: <code>OPEN</code>, <code>PARTLY_PAID</code>, <code>PAID</code>, <code>PARTLY_CLEARED</code> or <code>CLEARED</code>. Absent for invoices that carry no booking (<code>DRAFT</code>, cancelled).

invoiceTypestring

Invoice type: <code>MANUAL</code> or <code>RECURRING</code>.

amountnumber

Invoice total, on the same basis as <code>Invoice.amount</code>.

documentDatestring date

Invoice document date (ISO 8601).

paymentDatestring date

Payment due date (ISO 8601).

bookingDueDatestring date

Booking due date returned by accounting.

customerIdinteger

Id of the customer the invoice was issued to.

customerNamestring

Display name of the customer — the company name for a <code>COMPANY</code> customer, first and last name for a <code>PERSON</code>.

customerTypestring

Customer type: <code>COMPANY</code> or <code>PERSON</code>.

bookingNumbersstring

Accounting booking numbers created for this invoice, comma-separated. Empty while the invoice is not booked.

lastModifiedstring date-time

Last modification timestamp.

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.