Accounting48

Accounting Interface1

Article28

Authentication3

Company3

Company documents1

Company general4

Customer14

eBill Network Partner8

Email partner2

ePost Communication Platform Delivery5

ePost Communication Platform Monitoring1

ePost Communication Platform Preview Services4

ePost Digital Letterbox13

ePost Digital LetterBox Identity Matching with detailed recipient feedback5

ePost Digital Letterbox Onboarding and Profile Management1

ePost eArchive3

ePost Sign8

Finance12

get/core/v1/company-bank-accountsList the bank accounts of the authenticated company.
get/core/v1/invoicesSearch and page the invoices of the authenticated company.
put/core/v1/invoicesUpdate an existing DRAFT invoice for the authenticated company.
post/core/v1/invoicesCreate a new KLARA invoice for the authenticated company.
get/core/v1/invoices/next-invoice-numberGet the next available invoice number for the authenticated company.
get/core/v1/invoices/{id}Get a single invoice by its numeric id.
post/core/v1/invoices/{id}/printed-documentReturn the invoice as a PDF (rendering it if needed).
post/core/v1/invoices/{id}/sendSend a booked invoice (smart delivery or a forced channel).
get/core/v1/order-documents/filter/type-and-order-numberList order-management documents by type and order number.
get/core/v1/order-documents/{order-type}/next-document-numberGet the next document number for a given order-document type.
get/core/v1/order-numbering-configurationsGet the order-numbering configuration for a document type.
get/core/v1/orders/next-order-numberGet the next available order number for the authenticated company.

Individual2

Klara authentication generic1

Location1

Payroll3

Print partner1

Printer driver public API1

SHRM Barcode print2

SHRM Booking4

SHRM D3 Archive5

SHRM Employee Migration2

SHRM PWB3

SHRM TimeAS1

SPS3

Standard ePost Digital Letterbox Identity Matching4

Store1

Subscription1

Finance

Create a new KLARA invoice for the authenticated company.

Creates a new invoice for an existing customer under the company resolved from the bearer JWT. The request body's <code>id</code> must be <code>0</code> or omitted — this endpoint does not support updating existing invoices. Typical flow:<ol><li>Call <code>GET /core/v1/invoices/next-invoice-number</code> to obtain the next invoice number.</li><li>(Optional) List existing invoices with <code>GET /core/v1/invoices</code> — filter by <code>status</code> and page with <code>offset</code>/<code>limit</code> — to check what is already booked before creating another.</li><li>Look up the customer via <code>GET /core/v1/customers</code> (with search filters and pagination).</li><li>Look up company bank accounts via <code>GET /core/v1/company-bank-accounts</code>.</li><li>Search articles via <code>GET /core/latest/articles/search</code> or <code>GET /core/latest/articles/article-numbers</code> to populate order items.</li><li>(Optional) Look up open positions via <code>GET /core/v1/bank-reconciliation/open-positions</code> to reconcile prepayments / credit notes.</li><li>(Optional) Call <code>POST /core/v1/orders/next-order-number</code> to obtain the next <code>order.orderNumber</code>.</li><li>(Optional) Call <code>GET /core/latest/company-configuration/including-vat</code> to determine the company default for <code>usingVAT</code>.</li><li>Build the invoice payload with order items.</li><li>Call this endpoint with <code>status=INVOICED</code> to save and book, or <code>status=DRAFT</code> to save without booking.</li></ol>On status <code>INVOICED</code> or <code>SENT</code> the invoice is also booked into KLARA accounting, inventory transactions are created and the HubSpot indicator is synchronised. This endpoint does not send/deliver the invoice (no email/ePost/eBill/print&send), regardless of <code>postMethod</code> or a <code>SENT</code> status; retrieve the PDF via <code>POST /core/v1/invoices/{id}/printed-document</code> and deliver it yourself. The caller must hold the <code>FINANCE</code> permission on the target company. Status is caller-controlled. The Klara GUI keeps an invoice in <code>DRAFT</code> until the user posts it in the final step; via the API you choose — send <code>status=DRAFT</code> to save without booking, or <code>status=INVOICED</code> (or <code>SENT</code>) to book immediately. A DRAFT can be finalized later with <code>PUT /core/v1/invoices</code> (<code>status=INVOICED</code>). Important — booking is created without a printed invoice. When you book via this endpoint (<code>status=INVOICED</code>/<code>SENT</code>), the accounting booking is created but no PDF is rendered or stored — the invoice and its booking have no printed document (unlike the GUI, which renders, stores and books in one step). To attach the printed invoice, run two follow-up calls: (1) <code>POST /core/v1/invoices/{id}/printed-document</code> to render the PDF and store its <code>printedFileId</code> on the invoice, then (2) <code>PUT /core/v1/bookings/{id}/documents</code> to link that <code>printedFileId</code> (in <code>documentIds</code>) to the booking returned in <code>bookingNumbers</code>.

