Finance

Get a single invoice by its numeric id.

Returns the fully-enriched invoice document for the given <code>id</code> under the company resolved from the bearer JWT. The response includes order items enriched with inventory selection data and accounting booking-status fields (<code>bookingStatus</code>, <code>bookingDueDate</code>, <code>bookingSealed</code>) populated by <code>luz_accounting</code>. The caller must hold the <code>FINANCE</code> permission on the target company.

get/core/v1/invoices/{id}

Request

  • Base URL: https://api.klara.ch
  • URL: https://api.klara.ch/core/v1/invoices/{id}
  • Auth: one of:
    • API key in header X-API-KEY
    • HTTP bearer

Path parameters

idinteger required
Example:42

Numeric primary key of the invoice to retrieve. Obtain this from the <code>id</code> field of a previously created invoice (<code>POST /core/v1/invoices</code>).

Response

Invoice found and returned.

idinteger

Invoice id. Must be <code>0</code> or omitted when creating a new invoice. This endpoint only supports creation; updating an existing invoice is not supported.

orderTypestring

Polymorphic discriminator. Must be <code>INVOICE</code>. Allowed values: <code>INVOICE</code>.

statusstring

Invoice status. Allowed values: <code>DRAFT</code>, <code>INVOICED</code>, <code>SENT</code>, <code>PAID</code>, <code>CANCELLED</code>. Required. Status <code>INVOICED</code> or <code>SENT</code> triggers accounting booking.

invoiceCodestring required

Human-readable invoice code. Required and unique per company.

invoiceNumberinteger

Sequential invoice number, typically obtained from <code>GET /invoices/next-invoice-number</code>.

documentDatestring date

Invoice document date (ISO 8601). Required when <code>amount</code> is greater than 0. Must fall inside the company's active Order Management subscription period.

paymentDatestring date

Payment due date (ISO 8601). Required when <code>amount</code> is greater than 0. Must be on or after <code>documentDate</code>.

deliveryDatestring date

Service delivery date (ISO 8601).

issuedDatestring date

Date the invoice was issued (ISO 8601).

servicePeriodFromstring date

Service period start date (ISO 8601).

servicePeriodTostring date

Service period end date (ISO 8601).

servicePeriodPatternstring

Service period pattern label (e.g. <code>MONTHLY</code>, <code>YEARLY</code>).

vatDatestring date

VAT date. Server-managed (read-only).

bookingDueDatestring date

Booking due date returned by accounting. Server-managed (read-only).

lastModifiedstring date-time

Last modification timestamp. Server-managed (read-only).

createDatestring date-time

Creation timestamp. Server-managed (read-only).

amountnumber

Invoice total. When <code>usingVAT=false</code> (VAT-exclusive items) this is the gross total = net + VAT; when <code>usingVAT=true</code> (VAT-inclusive items) it is the sum of the gross item amounts (VAT already inside). <strong>Caller-supplied — the server does not recompute it.</strong>

usingVATboolean

Controls whether each item <code>price</code>/<code>amount</code> is <strong>VAT-inclusive (gross)</strong> or <strong>VAT-exclusive (net)</strong>. This is the GUI checkbox <em>"VAT included in amount of each item"</em>. <code>true</code> = amounts already include VAT (INCLUDE_VAT); <code>false</code> = VAT is added on top of the net amounts (EXCLUDE_VAT). It does <strong>not</strong> turn VAT on or off — whether VAT applies at all is governed by the company's VAT registration. Use <code>GET /core/latest/company-configuration/including-vat</code> for the company default. <strong>The server stores the amounts you send verbatim and does not recompute them from this flag</strong> — send <code>price</code>/<code>amount</code> consistent with the chosen mode (see the create operation's VAT-handling notes).

usingExportVatboolean

Export invoice flag — the GUI <em>"Export"</em> checkbox. When <code>true</code>, the invoice is treated as an export: every <code>orderItems[].vat.rate</code> must be <code>0</code> (export/zero VAT code), so no VAT is charged. When <code>false</code> (default) the items' normal VAT rates apply. The server does not recompute item VAT from this flag — set the per-item VAT accordingly.

hasCompanyVatboolean

