---
title: "Update an existing DRAFT invoice for the authenticated company."
method: PUT
path: "/core/v1/invoices"
tags: ["Finance"]
---

# Update an existing DRAFT invoice for the authenticated company.

`PUT /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

Updates a DRAFT invoice identified by <code>invoice.id</code> in the request body. Only invoices in <code>DRAFT</code> status can be updated — any other status returns 400. If the incoming <code>status</code> is <code>INVOICED</code> or <code>SENT</code>, the invoice is booked into KLARA accounting and inventory transactions are created, identical to the booking behavior of <code>POST /core/v1/invoices</code>. This is the call that finalizes a DRAFT — the GUI equivalent of posting in the final step; <strong>status is caller-controlled</strong>, so keep it <code>DRAFT</code> to re-save without booking. <strong>This endpoint does not send/deliver the invoice</strong> (no email/ePost/eBill/print&amp;send), regardless of <code>postMethod</code>; 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.<br/><br/><strong>Important — finalizing a DRAFT books it without a printed invoice.</strong> Setting <code>status=INVOICED</code>/<code>SENT</code> here creates the accounting booking but <strong>renders/stores no PDF</strong>. To attach the printed invoice to the booking, after this call run (1) <code>POST /core/v1/invoices/{id}/printed-document</code> to render and store the <code>printedFileId</code>, then (2) <code>PUT /core/v1/bookings/{id}/documents</code> to link that <code>printedFileId</code> (in <code>documentIds</code>) to the booking from <code>bookingNumbers</code>.

## Query parameters

- `confirmDontMindClosingFiscalYear` boolean

## Request body

- InvoiceCreateRequest: Request body of <code>POST</code> and <code>PUT /core/v1/invoices</code>. Carries every field of the <code>Invoice</code> model plus the nested order, line item, attachment and reconciliation blocks.<br/><br/><strong>Field names that look like typos but are not:</strong> <code>orderItems[].itemNumer</code> (article number), <code>...city.cityName18</code> / <code>cityName27</code> (Swiss Post 18- and 27-character city names) and <code>...address.homeNumber</code> (house number) are the literal wire field names accepted by the backend. <code>itemNumber</code>, <code>houseNumber</code> and similar corrected spellings are <strong>not</strong> accepted.<br/><br/><strong>VAT:</strong> set the code on <code>orderItems[].vat.vatCode</code> and nowhere else — it is the only VAT field this endpoint stores. A line that puts a code on the sibling <code>orderItems[].vatCode</code> and leaves <code>vat.vatCode</code> empty is rejected with <code>400 invoice.vat_code_missing</code> rather than booked at 0%. Omitting the code entirely is allowed: the server takes it from <code>vat.rate</code> when you sent one, from the article otherwise, and a company that is not liable for VAT needs none. To state a zero rate explicitly — on an export invoice, for instance — send the <code>"0"</code> ("No VAT") code.<br/><br/><strong><code>orderItems[].vat.rate</code> identifies the code, and must be the rate in force on the document's date.</strong> A company's VAT configuration normally holds one code per rate, so a rate alone is enough; only if two of the company's codes share it on that date are you asked for <code>vat.vatCode</code>. The date is the one the booking uses — <code>servicePeriodFrom</code>, else <code>deliveryDate</code>, else <code>documentDate</code>.<br/><br/>Rates change between releases, and a rate from another one is rejected rather than replaced: sending 8.1 on a document dated after that rate ended gives <code>400 invoice.vat_rate_mismatch</code> naming the rate that does apply, so you can invoice a total you calculated yourself. The same holds when you send a code and a rate together — they must agree on that date. Omit <code>vat.rate</code> entirely and the server fills it in from the code and the date, which is the shape that never needs revisiting when a rate changes. The sibling <code>orderItems[].vatCode</code>, <code>vatCase</code>, <code>articleType</code> and <code>tag</code> are accepted but not persisted, and <code>vatType</code> does not exist at all. Leave <code>hasCompanyVat</code> out: the server derives the company's VAT liability itself.
  - `id` integer: 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.
  - `orderType` string: Polymorphic discriminator. Must be <code>INVOICE</code>. Allowed values: <code>INVOICE</code>.
  - `status` string: 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.
  - `invoiceCode` string, required: Human-readable invoice code. Required and unique per company.
  - `invoiceNumber` integer: Sequential invoice number, typically obtained from <code>GET /invoices/next-invoice-number</code>.
  - `documentDate` string, 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.
  - `paymentDate` string, date: Payment due date (ISO 8601). Required when <code>amount</code> is greater than 0. Must be on or after <code>documentDate</code>.
  - `deliveryDate` string, date: Service delivery date (ISO 8601).
  - `issuedDate` string, date: Date the invoice was issued (ISO 8601).
  - `servicePeriodFrom` string, date: Service period start date (ISO 8601).
  - `servicePeriodTo` string, date: Service period end date (ISO 8601).
  - `servicePeriodPattern` string: Service period pattern label (e.g. <code>MONTHLY</code>, <code>YEARLY</code>).
  - `vatDate` string, date: VAT date. Server-managed (read-only).
  - `bookingDueDate` string, date: Booking due date returned by accounting. Server-managed (read-only).
  - `lastModified` string, date-time: Last modification timestamp. Server-managed (read-only).
  - `createDate` string, date-time: Creation timestamp. Server-managed (read-only).
  - `amount` number: 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>
  - `usingVAT` boolean: 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).
  - `usingExportVat` boolean: 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.
  - `hasCompanyVat` boolean: 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.
  - `subject` string: Free-text invoice subject.
  - `closeAndSignature` string: Free-text closing remarks / signature block.
  - `ourReference` string: Internal sender reference.
  - `yourReference` string: Customer-side reference (e.g. PO number).
  - `companyCityAndDate` string: Header line such as 'Zurich, 28.05.2026'.
  - `postMethod` string: Distribution channel recorded on the invoice. <strong>Stored only — creating an invoice does not deliver it</strong> (no email/ePost/eBill/print&amp;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>.
  - `delivery` string: Delivery method label (free text).
  - `ibanNumberCHF` string: CHF IBAN for payment. Validated by downstream service.
  - `ibanNumberCHW` string: WIR-franc IBAN for payment.
  - `wirAcceptanceRate` number: WIR acceptance percentage.
  - `referenceNumber` string: QR / ISR reference number.
  - `qrInvoice` boolean: When <code>true</code>, the invoice is rendered/booked as a Swiss QR-invoice. Defaults to false.
  - `fromAutoInvoicing` boolean: Indicates the invoice was generated by auto-invoicing. Defaults to false.
  - `fromInvoiceRun` boolean: Indicates the invoice was produced by a recurring invoice run. When <code>true</code>, accounting booking and inventory transactions are skipped. Defaults to false.
  - `invoiceType` string: Invoice type. Allowed values: <code>MANUAL</code>, <code>CREDIT_DEBIT</code>.
  - `originDistributionMethod` string: 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>.
  - `templateId` integer: Template id used to create this invoice.
  - `runHistoryId` integer: Recurring invoice run history id.
  - `settledAmount` number: Klara-Pay settled amount (online shop only).
  - `bookingNumbers` string: Accounting booking-number string. Server-managed (read-only).
  - `businessCaseId` integer: Accounting business case id. Server-managed (read-only).
  - `bookingStatus` string: Booking status (e.g. <code>OPEN</code>, <code>PARTIAL</code>, <code>PAID</code>). Server-managed (read-only).
  - `bookingMessage` string: Optional booking error/info code (e.g. <code>INVALID_SUBSCRIPTION_FOR_ACCOUNTING</code>). Server-managed (read-only).
  - `bookingSealed` boolean: Whether the booking has been finalized. Server-managed (read-only).
  - `fiscalYearHasCreatedAuto` boolean: Whether a fiscal year was auto-created during booking. Server-managed (read-only).
  - `createBy` string: Server-assigned audit user (token subject). Server-managed (read-only).
  - `order` object, required: The order header this invoice belongs to. <strong>Required.</strong>
    - `id` integer: Order id. Must be <code>0</code> or omitted for a new order.
    - `orderNumber` integer, required: Order number, unique within the company. <strong>Required and must be greater than 0.</strong> Obtain it from <code>POST /core/v1/orders/next-order-number</code> — that endpoint is not idempotent, each call advances the counter.
    - `orderName` string: Free-text order name.
    - `companyId` integer, required: Owning KLARA company id — must match the company resolved from the bearer token. <strong>Required.</strong>
    - `customer` object, required: The invoice recipient. <strong>Required.</strong>
      - `id` integer, required: Customer id of an existing customer. <strong>Required.</strong>
      - `customerType` string, required: Discriminator selecting <code>company</code> or <code>person</code>. <strong>Required.</strong> Allowed values: <code>COMPANY</code>, <code>PERSON</code>.
      - `companyId` integer: Owning KLARA company id — must match the company resolved from the bearer token.
      - `company` object: Company partner data. Required when <code>customerType</code> is <code>COMPANY</code>.
        - `id` integer: Company partner id as returned by the customer lookup.
        - `name` string, required: Company name. <strong>Required.</strong>
        - `addresses` InvoiceAddress[]: Postal addresses of the company. At least the billing address must be present for the invoice to be printable.
          - `id` integer: Address id. Use the id returned by the customer lookup; <code>0</code> or omitted for a new address.
          - `type` string, required: Partner type this address belongs to. <strong>Required.</strong> Allowed values: <code>COMPANY</code>, <code>PERSON</code>.
          - `addressType` string, required: Address type label. <strong>Required.</strong> Typically <code>MAIN</code> or <code>BILLING</code>.
          - `salutation` string: Salutation of the addressee. Allowed values: <code>MALE</code>, <code>FEMALE</code>, <code>MALE_FEMALE</code>, <code>FAMILY</code>.
          - `firstName` string: First name of the addressee (person addresses).
          - `lastName` string: Last name of the addressee (person addresses).
          - `companyName` string: Company name of the addressee (company addresses).
          - `street` string: Street name, without the house number.
          - `homeNumber` string: House number. <code>homeNumber</code> is the literal field name used throughout the KLARA address model — <code>houseNumber</code> is not accepted.
          - `additionalAddress` string: Additional address line (c/o, department, ...).
          - `addressLines` string: Combined street and house number. <strong>Deprecated</strong> — use <code>street</code> and <code>homeNumber</code> instead.
          - `city` object, required: City block. <strong>Required.</strong>
            - `id` integer: City id from the Swiss Post address directory.
            - `addressPostcode` string: Postcode (PLZ / NPA).
            - `cityName18` string, required: City name, 18-character Swiss Post variant. <strong>Required.</strong> <code>cityName18</code> is the literal field name of the Swiss Post address directory (18-character abbreviation) — it is not a typo or a leftover.
            - `cityName27` string, required: City name, 27-character Swiss Post variant. <strong>Required.</strong>
            - `onrp` integer: Swiss Post ONRP identifier of the locality.
            - `postcodeType` integer: Swiss Post postcode type.
            - `additionalPostcode` string: Additional postcode suffix (max 2 characters).
            - `basicPostcode` integer: Basic postcode.
            - `languageCode` integer: Swiss Post language code of the locality.
            - `state` object: Canton / state of the locality.
              - …
            - `country` object: Country of the locality.
              - …
          - `validFrom` string, date: Address valid-from date (ISO 8601).
          - `validTo` string, date: Address valid-to date (ISO 8601). Must be after <code>validFrom</code>.
        - `emails` InvoiceEmail[]: E-mail addresses of the company.
          - `id` string: E-mail entry id.
          - `emailAddress` string: The e-mail address.
          - `type` string: E-mail type. Allowed values: <code>PRIVATE</code>, <code>WORK</code>, <code>OFFICE</code>, <code>OTHER</code>.
        - `phones` InvoicePhone[]: Phone numbers of the company.
          - `id` integer: Phone entry id.
          - `phoneNumber` string: The phone number.
          - `type` string: Phone type. Allowed values: <code>PRIVATE</code>, <code>OFFICE</code>, <code>FAX</code>, <code>WORK</code>, <code>MOBILE</code>.
        - `companyBillingAddress` object: Dedicated billing address, used when <code>companyBillingAddressEnabled</code> is <code>true</code>.
          - `id` integer: Address id. Use the id returned by the customer lookup; <code>0</code> or omitted for a new address.
          - `type` string, required: Partner type this address belongs to. <strong>Required.</strong> Allowed values: <code>COMPANY</code>, <code>PERSON</code>.
          - `addressType` string, required: Address type label. <strong>Required.</strong> Typically <code>MAIN</code> or <code>BILLING</code>.
          - `salutation` string: Salutation of the addressee. Allowed values: <code>MALE</code>, <code>FEMALE</code>, <code>MALE_FEMALE</code>, <code>FAMILY</code>.
          - `firstName` string: First name of the addressee (person addresses).
          - `lastName` string: Last name of the addressee (person addresses).
          - `companyName` string: Company name of the addressee (company addresses).
          - `street` string: Street name, without the house number.
          - `homeNumber` string: House number. <code>homeNumber</code> is the literal field name used throughout the KLARA address model — <code>houseNumber</code> is not accepted.
          - `additionalAddress` string: Additional address line (c/o, department, ...).
          - `addressLines` string: Combined street and house number. <strong>Deprecated</strong> — use <code>street</code> and <code>homeNumber</code> instead.
          - `city` object, required: City block. <strong>Required.</strong>
            - `id` integer: City id from the Swiss Post address directory.
            - `addressPostcode` string: Postcode (PLZ / NPA).
            - `cityName18` string, required: City name, 18-character Swiss Post variant. <strong>Required.</strong> <code>cityName18</code> is the literal field name of the Swiss Post address directory (18-character abbreviation) — it is not a typo or a leftover.
            - `cityName27` string, required: City name, 27-character Swiss Post variant. <strong>Required.</strong>
            - `onrp` integer: Swiss Post ONRP identifier of the locality.
            - `postcodeType` integer: Swiss Post postcode type.
            - `additionalPostcode` string: Additional postcode suffix (max 2 characters).
            - `basicPostcode` integer: Basic postcode.
            - `languageCode` integer: Swiss Post language code of the locality.
            - `state` object: Canton / state of the locality.
              - …
            - `country` object: Country of the locality.
              - …
          - `validFrom` string, date: Address valid-from date (ISO 8601).
          - `validTo` string, date: Address valid-to date (ISO 8601). Must be after <code>validFrom</code>.
        - `companyBillingAddressEnabled` boolean: Whether <code>companyBillingAddress</code> is used instead of the main address.
        - `corporateIdentificationNumber` string: Swiss company identification number (UID).
        - `vatNumber` string: VAT registration number.
        - `hrNumber` string: Commercial register number.
        - `nogaCode` string: NOGA economic activity code.
        - `companyNumber` string: Company number in KLARA.
        - `companyOriginReference` string: External reference of the company in the partner system.
        - `website` string: Company website.
        - `language` string: Preferred correspondence language as a BCP-47 tag.
      - `person` object: Person partner data. Required when <code>customerType</code> is <code>PERSON</code>.
        - `id` integer: Person partner id as returned by the customer lookup.
        - `salutation` string: Salutation. Allowed values: <code>MALE</code>, <code>FEMALE</code>, <code>MALE_FEMALE</code>, <code>FAMILY</code>.
        - `firstName` string, required: First name. <strong>Required.</strong>
        - `lastName` string, required: Last name. <strong>Required.</strong>
        - `birthday` string, date, required: Date of birth (ISO 8601). <strong>Required</strong> by the downstream person model.
        - `addressList` InvoiceAddress[]: Postal addresses of the person.
          - `id` integer: Address id. Use the id returned by the customer lookup; <code>0</code> or omitted for a new address.
          - `type` string, required: Partner type this address belongs to. <strong>Required.</strong> Allowed values: <code>COMPANY</code>, <code>PERSON</code>.
          - `addressType` string, required: Address type label. <strong>Required.</strong> Typically <code>MAIN</code> or <code>BILLING</code>.
          - `salutation` string: Salutation of the addressee. Allowed values: <code>MALE</code>, <code>FEMALE</code>, <code>MALE_FEMALE</code>, <code>FAMILY</code>.
          - `firstName` string: First name of the addressee (person addresses).
          - `lastName` string: Last name of the addressee (person addresses).
          - `companyName` string: Company name of the addressee (company addresses).
          - `street` string: Street name, without the house number.
          - `homeNumber` string: House number. <code>homeNumber</code> is the literal field name used throughout the KLARA address model — <code>houseNumber</code> is not accepted.
          - `additionalAddress` string: Additional address line (c/o, department, ...).
          - `addressLines` string: Combined street and house number. <strong>Deprecated</strong> — use <code>street</code> and <code>homeNumber</code> instead.
          - `city` object, required: City block. <strong>Required.</strong>
            - `id` integer: City id from the Swiss Post address directory.
            - `addressPostcode` string: Postcode (PLZ / NPA).
            - `cityName18` string, required: City name, 18-character Swiss Post variant. <strong>Required.</strong> <code>cityName18</code> is the literal field name of the Swiss Post address directory (18-character abbreviation) — it is not a typo or a leftover.
            - `cityName27` string, required: City name, 27-character Swiss Post variant. <strong>Required.</strong>
            - `onrp` integer: Swiss Post ONRP identifier of the locality.
            - `postcodeType` integer: Swiss Post postcode type.
            - `additionalPostcode` string: Additional postcode suffix (max 2 characters).
            - `basicPostcode` integer: Basic postcode.
            - `languageCode` integer: Swiss Post language code of the locality.
            - `state` object: Canton / state of the locality.
              - …
            - `country` object: Country of the locality.
              - …
          - `validFrom` string, date: Address valid-from date (ISO 8601).
          - `validTo` string, date: Address valid-to date (ISO 8601). Must be after <code>validFrom</code>.
        - `emailList` InvoiceEmail[]: E-mail addresses of the person.
          - `id` string: E-mail entry id.
          - `emailAddress` string: The e-mail address.
          - `type` string: E-mail type. Allowed values: <code>PRIVATE</code>, <code>WORK</code>, <code>OFFICE</code>, <code>OTHER</code>.
        - `phoneList` InvoicePhone[]: Phone numbers of the person.
          - `id` integer: Phone entry id.
          - `phoneNumber` string: The phone number.
          - `type` string: Phone type. Allowed values: <code>PRIVATE</code>, <code>OFFICE</code>, <code>FAX</code>, <code>WORK</code>, <code>MOBILE</code>.
        - `personNumber` string: Person number in KLARA.
        - `personOriginReference` string: External reference of the person in the partner system.
        - `website` string: Personal website.
        - `language` string: Preferred correspondence language as a BCP-47 tag.
      - `termsOfPayment` integer: Payment terms in days, used to derive the default <code>paymentDate</code>.
      - `discount` number: Default customer discount in percent.
      - `priceCategory` string: Price category assigned to the customer.
      - `uuid` string: Stable external identifier of the customer.
    - `invoiceGroup` string: Invoice group the order is assigned to.
    - `lumpSum` boolean: Whether the order is billed as a lump sum.
    - `archived` boolean: Whether the order is archived.
  - `orderItems` InvoiceOrderItem[], required: Invoice line items. <strong>Required — at least one entry.</strong>
    - `id` integer: Item id. Must be <code>0</code> or omitted for a new item.
    - `position` integer: Line position, 1-based.
    - `itemNumer` string: Article number of the item, as returned by <code>GET /core/latest/articles/search</code> or <code>GET /core/latest/articles/article-numbers</code>. <strong>The field name is <code>itemNumer</code>, not <code>itemNumber</code>.</strong> This spelling is the literal wire field name of the KLARA order-management model and is what the backend accepts — it is not a typo in this documentation. Note that the article search endpoints expose the same value under the name <code>articleNumber</code>.
    - `description` string: Item description printed on the invoice line.
    - `articleExtendedDescription` string: Additional descriptive text printed below the line.
    - `quantity` number: Quantity billed.
    - `unit` string: Unit of measure.
    - `price` number: Unit price. Negative for credit-note lines. VAT-inclusive (gross) when the document has <code>usingVAT=true</code>, VAT-exclusive (net) when <code>usingVAT=false</code>. Both variants are available from the article lookup endpoints.
    - `discount` number: Discount on this line, in percent.
    - `amount` number: Line total = <code>quantity x price x (1 - discount/100)</code>, rounded to the nearest 0.05 (Swiss commercial rounding). Gross or net following <code>usingVAT</code>, on the same basis as <code>price</code>.
    - `posAmount` number: Position amount as shown in the KLARA GUI. Optional; derived from <code>amount</code> when omitted.
    - `vat` object: VAT applied to this line. For an export invoice (<code>usingExportVat=true</code>) set <code>rate</code> to <code>0</code> and use the export/zero VAT code.
      - `id` integer: VAT id.
      - `vatCode` string, required: VAT code. <strong>Required.</strong>
      - `rate` number: VAT rate in percent. Set to <code>0</code> for export invoices (<code>usingExportVat=true</code>).
      - `description` string: Human-readable VAT description.
      - `masterId` integer: Master data id of the VAT record.
      - `companySelectedVat` boolean: Whether this is a company-selected VAT.
      - `sss1` boolean: Whether the first Swiss social-security special rate applies.
      - `sss2` boolean: Whether the second Swiss social-security special rate applies.
      - `validFrom` string, date: VAT valid-from date (ISO 8601).
      - `validTo` string, date: VAT valid-to date (ISO 8601).
    - `vatCode` string: VAT code of the line. Convenience mirror of <code>vat.vatCode</code>. <strong>Not persisted on this endpoint</strong> — the value that is stored comes from <code>vat.vatCode</code>. Do not send the two with different values: this field is silently discarded, so a mismatch results in the <code>vat.vatCode</code> value being booked.
    - `vatCase` string: VAT treatment of the line. Allowed values: <code>TAXABLE_SUPPLY</code>, <code>EXEMPT_SUPPLY</code>, <code>REVERSE_CHARGE</code>. <strong>Accepted but not persisted on this endpoint</strong> — the <code>order_item</code> table has no column for it. It is populated by the server only on the recurring-invoice run, from the article master data.
    - `articleType` string: Article category. Allowed values: <code>PRODUCTION</code>, <code>PREPAYMENT</code>, <code>SERVICE</code>. <strong>Accepted but not persisted on this endpoint</strong> — the <code>order_item</code> table has no column for it. It is populated by the server only on the recurring-invoice run, from the article master data.
    - `tag` string: Accounting tag of the line. <strong>Accepted but not persisted on this endpoint</strong> — the <code>order_item</code> table has no column for it, so a value sent here is silently discarded. It is derived by the server from the article master data on the recurring-invoice run. Booking behaviour is therefore not influenced by this field on <code>POST</code>/<code>PUT</code>.
    - `servicePeriodFrom` string, date: Service period start for this line (ISO 8601).
    - `servicePeriodTo` string, date: Service period end for this line (ISO 8601).
    - `servicePeriodPattern` string: Service period pattern label for this line.
    - `specialRates` string: Swiss social-security special rate applied to the line. Allowed values: <code>SSS1</code>, <code>SSS2</code>.
    - `articleSet` string: Identifier of the article set this line belongs to.
    - `inventorySelections` InvoiceInventorySelection[]: Inventory selections (serial numbers, storage places) for stock-managed articles. Persisted through a dedicated path rather than with the line itself, so the serial numbers you send are validated separately — an invalid serial number fails the request even though the surrounding line is accepted.
      - `storagePlaceId` integer: Storage place the quantity is taken from.
      - `quantity` number: Quantity taken from this storage place.
      - `serialNumbers` string[]: Serial numbers of the units delivered. Duplicates within the same invoice are rejected.
  - `attachments` InvoiceAttachment[]: Documents attached to the invoice.
    - `id` integer: Attachment id. Must be <code>0</code> or omitted for a new attachment.
    - `orderDetailId` integer: Id of the invoice this attachment belongs to. Must be <code>0</code> for a new invoice.
    - `fileId` string: Document id of the uploaded file.
  - `openPositionsLinkedToInvoice` InvoiceOpenPositionLink[]: Open positions (prepayments, credit notes) offset against this invoice. Persisted through a dedicated path rather than with the invoice row itself.
    - `bookingTypeCode` string, required: Type of the linked booking. <strong>Required.</strong> For invoice reconciliation the relevant values are <code>AR_PREPAYMENT</code> and <code>AR_CREDITNOTE</code>.
    - `bookingDetailUri` string, required: Internal URI of the booking detail to reconcile. <strong>Required.</strong> Must match the pattern <code>/luz_accounting/api/{tenant-id}/companies/{companyId}/bookings/{bookingId}/booking-details/{detailId}</code>.
    - `partialPaymentAmount` number: Amount to offset from this open position.
  - `documentAddress` object: Address block printed on the invoice document. Derived from the customer when omitted. Resolved against the customer's stored addresses and kept as a reference — the invoice records which address was used, it does not keep a private copy of the values you send.
    - `customerId` integer: Customer the address belongs to.
    - `customerType` string: Partner type. Allowed values: <code>COMPANY</code>, <code>PERSON</code>.
    - `address` object: The postal address to print.
      - `id` integer: Address id. Use the id returned by the customer lookup; <code>0</code> or omitted for a new address.
      - `type` string, required: Partner type this address belongs to. <strong>Required.</strong> Allowed values: <code>COMPANY</code>, <code>PERSON</code>.
      - `addressType` string, required: Address type label. <strong>Required.</strong> Typically <code>MAIN</code> or <code>BILLING</code>.
      - `salutation` string: Salutation of the addressee. Allowed values: <code>MALE</code>, <code>FEMALE</code>, <code>MALE_FEMALE</code>, <code>FAMILY</code>.
      - `firstName` string: First name of the addressee (person addresses).
      - `lastName` string: Last name of the addressee (person addresses).
      - `companyName` string: Company name of the addressee (company addresses).
      - `street` string: Street name, without the house number.
      - `homeNumber` string: House number. <code>homeNumber</code> is the literal field name used throughout the KLARA address model — <code>houseNumber</code> is not accepted.
      - `additionalAddress` string: Additional address line (c/o, department, ...).
      - `addressLines` string: Combined street and house number. <strong>Deprecated</strong> — use <code>street</code> and <code>homeNumber</code> instead.
      - `city` object, required: City block. <strong>Required.</strong>
        - `id` integer: City id from the Swiss Post address directory.
        - `addressPostcode` string: Postcode (PLZ / NPA).
        - `cityName18` string, required: City name, 18-character Swiss Post variant. <strong>Required.</strong> <code>cityName18</code> is the literal field name of the Swiss Post address directory (18-character abbreviation) — it is not a typo or a leftover.
        - `cityName27` string, required: City name, 27-character Swiss Post variant. <strong>Required.</strong>
        - `onrp` integer: Swiss Post ONRP identifier of the locality.
        - `postcodeType` integer: Swiss Post postcode type.
        - `additionalPostcode` string: Additional postcode suffix (max 2 characters).
        - `basicPostcode` integer: Basic postcode.
        - `languageCode` integer: Swiss Post language code of the locality.
        - `state` object: Canton / state of the locality.
          - `id` integer: State id.
          - `code` string: Canton code (max 3 characters).
          - `description` string: Canton name.
        - `country` object: Country of the locality.
          - `id` integer: Country id.
          - `countryName` string: Country name.
          - `iso2Code` string: ISO 3166-1 alpha-2 code.
          - `iso3Code` string: ISO 3166-1 alpha-3 code.
          - `phoneCode` string: International dialling code.
          - `numericCode` string: ISO 3166-1 numeric code.
      - `validFrom` string, date: Address valid-from date (ISO 8601).
      - `validTo` string, date: Address valid-to date (ISO 8601). Must be after <code>validFrom</code>.
    - `salutation` string: Salutation printed above the address. Allowed values: <code>MALE</code>, <code>FEMALE</code>, <code>MALE_FEMALE</code>, <code>FAMILY</code>.
    - `personFirstName` string: First name printed on the document (person recipients).
    - `personLastName` string: Last name printed on the document (person recipients).
    - `companyName` string: Company name printed on the document (company recipients).
  - `mailingAddress` object: Address used for postal delivery. Derived from the customer when omitted. Resolved and referenced the same way as <code>documentAddress</code>.
    - `customerId` integer: Customer the address belongs to.
    - `customerType` string: Partner type. Allowed values: <code>COMPANY</code>, <code>PERSON</code>.
    - `address` object: The postal address to print.
      - `id` integer: Address id. Use the id returned by the customer lookup; <code>0</code> or omitted for a new address.
      - `type` string, required: Partner type this address belongs to. <strong>Required.</strong> Allowed values: <code>COMPANY</code>, <code>PERSON</code>.
      - `addressType` string, required: Address type label. <strong>Required.</strong> Typically <code>MAIN</code> or <code>BILLING</code>.
      - `salutation` string: Salutation of the addressee. Allowed values: <code>MALE</code>, <code>FEMALE</code>, <code>MALE_FEMALE</code>, <code>FAMILY</code>.
      - `firstName` string: First name of the addressee (person addresses).
      - `lastName` string: Last name of the addressee (person addresses).
      - `companyName` string: Company name of the addressee (company addresses).
      - `street` string: Street name, without the house number.
      - `homeNumber` string: House number. <code>homeNumber</code> is the literal field name used throughout the KLARA address model — <code>houseNumber</code> is not accepted.
      - `additionalAddress` string: Additional address line (c/o, department, ...).
      - `addressLines` string: Combined street and house number. <strong>Deprecated</strong> — use <code>street</code> and <code>homeNumber</code> instead.
      - `city` object, required: City block. <strong>Required.</strong>
        - `id` integer: City id from the Swiss Post address directory.
        - `addressPostcode` string: Postcode (PLZ / NPA).
        - `cityName18` string, required: City name, 18-character Swiss Post variant. <strong>Required.</strong> <code>cityName18</code> is the literal field name of the Swiss Post address directory (18-character abbreviation) — it is not a typo or a leftover.
        - `cityName27` string, required: City name, 27-character Swiss Post variant. <strong>Required.</strong>
        - `onrp` integer: Swiss Post ONRP identifier of the locality.
        - `postcodeType` integer: Swiss Post postcode type.
        - `additionalPostcode` string: Additional postcode suffix (max 2 characters).
        - `basicPostcode` integer: Basic postcode.
        - `languageCode` integer: Swiss Post language code of the locality.
        - `state` object: Canton / state of the locality.
          - `id` integer: State id.
          - `code` string: Canton code (max 3 characters).
          - `description` string: Canton name.
        - `country` object: Country of the locality.
          - `id` integer: Country id.
          - `countryName` string: Country name.
          - `iso2Code` string: ISO 3166-1 alpha-2 code.
          - `iso3Code` string: ISO 3166-1 alpha-3 code.
          - `phoneCode` string: International dialling code.
          - `numericCode` string: ISO 3166-1 numeric code.
      - `validFrom` string, date: Address valid-from date (ISO 8601).
      - `validTo` string, date: Address valid-to date (ISO 8601). Must be after <code>validFrom</code>.
    - `salutation` string: Salutation printed above the address. Allowed values: <code>MALE</code>, <code>FEMALE</code>, <code>MALE_FEMALE</code>, <code>FAMILY</code>.
    - `personFirstName` string: First name printed on the document (person recipients).
    - `personLastName` string: Last name printed on the document (person recipients).
    - `companyName` string: Company name printed on the document (company recipients).
  - `mailingContact` integer: Contact person id used for postal delivery.
  - `emailDistribution` object: E-mail distribution settings recorded on the invoice. <strong>Stored only — this endpoint never sends the invoice.</strong>
    - `id` integer: Distribution entry id. Must be <code>0</code> or omitted for a new invoice.
    - `subject` string: Subject line stored for the distribution.
    - `emailAddress` string: Primary recipient address.
    - `ccEmailAddresses` string[]: Carbon-copy recipient addresses.
    - `replyTo` string: Reply-to address.
    - `emailText` string: Body text stored for the distribution.
  - `partnerContactId` integer: Contact person of the customer this invoice is addressed to.
  - `printedFileId` string: 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.

## Response `200`

Invoice updated successfully.

- Invoice: An invoice document (creation or update). The polymorphic discriminator <code>orderType</code> is always <code>INVOICE</code>. Server-managed read-only fields (<code>vatDate</code>, <code>lastModified</code>, <code>createDate</code>, <code>bookingDueDate</code>, <code>bookingNumbers</code>, <code>businessCaseId</code>) are populated on the response.
  - `id` integer: 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.
  - `orderType` string: Polymorphic discriminator. Must be <code>INVOICE</code>. Allowed values: <code>INVOICE</code>.
  - `status` string: 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.
  - `invoiceCode` string, required: Human-readable invoice code. Required and unique per company.
  - `invoiceNumber` integer: Sequential invoice number, typically obtained from <code>GET /invoices/next-invoice-number</code>.
  - `documentDate` string, 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.
  - `paymentDate` string, date: Payment due date (ISO 8601). Required when <code>amount</code> is greater than 0. Must be on or after <code>documentDate</code>.
  - `deliveryDate` string, date: Service delivery date (ISO 8601).
  - `issuedDate` string, date: Date the invoice was issued (ISO 8601).
  - `servicePeriodFrom` string, date: Service period start date (ISO 8601).
  - `servicePeriodTo` string, date: Service period end date (ISO 8601).
  - `servicePeriodPattern` string: Service period pattern label (e.g. <code>MONTHLY</code>, <code>YEARLY</code>).
  - `vatDate` string, date: VAT date. Server-managed (read-only).
  - `bookingDueDate` string, date: Booking due date returned by accounting. Server-managed (read-only).
  - `lastModified` string, date-time: Last modification timestamp. Server-managed (read-only).
  - `createDate` string, date-time: Creation timestamp. Server-managed (read-only).
  - `amount` number: 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>
  - `usingVAT` boolean: 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).
  - `usingExportVat` boolean: 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.
  - `hasCompanyVat` boolean: 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.
  - `subject` string: Free-text invoice subject.
  - `closeAndSignature` string: Free-text closing remarks / signature block.
  - `ourReference` string: Internal sender reference.
  - `yourReference` string: Customer-side reference (e.g. PO number).
  - `companyCityAndDate` string: Header line such as 'Zurich, 28.05.2026'.
  - `postMethod` string: Distribution channel recorded on the invoice. <strong>Stored only — creating an invoice does not deliver it</strong> (no email/ePost/eBill/print&amp;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>.
  - `delivery` string: Delivery method label (free text).
  - `ibanNumberCHF` string: CHF IBAN for payment. Validated by downstream service.
  - `ibanNumberCHW` string: WIR-franc IBAN for payment.
  - `wirAcceptanceRate` number: WIR acceptance percentage.
  - `referenceNumber` string: QR / ISR reference number.
  - `qrInvoice` boolean: When <code>true</code>, the invoice is rendered/booked as a Swiss QR-invoice. Defaults to false.
  - `fromAutoInvoicing` boolean: Indicates the invoice was generated by auto-invoicing. Defaults to false.
  - `fromInvoiceRun` boolean: Indicates the invoice was produced by a recurring invoice run. When <code>true</code>, accounting booking and inventory transactions are skipped. Defaults to false.
  - `invoiceType` string: Invoice type. Allowed values: <code>MANUAL</code>, <code>CREDIT_DEBIT</code>.
  - `originDistributionMethod` string: 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>.
  - `templateId` integer: Template id used to create this invoice.
  - `runHistoryId` integer: Recurring invoice run history id.
  - `settledAmount` number: Klara-Pay settled amount (online shop only).
  - `bookingNumbers` string: Accounting booking-number string. Server-managed (read-only).
  - `businessCaseId` integer: Accounting business case id. Server-managed (read-only).
  - `bookingStatus` string: Booking status (e.g. <code>OPEN</code>, <code>PARTIAL</code>, <code>PAID</code>). Server-managed (read-only).
  - `bookingMessage` string: Optional booking error/info code (e.g. <code>INVALID_SUBSCRIPTION_FOR_ACCOUNTING</code>). Server-managed (read-only).
  - `bookingSealed` boolean: Whether the booking has been finalized. Server-managed (read-only).
  - `fiscalYearHasCreatedAuto` boolean: Whether a fiscal year was auto-created during booking. Server-managed (read-only).
  - `createBy` string: Server-assigned audit user (token subject). Server-managed (read-only).

## Other responses

- `400`: Data invalid<br/><br/><strong>Error codes</strong> for this response (the <code>code</code> field of the response body):<ul><li><code>invoice.vat_code_missing</code> — At least one orderItems[] entry set VAT on vatType, vatCase or the top-level vatCode while leaving vat.vatCode empty. Only vat.vatCode is stored, so that line would have been booked at 0%. Move the code to vat.vatCode, or send "0" ("No VAT") for a position that genuinely carries none.</li><li><code>invoice.vat_rate_mismatch</code> — At least one orderItems[] entry sent a vat.rate that is not the rate of its vat.vatCode. The booking always uses the code's rate, so the invoice document would state a different percentage than the accounting record. Send the matching rate, or omit vat.rate and let the server fill it in.</li></ul>Failures detected by a downstream service carry that service's own <code>code</code>, which this reference does not enumerate, so the <code>code</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<br/><br/>Failures detected by a downstream service carry that service's own <code>code</code>, which this reference does not enumerate, so the <code>code</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<br/><br/>Failures detected by a downstream service carry that service's own <code>code</code>, which this reference does not enumerate, so the <code>code</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.
- `404`: Resource not found<br/><br/>Failures detected by a downstream service carry that service's own <code>code</code>, which this reference does not enumerate, so the <code>code</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<br/><br/>Failures detected by a downstream service carry that service's own <code>code</code>, which this reference does not enumerate, so the <code>code</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.<br/><br/>Failures detected by a downstream service carry that service's own <code>code</code>, which this reference does not enumerate, so the <code>code</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)