post/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

confirmDontMindClosingFiscalYearboolean

When <code>true</code>, allows save/booking even if the document date falls inside a closing or closed fiscal year. Defaults to false.

Headers

Accept-Languagestring

Example:en

Preferred response language as a BCP-47 tag (e.g. <code>en</code>, <code>de</code>, <code>fr</code>, <code>it</code>). Forwarded to luzfin_finance.

Request body

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). Caller-supplied — the server does not recompute it.

usingVATboolean

Controls whether each item <code>price</code>/<code>amount</code> is VAT-inclusive (gross) or VAT-exclusive (net). This is the GUI checkbox "VAT included in amount of each item". <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 not 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. The server stores the amounts you send verbatim and does not recompute them from this flag — 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 "Export" 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. Leave this out. 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. Stored only — creating an invoice does not deliver it (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).

mailingContactinteger

Contact person id used for postal delivery.

partnerContactIdinteger

Contact person of the customer this invoice is addressed to.

printedFileIdstring

Document id of the printed invoice PDF. Normally server-assigned by <code>POST /core/v1/invoices/{id}/printed-document</code> — omit it on creation. Set it only to attach a PDF your own system rendered.

Example request

{
  "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",
  "order": {
    "orderNumber": 2026001,
    "orderName": "Consulting Q2 2026",
    "companyId": 12345,
    "customer": {
      "id": 50123,
      "customerType": "COMPANY",
      "companyId": 12345,
      "company": {
        "id": 50123,
        "name": "Muster AG",
        "addresses": [
          {
            "type": "COMPANY",
            "addressType": "MAIN",
            "salutation": "MALE",
            "firstName": "Hans",
            "lastName": "Muster",
            "companyName": "Muster AG",
            "street": "Bahnhofstrasse",
            "homeNumber": "12a",
            "additionalAddress": "c/o Finance Department",
            "addressLines": "Bahnhofstrasse 12a",
            "city": {
              "id": 4247,
              "addressPostcode": "8005",
              "cityName18": "Zuerich",
              "cityName27": "Zuerich",
              "onrp": 4247,
              "postcodeType": 20,
              "additionalPostcode": "00",
              "basicPostcode": 8005,
              "languageCode": 1,
              "state": {
                "id": 26,
                "code": "ZH",
                "description": "Zuerich"
              },
              "country": {
                "id": 1,
                "countryName": "Switzerland",
                "iso2Code": "CH",
                "iso3Code": "CHE",
                "phoneCode": "41",
                "numericCode": "756"
              }
            },
            "validFrom": "2026-01-01",
            "validTo": "2026-12-31"
          }
        ],
        "emails": [
          {
            "id": "1001",
            "emailAddress": "billing@muster.ch",
            "type": "WORK"
          }
        ],
        "phones": [
          {
            "id": 2001,
            "phoneNumber": "+41 44 123 45 67",
            "type": "WORK"
          }
        ],
        "companyBillingAddress": {
          "type": "COMPANY",
          "addressType": "MAIN",
          "salutation": "MALE",
          "firstName": "Hans",
          "lastName": "Muster",
          "companyName": "Muster AG",
          "street": "Bahnhofstrasse",
          "homeNumber": "12a",
          "additionalAddress": "c/o Finance Department",
          "addressLines": "Bahnhofstrasse 12a",
          "city": {
            "id": 4247,
            "addressPostcode": "8005",
            "cityName18": "Zuerich",
            "cityName27": "Zuerich",
            "onrp": 4247,
            "postcodeType": 20,
            "additionalPostcode": "00",
            "basicPostcode": 8005,
            "languageCode": 1,
            "state": {
              "id": 26,
              "code": "ZH",
              "description": "Zuerich"
            },
            "country": {
              "id": 1,
              "countryName": "Switzerland",
              "iso2Code": "CH",
              "iso3Code": "CHE",
              "phoneCode": "41",
              "numericCode": "756"
            }
          },
          "validFrom": "2026-01-01",
          "validTo": "2026-12-31"
        },
        "corporateIdentificationNumber": "CHE-123.456.789",
        "vatNumber": "CHE-123.456.789 MWST",
        "hrNumber": "CH-020.3.926.481-3",
        "nogaCode": "620100",
        "companyNumber": "C-0001",
        "companyOriginReference": "ERP-4711",
        "website": "https://www.muster.ch",
        "language": "de"
      },
      "person": {
        "id": 50124,
        "salutation": "MALE",
        "firstName": "Hans",
        "lastName": "Muster",
        "birthday": "1980-04-17",
        "addressList": [
          {
            "type": "COMPANY",
            "addressType": "MAIN",
            "salutation": "MALE",
            "firstName": "Hans",
            "lastName": "Muster",
            "companyName": "Muster AG",
            "street": "Bahnhofstrasse",
            "homeNumber": "12a",
            "additionalAddress": "c/o Finance Department",
            "addressLines": "Bahnhofstrasse 12a",
            "city": {
              "id": 4247,
              "addressPostcode": "8005",
              "cityName18": "Zuerich",
              "cityName27": "Zuerich",
              "onrp": 4247,
              "postcodeType": 20,
              "additionalPostcode": "00",
              "basicPostcode": 8005,
              "languageCode": 1,
              "state": {
                "id": 26,
                "code": "ZH",
                "description": "Zuerich"
              },
              "country": {
                "id": 1,
                "countryName": "Switzerland",
                "iso2Code": "CH",
                "iso3Code": "CHE",
                "phoneCode": "41",
                "numericCode": "756"
              }
            },
            "validFrom": "2026-01-01",
            "validTo": "2026-12-31"
          }
        ],
        "emailList": [
          {
            "id": "1001",
            "emailAddress": "billing@muster.ch",
            "type": "WORK"
          }
        ],
        "phoneList": [
          {
            "id": 2001,
            "phoneNumber": "+41 44 123 45 67",
            "type": "WORK"
          }
        ],
        "personNumber": "P-0001",
        "personOriginReference": "ERP-8150",
        "website": "https://www.muster.ch",
        "language": "de"
      },
      "termsOfPayment": 30,
      "priceCategory": "STANDARD",
      "uuid": "0d9f4d1e-4a2b-4c8d-9f3e-1b2c3d4e5f60"
    },
    "invoiceGroup": "DEFAULT"
  },
  "orderItems": [
    {
      "position": 1,
      "itemNumer": "P0000061123",
      "description": "Consulting services",
      "articleExtendedDescription": "Sprint 12, May 2026",
      "quantity": 10,
      "unit": "Hour",
      "price": 100,
      "amount": 1000,
      "posAmount": 1000,
      "vat": {
        "id": 1,
        "vatCode": "1",
        "rate": 8.1,
        "description": "Normal rate 8.1%",
        "validFrom": "2024-01-01",
        "validTo": "2099-12-31"
      },
      "vatCode": "1",
      "vatCase": "TAXABLE_SUPPLY",
      "articleType": "SERVICE",
      "tag": "3400",
      "servicePeriodFrom": "2026-05-01",
      "servicePeriodTo": "2026-05-31",
      "servicePeriodPattern": "MONTHLY",
      "specialRates": "SSS1",
      "articleSet": "SET-001",
      "inventorySelections": [
        {
          "storagePlaceId": 77,
          "quantity": 1,
          "serialNumbers": [
            "SN-0001",
            "SN-0002"
          ]
        }
      ]
    }
  ],
  "attachments": [
    {
      "fileId": "5f8d0d55-b1a4-4d6e-9a1f-2c3b4d5e6f70"
    }
  ],
  "openPositionsLinkedToInvoice": [
    {
      "bookingTypeCode": "AR_PREPAYMENT",
      "bookingDetailUri": "/luz_accounting/api/klara_tenant/companies/12345/bookings/778/booking-details/9912",
      "partialPaymentAmount": 250
    }
  ],
  "documentAddress": {
    "customerId": 50123,
    "customerType": "COMPANY",
    "address": {
      "type": "COMPANY",
      "addressType": "MAIN",
      "salutation": "MALE",
      "firstName": "Hans",
      "lastName": "Muster",
      "companyName": "Muster AG",
      "street": "Bahnhofstrasse",
      "homeNumber": "12a",
      "additionalAddress": "c/o Finance Department",
      "addressLines": "Bahnhofstrasse 12a",
      "city": {
        "id": 4247,
        "addressPostcode": "8005",
        "cityName18": "Zuerich",
        "cityName27": "Zuerich",
        "onrp": 4247,
        "postcodeType": 20,
        "additionalPostcode": "00",
        "basicPostcode": 8005,
        "languageCode": 1,
        "state": {
          "id": 26,
          "code": "ZH",
          "description": "Zuerich"
        },
        "country": {
          "id": 1,
          "countryName": "Switzerland",
          "iso2Code": "CH",
          "iso3Code": "CHE",
          "phoneCode": "41",
          "numericCode": "756"
        }
      },
      "validFrom": "2026-01-01",
      "validTo": "2026-12-31"
    },
    "salutation": "MALE",
    "personFirstName": "Hans",
    "personLastName": "Muster",
    "companyName": "Muster AG"
  },
  "mailingAddress": {
    "customerId": 50123,
    "customerType": "COMPANY",
    "address": {
      "type": "COMPANY",
      "addressType": "MAIN",
      "salutation": "MALE",
      "firstName": "Hans",
      "lastName": "Muster",
      "companyName": "Muster AG",
      "street": "Bahnhofstrasse",
      "homeNumber": "12a",
      "additionalAddress": "c/o Finance Department",
      "addressLines": "Bahnhofstrasse 12a",
      "city": {
        "id": 4247,
        "addressPostcode": "8005",
        "cityName18": "Zuerich",
        "cityName27": "Zuerich",
        "onrp": 4247,
        "postcodeType": 20,
        "additionalPostcode": "00",
        "basicPostcode": 8005,
        "languageCode": 1,
        "state": {
          "id": 26,
          "code": "ZH",
          "description": "Zuerich"
        },
        "country": {
          "id": 1,
          "countryName": "Switzerland",
          "iso2Code": "CH",
          "iso3Code": "CHE",
          "phoneCode": "41",
          "numericCode": "756"
        }
      },
      "validFrom": "2026-01-01",
      "validTo": "2026-12-31"
    },
    "salutation": "MALE",
    "personFirstName": "Hans",
    "personLastName": "Muster",
    "companyName": "Muster AG"
  },
  "emailDistribution": {
    "subject": "Invoice INV-2026-001",
    "emailAddress": "billing@muster.ch",
    "ccEmailAddresses": [
      "accounting@muster.ch"
    ],
    "replyTo": "finance@my-company.ch",
    "emailText": "Please find our invoice attached."
  },
  "printedFileId": "5f8d0d55-b1a4-4d6e-9a1f-2c3b4d5e6f70"
}

Response

Invoice persisted successfully.