Whether the company is liable for VAT. <strong>Leave this out.</strong> The server derives it from the company's VAT registration for the invoice's effective VAT date (<code>deliveryDate</code> when set, otherwise <code>documentDate</code>) and a derived value always wins over a value sent here. It is documented only because it is accepted, and because sending <code>false</code> on a VAT-registered company used to book every position at 0% while returning 200 — this field is the master switch for VAT at booking time, ahead of any per-line VAT code. It is only consulted when the company has no VAT configuration for that date, where it cannot be derived at all.

subjectstring

Free-text invoice subject.

closeAndSignaturestring

Free-text closing remarks / signature block.

ourReferencestring

Internal sender reference.

yourReferencestring

Customer-side reference (e.g. PO number).

companyCityAndDatestring

Header line such as 'Zurich, 28.05.2026'.

postMethodstring

Distribution channel recorded on the invoice. <strong>Stored only — creating an invoice does not deliver it</strong> (no email/ePost/eBill/print&send). Allowed values: <code>A_POST</code>, <code>B_POST</code>, <code>SEND_EMAIL</code>, <code>PRINT_AND_MANUAL_SEND</code>, <code>EPOST</code>, <code>EBILL</code>.

deliverystring

Delivery method label (free text).

ibanNumberCHFstring

CHF IBAN for payment. Validated by downstream service.

ibanNumberCHWstring

WIR-franc IBAN for payment.

wirAcceptanceRatenumber

WIR acceptance percentage.

referenceNumberstring

QR / ISR reference number.

qrInvoiceboolean

When <code>true</code>, the invoice is rendered/booked as a Swiss QR-invoice. Defaults to false.

fromAutoInvoicingboolean

Indicates the invoice was generated by auto-invoicing. Defaults to false.

fromInvoiceRunboolean

Indicates the invoice was produced by a recurring invoice run. When <code>true</code>, accounting booking and inventory transactions are skipped. Defaults to false.

invoiceTypestring

Invoice type. Allowed values: <code>MANUAL</code>, <code>CREDIT_DEBIT</code>.

originDistributionMethodstring

Origin distribution method. Allowed values: <code>A_POST</code>, <code>B_POST</code>, <code>SEND_EMAIL</code>, <code>PRINT_AND_MANUAL_SEND</code>, <code>EPOST</code>, <code>EBILL</code>.

templateIdinteger

Template id used to create this invoice.

runHistoryIdinteger

Recurring invoice run history id.

settledAmountnumber

Klara-Pay settled amount (online shop only).

bookingNumbersstring

Accounting booking-number string. Server-managed (read-only).

businessCaseIdinteger

Accounting business case id. Server-managed (read-only).

bookingStatusstring

Booking status (e.g. <code>OPEN</code>, <code>PARTIAL</code>, <code>PAID</code>). Server-managed (read-only).

bookingMessagestring

Optional booking error/info code (e.g. <code>INVALID_SUBSCRIPTION_FOR_ACCOUNTING</code>). Server-managed (read-only).

bookingSealedboolean

Whether the booking has been finalized. Server-managed (read-only).

fiscalYearHasCreatedAutoboolean

Whether a fiscal year was auto-created during booking. Server-managed (read-only).

createBystring

Server-assigned audit user (token subject). Server-managed (read-only).

Example response

{
  "orderType": "INVOICE",
  "status": "INVOICED",
  "invoiceCode": "INV-2026-001",
  "invoiceNumber": 2026001,
  "documentDate": "2026-05-28",
  "paymentDate": "2026-06-27",
  "deliveryDate": "2026-05-25",
  "issuedDate": "2026-05-28",
  "servicePeriodFrom": "2026-05-01",
  "servicePeriodTo": "2026-05-31",
  "servicePeriodPattern": "MONTHLY",
  "amount": 1080,
  "usingVAT": true,
  "hasCompanyVat": true,
  "subject": "Invoice 2026-001",
  "closeAndSignature": "Thank you for your business.",
  "ourReference": "ACC-2026",
  "yourReference": "PO-9981",
  "companyCityAndDate": "Zurich, 28.05.2026",
  "postMethod": "SEND_EMAIL",
  "delivery": "DHL",
  "ibanNumberCHF": "CH9300762011623852957",
  "ibanNumberCHW": "CH9300762011623852957",
  "referenceNumber": "21 00000 00003 13947 14300 09017",
  "qrInvoice": true,
  "invoiceType": "MANUAL",
  "originDistributionMethod": "SEND_EMAIL"
}

Changes

No recorded changes to this operation across all 1 revision of this API.