Looking for the ePost APIs? developer.epost.ch

KLARA API documentation

Integrate accounting, articles, customers, payroll and time tracking directly with KLARA business software. Everything on this site is about KLARA only.

97Endpoints
5Domains
RESTJSON over HTTPS
Getting started From API key to your first response in under 15 minutes. Authentication API key or token flow, and when to use which. Sending documents Let KLARA pick the delivery channel automatically. Payroll data New: submit variable salary items to a payslip. Response languages Get account names and labels in DE, FR, IT or EN. API reference All 97 integration endpoints, grouped by domain. Changelog What changed with each API release. Known limitations What the API cannot do yet. Read before you build.

Getting started

  1. Prerequisites

    An active KLARA account with a company set up, a user role that allows managing users, and an HTTP client. HTTP/1.0 is no longer supported, so use HTTP/1.1 or HTTP/2.

  2. Create an API key in KLARA

    Go to Benutzer, add a new API key, give it a name and assign at least one KLARA user role. Suggested naming convention: integration-payroll-prod.

  3. Choose roles and permissions

    Assign only the roles your use case needs. Any user holding that role can authenticate with the key. See Roles & permissions.

  4. Set up authentication

    Send the key as an X-API-KEY header, or obtain a bearer token via the token flow. See Authentication.

  5. Make your first API call

    List your articles. This is a read-only request that touches no data.

    curl -X GET "https://api.klara.ch/core/latest/articles" \
  -H "X-API-KEY: $KLARA_API_KEY" \
  -H "Accept: application/json"

    A successful call returns 200 with a JSON array. If you get 401, check the header name and that the key is assigned to a role. See Authentication.

    This example only reads, which is deliberate: there is no separate test environment, so every call works on your live data. See Environments.

  6. Where to go next

    Browse the reference by domain, or read the guides on errors, pagination and versioning.

API basics

Everything you need once, so you never have to guess again.

API routes

All endpoints live on https://api.klara.ch. Paths in this reference are relative and must be combined with the host:

GET /core/v1/invoices/42
→ https://api.klara.ch/core/v1/invoices/42

Three prefixes are in use. /core/v1 holds accounting, finance and payroll, /core/v2 holds company and individual profiles, and /core/latest still holds articles, customers and authentication.

HTTP verbs

VerbUsed forEndpoints
GETRetrieving resources55
PUTReplacing a resource completely10
POSTCreating resources, and some actions such as /send25
DELETERemoving a resource7

97 endpoints in total, which is the same number as in the reference below and in the downloadable specification.

The KLARA API does not use PATCH. To change part of a resource, send a complete PUT. Read the current state first if you do not hold it.

Headers

HeaderValueWhen
X-API-KEYyour API keyAPI key authentication
AuthorizationBearer <JWT>Token authentication
Acceptapplication/json Almost everywhere. Three endpoints return binary or PDF instead, see below
Content-Typedepends on the endpoint On any request with a body. Most take application/json, the token endpoints take application/x-www-form-urlencoded and the upload endpoints take multipart/form-data, see below
Accept-Languagede-CH, fr-CH, it-CH or en Optional, on the endpoints that return translated labels

Media types

Request bodies

Send the matching Content-Type. Form-encoded endpoints reject a JSON body, which is the most common reason a first token request fails.

Media typeEndpointsWhich ones
application/json22every endpoint that has one
application/x-www-form-urlencoded4POST /core/latest/generic-token
POST /core/latest/tenants
POST /core/latest/token
POST /core/latest/token/by-microsoft
multipart/form-data3POST /core/latest/articles/{article-id}/images
POST /core/latest/companies/{company-id}/documents
PUT /core/latest/articles/{article-id}/images/{image-id}

Responses

Ask for what the endpoint returns. Accept: application/json is correct almost everywhere, but not for the binary and PDF responses below.

Media typeEndpointsWhich ones
application/json97every endpoint that has one
application/octet-stream2GET /core/latest/articles/{article-id}/images/{image-id}
POST /core/latest/payroll-interface-file
application/pdf1POST /core/v1/invoices/{id}/printed-document

Errors

Most error responses use this shape:

{
  "uuid":        "b3f1c8e2-...",
  "createdTime": "2026-07-30T09:12:44Z",
  "code":        "VALIDATION_FAILED",
  "message":     "Human readable description"
}

The authentication endpoints use the OAuth-style shape instead:

{ "error": "invalid_grant", "error_description": "Bad credentials" }

The uuid identifies one specific occurrence. Include it in support requests. It is the fastest route to an answer.

The field detail still appears in some responses but is deprecated. Do not build on it.

OpenAPI specification

Download the specification The full KLARA API is published as an OpenAPI 3.0.3 document. Generate clients, import it into Postman or Insomnia, spin up a mock server, or run contract tests against it.

klara-openapi.json This is the specification this documentation was generated from. Both are updated when a new API version is released.

Authentication

The KLARA API accepts two mechanisms. Most endpoints accept either.

MechanismHowBest for
apiKeyAuthHeader X-API-KEY Server-to-server integrations bound to one company
bearerAuthHeader Authorization: Bearer <JWT> User-context flows, multi-tenant tools

Token flow

A KLARA user can belong to several tenants. Resolve the tenant first, then request a token.

POST /core/latest/tenants     # returns tenant id + company id
POST /core/latest/token       # grant_type: password | refresh_token | token_exchange
The token endpoints expect a form body, not JSON All four take Content-Type: application/x-www-form-urlencoded. Sending JSON is the most common reason a first token request fails. Full media type list under Requests and responses.

Which fields each grant needs

The specification does not mark any of these form fields as required, so the table below is taken from the endpoint descriptions rather than from the schema. Treat it as the working contract and expect 400 if a field is missing.

Endpointgrant_typeRequired fields Returns
POST /core/latest/tokenpassword username, password, tenant_id, company_id Access token scoped to one company, plus refresh token
refresh_tokenrefresh_token A new access token without re-sending credentials
token_exchange subject_token, audience OAuth 2.0 Token Exchange, RFC 8693. Pass subject_token as the raw upstream token value, without the Bearer  prefix. The only audience value the specification documents is cossa
POST /core/latest/generic-token passwordusername, password Access token for the user, not bound to a company
refresh_tokenrefresh_token A new access token
POST /core/latest/token/by-microsoftnot applicable microsoft_access_token, tenant_id System token
POST /core/latest/tenantsnot applicable username and password, or access_token The user's tenants with their tenant and company ids

Which one do I use? /core/latest/token returns a token bound to one tenant and company, which is what you want for a normal integration. /core/latest/generic-token takes no tenant or company and returns a token for the user alone. If you are unsure, use /core/latest/token.

Complete example, password grant

curl -X POST "https://api.klara.ch/core/latest/tenants" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "username=$KLARA_USER" \
  --data-urlencode "password=$KLARA_PASSWORD"
# → pick the tenant id and company id you want to work with

curl -X POST "https://api.klara.ch/core/latest/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=password" \
  --data-urlencode "username=$KLARA_USER" \
  --data-urlencode "password=$KLARA_PASSWORD" \
  --data-urlencode "tenant_id=$TENANT_ID" \
  --data-urlencode "company_id=$COMPANY_ID"

# use the access_token from the response on any other endpoint
curl -X GET "https://api.klara.ch/core/v1/customers?limit=10" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Accept: application/json"

Refreshing

curl -X POST "https://api.klara.ch/core/latest/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "refresh_token=$REFRESH_TOKEN"
Errors from the token endpoints carry no response body 400, 401, 429 and 500 on /core/latest/token, /core/latest/generic-token and /core/latest/token/by-microsoft define no body in the specification. You get the status code and nothing else, so log the request you sent. POST /core/latest/tenants is the exception and returns an error and error_description pair.

Endpoints that need no authentication

4 endpoints require no authentication, because they are how you obtain a token in the first place. Everything else in this reference accepts either an API key or a bearer token, and no endpoint accepts only one of the two.

Submitting variable payroll data

Available now Payroll used to be read-only through file exports. Three endpoints let you add variable salary items (hours, allowances, bonuses) directly to an employee's payslip.

The flow is three calls. You need the employee first, then the payslip that is still editable, then you post the item.

1. GET  /core/v1/employees/short-info
      → find the employee, take their employeeId

2. GET  /core/v1/payroll/employees/{employeeId}/addable-salary-items
      → returns which item types may be added, plus contractId and payslipId

3. POST /core/v1/payroll/contracts/{contractId}/payslips/{payslipId}/salary-items
      → adds the item and recalculates the month

What you can submit

Salary items come in the types Base, Percent, Quantity, Amount and Comments. Step 2 tells you which types the payslip accepts. Do not guess, the answer depends on the employee's contract.

Finding the right employee

GET /core/v1/employees/short-info returns a lightweight directory: id, name, email, employee number, workplace and status. It supports search-key, filter-by-status, workplace-ids, sort-field and sort-direction. This is the most capable filtering in the whole API today.

Two constraints worth knowing before you build
  • Only editable payslips. Once a payslip is sealed, it no longer accepts items. Your integration needs to run before the salary run is closed, so plan the timing.
  • Recalculation is triggered per call. Pass recalculate=false when adding several items in sequence, then recalculate once at the end. Otherwise you recompute the month for every single item.

Getting responses in German, French, Italian or English

Switzerland has four language regions, and so does your customer base. A number of endpoints return content that is translated, for example account names, VAT descriptions, booking-type labels and salary-item descriptions. You choose the language with the standard Accept-Language request header.

curl -X GET "https://api.klara.ch/core/v1/accounting/accounts"   -H "X-API-KEY: $KLARA_API_KEY"   -H "Accept-Language: fr-CH"   -H "Accept: application/json"

The header takes an IETF language tag. The tags documented in the specification are de-CH, fr-CH, it-CH and en. Where a translation is missing, the response falls back to German. Some endpoints fall back to the language configured on the tenant instead when you omit the header, so pass it explicitly if you care about the result.

Where it applies

23 endpoints accept Accept-Language. Look for it in the parameter list of any endpoint in the API reference. It is most common across accounting: accounts, booking types, VAT types, VAT cases, business-case templates and financial years. It also affects POST /core/v1/bookings, where it selects the language of localised error messages, and the payroll endpoint that lists addable salary items.

Building your own language picker

Two schemas return not just the resolved text but the complete set of translations, keyed by language tag. Use these when your own interface offers a language switch and you would rather not call the API once per language.

SchemaFields
PublicApiBusinessCaseTemplate i18n, keywordI18ns
PublicApiVatType i18n, i18nShortName
This documentation is in English The reference text is generated from the API specification, which is maintained in English. The language of the documentation is independent of the language of the API responses: you can read this page in English and still receive French or Italian content from the endpoints above.

Keeping your API key safe

An API key authenticates as a role inside your company. Treat it like a password.

Sending documents with smart delivery

You do not have to decide how an invoice reaches your customer. Book it, then call POST /core/v1/invoices/{id}/send without a channel. KLARA routes it through EPOST, EBILL, SEND_EMAIL and Print&Send, and only fails if none of them can deliver.

Smart delivery

Omit the channel query parameter. There is no request body.

curl -X POST "https://api.klara.ch/core/v1/invoices/42/send"   -H "X-API-KEY: $KLARA_API_KEY"   -H "Accept: application/json"

Forcing one channel

Pass channel as a query parameter to force exactly that channel. If the recipient is not eligible for it, for example no email on file, not registered for eBill, or Print&Send not subscribed, the call fails with 400.

curl -X POST "https://api.klara.ch/core/v1/invoices/42/send?channel=SEND_EMAIL"   -H "X-API-KEY: $KLARA_API_KEY"   -H "Accept: application/json"
ValueChannelCan be forced
SEND_EMAILEmail to the recipientyes
EPOSTePost digital letterboxyes
EBILLeBill, straight into the recipient's e-bankingyes
A_POSTPrinted and posted, A Postyes
B_POSTPrinted and posted, B Postyes
PRINT_AND_MANUAL_SENDPrinted for manual dispatch no, rejected with 400

PRINT_AND_MANUAL_SEND is a value you may see on Invoice.postMethod, but it is not a deliverable channel and cannot be forced.

Two things that will bite you
  • The invoice must already be booked. Drafts and cancelled invoices are rejected with 400. Create and book it first through POST /core/v1/invoices with status=INVOICED.
  • This call is not idempotent. Every successful call performs a real delivery, sending an email or handing a letter to the postal channel, and overwrites the invoice's recorded post method. Do not retry blindly after a success. Remember there is no test environment, so this happens on live data.

Requires the FINANCE permission on the target company. The invoice PDF is rendered on demand if it has not been printed yet.

Why ePost and eBill appear here KLARA and ePost are both products of ePost Service AG. ePost and eBill are two of the delivery channels KLARA can use. You reach them through the KLARA API, with no separate integration. Building on the ePost Communication Platform itself? See developer.epost.ch.

Roles & permissions

An API key is linked to one or more KLARA roles. Any user holding that role can use the key to authenticate for that company. You create and manage keys under Benutzer in KLARA.

Least privilege matters more than usual here Assigning a key to an employee role grants access to all Public API endpoints available to that role, regardless of the restrictions configured for that user inside KLARA. Create one key per use case, with the narrowest role that works, and rotate keys when team members change.

Which permission does an endpoint need?

Where the API declares a permission requirement, it is shown in the endpoint's detail block in the API reference. Look for Required permission. You will see constants such as ACCOUNTING, FINANCE, ARTICLE_READ_ONLY or COMPENSATION_TIME_TRACKING. Some endpoints state explicitly that no particular permission is required.

If an endpoint shows no permission and you receive 403, the role assigned to your key does not cover it. Contact support and include the endpoint and the uuid from the error response, and you will get a definitive answer.

Limits, pagination and environments

Environments

There is one environment: https://api.klara.ch. It serves your live company data.

There is no separate test environment Every request you send acts on real data in your company. Plan for that:
  • Explore with GET first. Reading is safe. Get familiar with the data shapes before you write anything.
  • Writes take effect immediately. A created invoice is a real invoice, and a salary item added to a payslip is real payroll data.
  • Use a separate key for development, named so you can recognise and revoke it, for example integration-dev. Delete it when you go live.
  • If you can, develop against a company you control rather than a client's production company.

Rate limiting

The API enforces a rate limit. When you exceed it, the response is 429 API rate limit exceeded. Nearly every endpoint can return it.

The limit is not published yet The specification declares the 429 response but names no threshold, no time window, no counting scope and no Retry-After or rate limit headers. Until those are confirmed, treat the guidance below as the contract and do not assume a number.

How to build for it

If your integration needs a higher limit, talk to us and describe the volume you expect.

Pagination

8 endpoints accept pagination parameters:

EndpointParameters
GET /core/latest/article-categorieslimit no offset, only the first page is reachable
GET /core/latest/article-filterslimit no offset, only the first page is reachable
GET /core/latest/articleslimit, offset
GET /core/latest/articles/article-and-variantslimit, offset
GET /core/latest/articles/searchlimit, offset
GET /core/v1/accounting/business-case-templateslimit, offset
GET /core/v1/accounting/master-vatslimit, offset
GET /core/v1/customerslimit, offset

Searching and filtering

8 endpoints accept search or filter parameters as part of the query string. Anything not listed here has to be fetched and filtered in your own code.

EndpointParameters
GET /core/latest/article-categoriesactive-status, keyword
GET /core/latest/article-filtersactive-status, keyword
GET /core/latest/articles/searchkeyword
GET /core/v1/accounting/business-casesdateForFilteringCompanyVat, dateForFilteringFiscalYear
GET /core/v1/accounting/business-cases/v2dateForFilteringCompanyVat, dateForFilteringFiscalYear
GET /core/v1/bank-reconciliation/open-positionsgeneral-search, payment-date-from, payment-date-to, position-status
GET /core/v1/customerssearch-key, status
GET /core/v1/employees/short-infofilter-by-status, search-key, sort-direction, sort-field, workplace-ids

Invoices are the most important gap: they cannot be listed or filtered at all, so you have to keep the ids you created. See Known limitations.

API reference

97 endpoints. Click any endpoint for its description, parameters, request body and responses. Everything below is generated from klara-openapi.json; ePost endpoints and the eBill, SPS, email and print partner channels are removed by the build.

Want to try a request? Download the OpenAPI specification and import it into Postman, Insomnia or Bruno. You get every endpoint, parameter and example as a ready-made collection. Never paste a production API key into a tool you do not control.

Finance & Accounting

Accounting24

GET/core/v1/accounting/accountskey / tokenList Klara master chart-of-account rows.
Returns the canonical debit/credit accounts maintained by Klara as the seed of any company's bookkeeping. The data is global — the same chart of accounts is returned for every tenant, so there are no tenant or company path parameters. When the optional legal-form query parameter is supplied, only accounts that carry a translation for that legal form are returned, and the name field is resolved from the legal-form-specific translation column. The Accept-Language header selects which translation is used; if absent or unsupported the platform default applies. The endpoint is a pure read — idempotent, no side effects. Any authenticated bearer token is accepted; the downstream service declares no role or permission requirement on this endpoint.
Required permission

none The specification states that no role or permission is required for this endpoint.

Parameters 2
NameDescription
legal-form
query string
Restricts the result to accounts that carry a translation for the given Swiss legal form, and resolves name from that legal-form-specific column. Allowed values: LIMITED_LIABILITY, CORPORATION, OR, INDIVIDUALLY_OWNED_COMPANY, ASSOCIATION, SIMPLE_PARTNERSHIP, GENERAL_PARTNERSHIP, LIMITED_PARTNERSHIP, COOPERATIVE_COMPANY, FOUNDATION.
Allowed values: LIMITED_LIABILITY, CORPORATION, OR, INDIVIDUALLY_OWNED_COMPANY, ASSOCIATION, SIMPLE_PARTNERSHIP, GENERAL_PARTNERSHIP, LIMITED_PARTNERSHIP, COOPERATIVE_COMPANY, FOUNDATION
example: CORPORATION
Accept-Language
header string
IETF language tag used to resolve the localized name field of each account. Examples: de-CH, fr-CH, it-CH, en.
example: de-CH
Responses 5
200 Master accounts, sorted by code ascending. Empty array when the chart of accounts has not been seeded yet. show body

application/json array of PublicApiAccount

Array of PublicApiAccount.

  • id integer (int64) format: int64 example: 42
    Internal identifier of the master account.
  • code integer (int32) format: int32 example: 1020
    Numeric account code as printed on the chart of accounts.
  • name string example: Bank
    Localized account name. Resolved against the request's Accept-Language and, when legal-form is supplied, against the legal-form-specific translation.
  • tags string example: bank;konto
    Free-text keyword tokens associated with the account, used by client-side search. Tokens are delimited by comma or semicolon.
  • links string example: bank_account
    Linked-account references used by report computations.
  • accountReportLinks string example: bank_account
    Report-grouping references used to assemble balance-sheet / P&L groupings.
  • initialBalanceSheet boolean example: False
    True when the account is part of the initial opening-balance sheet.
  • visibleFirstFiscalYear boolean example: True
    True when the account is visible during the first fiscal year of a new company.
  • visibleFromSecondFiscalYear boolean example: True
    True when the account becomes visible from the second fiscal year onwards.
  • vatAccount boolean example: False
    True when the account is reserved for VAT postings.
  • accountReportFilters array of PublicApiAccountReportFilter
    Report-grouping configuration rows attached to this account.
    show fields

    Array of PublicApiAccountReportFilter.

    • display string example: Operating expenses
      Human-readable label of the report bucket this account contributes to.
    • linkAccountValue string example: 6000
      Underlying linked-account value used by the accounting engine to resolve the bucket.
  • notManuallyAdded boolean example: True
    True when the account was seeded automatically (not added by an end user).
401 No Authorization header found or invalid token no response body
404 The supplied legal-form value does not match any known legal form. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/accounts/account-displayingkey / tokenList the account-displaying picker rows for the authenticated company.
Returns a flat list of AccountDisplaying rows for every account in the caller's company chart of accounts. Each row represents one selectable combination that a bookkeeper can pick when entering a manual journal line. Tenant and company are derived from the bearer token — there are no tenant or company path parameters.

How rows are produced: For each master account the downstream service checks whether the account carries any linked sub-account definitions (e.g. a bank account linked to specific bank-accounts, a VAT account linked to VAT-rate items). If the account has no sub-account definitions, exactly one bare row is emitted with combinedCode equal to the bare account code (e.g. "3000"), linkType equal to null, and specificationItem equal to null. If the account has one or more sub-account link specifications, one row is emitted per individual sub-account entry, numbered sequentially across all link types with a 0-based counter suffix: "1020-0", "1020-1", …

combinedCode: "<accountCode>-<i>" when a sub-account exists (e.g. "1020-0"), or the bare account code string (e.g. "3000") when linkType is null. The suffix index is a flat 0-based counter per account, spanning all link types in declaration order.

combinedName: "<accountName> (<subAccountDisplay>)" when a sub-account exists (e.g. "Bank (UBS)"), or the bare account name (e.g. "Bürobedarf") when linkType is null.

parentAccount: the full master account this row belongs to. Always populated, including for bare rows.

linkType: the link-type category name (e.g. "BANK", "CUSTOMER", "VAT_RATE"). null when the account has no sub-account definitions.

linkDisplay: the human-readable label for the link type in the current locale (e.g. "Bank account"). Falls back to the German label when no translation exists for the requested language. null when linkType is null.

linkOptional: true when the sub-account selection is optional for the user (link keys are separated by ; in the account definition); false when selecting a sub-account is mandatory (link keys separated by ,); null when the account has no sub-account definitions.

specificationItem: the resolved sub-account entry for this row. Its link field is the URI that must be round-tripped back to the booking endpoint when the user selects this row. Its display field is the human-readable label shown to the bookkeeper (e.g. "UBS", "8.1 %"). null when linkType is null.

Row order is stable: accounts are sorted by code ascending (same order as GET /core/v1/accounting/accounts); sub-account rows within each account preserve the link-type declaration order and then the entry order returned by the underlying service.

The endpoint is a pure read — idempotent, no side effects. The caller must hold the ACCOUNTING permission on the company in scope.
Required permission

ACCOUNTING

Parameters 2
NameDescription
legal-form
query string
When supplied, restricts the result to accounts that carry a translation for the given Swiss legal form and resolves the parentAccount.name field from the legal-form-specific translation column. When omitted, all accounts are returned and account.name is resolved from the generic language column. Allowed values: LIMITED_LIABILITY, CORPORATION, OR, INDIVIDUALLY_OWNED_COMPANY, ASSOCIATION, SIMPLE_PARTNERSHIP, GENERAL_PARTNERSHIP, LIMITED_PARTNERSHIP, COOPERATIVE_COMPANY, FOUNDATION.
Allowed values: LIMITED_LIABILITY, CORPORATION, OR, INDIVIDUALLY_OWNED_COMPANY, ASSOCIATION, SIMPLE_PARTNERSHIP, GENERAL_PARTNERSHIP, LIMITED_PARTNERSHIP, COOPERATIVE_COMPANY, FOUNDATION
example: CORPORATION
Accept-Language
header string
IETF language tag used to localize the parentAccount.name field of each row and the linkDisplay label. Falls back to German when no translation exists for the requested language. Examples: de-CH, fr-CH, it-CH, en.
example: de-CH
Responses 6
200 Flat list of account-displaying rows, sorted by account code ascending. Each row contains combinedCode, combinedName, parentAccount, and the link fields populated for sub-account rows or null for bare rows. Returns an empty array when no accounts match the supplied legal-form. show body

application/json array of PublicApiAccountDisplaying

Array of PublicApiAccountDisplaying.

  • combinedCode string example: 1020-0
    Picker key. "<accountCode>-<i>" when a sub-account exists (e.g. "1020-0"); the bare account code string (e.g. "3000") when linkType is null. The suffix index is a flat 0-based counter per account, spanning all link types in declaration order.
  • combinedName string example: Bank (UBS)
    Picker label. "<accountName> (<subAccountDisplay>)" when a sub-account exists (e.g. "Bank (UBS)"); the bare account name (e.g. "Bürobedarf") when linkType is null.
  • parentAccount object
    A master account from Klara's global chart of accounts.
    show fields
    • id integer (int64) format: int64 example: 42
      Internal identifier of the master account.
    • code integer (int32) format: int32 example: 1020
      Numeric account code as printed on the chart of accounts.
    • name string example: Bank
      Localized account name. Resolved against the request's Accept-Language and, when legal-form is supplied, against the legal-form-specific translation.
    • tags string example: bank;konto
      Free-text keyword tokens associated with the account, used by client-side search. Tokens are delimited by comma or semicolon.
    • links string example: bank_account
      Linked-account references used by report computations.
    • accountReportLinks string example: bank_account
      Report-grouping references used to assemble balance-sheet / P&L groupings.
    • initialBalanceSheet boolean example: False
      True when the account is part of the initial opening-balance sheet.
    • visibleFirstFiscalYear boolean example: True
      True when the account is visible during the first fiscal year of a new company.
    • visibleFromSecondFiscalYear boolean example: True
      True when the account becomes visible from the second fiscal year onwards.
    • vatAccount boolean example: False
      True when the account is reserved for VAT postings.
    • accountReportFilters array of PublicApiAccountReportFilter
      Report-grouping configuration rows attached to this account.
      show fields

      Array of PublicApiAccountReportFilter.

      • display string example: Operating expenses
        Human-readable label of the report bucket this account contributes to.
      • linkAccountValue string example: 6000
        Underlying linked-account value used by the accounting engine to resolve the bucket.
    • notManuallyAdded boolean example: True
      True when the account was seeded automatically (not added by an end user).
  • linkType string example: BANK
    Link-type category. Identifies the kind of entity the sub-account refers to. Common values: VAT_RATE, VAT_CASE, BANK, CUSTOMER, SUPPLIER, EMPLOYEE, SOCIAL_INSURANCE, TAX_AT_SOURCE, EQUITY, TANGIBLE_ASSET, IMMOBILE_TANGIBLE_ASSET, UNFINISHED_PRODUCTS, FINISHED_PRODUCTS, NON_BILLED_SERVICES, INVENTORY_CHANGE_MATERIAL, INVENTORY_CHANGE_GOODS, LONG_TERM_INTEREST_BEARING, OTHER_LONG_TERM_INTEREST_BEARING, GIFT_CARD, VARIOUS. null when the account has no sub-account definitions.
  • linkDisplay string example: Bank account
    Human-readable label for the link type in the requested Accept-Language. Falls back to the German label when no translation exists for the requested language. null when linkType is null.
  • linkOptional boolean example: False
    true when the sub-account selection is optional for the user (link keys are separated by ; in the account definition); false when selecting a sub-account is mandatory (link keys separated by ,); null when the account has no sub-account definitions.
  • specificationItem object
    One concrete sub-account choice; carries the URI to round-trip to the booking endpoint and the display label.
    show fields
    • id string example: 42
      Stable identifier of the underlying entity (e.g. bank-account id, VAT-rate id, customer id). May be null for synthesized entries.
    • filteredBy string example:
      Optional filter token used by the Accounting UI to narrow the picker. Empty for most link types.
    • display string example: UBS
      Human-readable label shown in the picker (e.g. "UBS" for a bank account, "8.1 %" for a VAT rate).
    • link string example: bank_account:/luz_finance/api/5fe76717-60a0-4b20-9819-255a957f3eb9/companies/1/bank-accounts/42
      Canonical URI for this sub-account choice. MUST be round-tripped verbatim to the booking-creation endpoint when the row is selected.
    • additionalAttribute string example:
      Free-form additional attribute attached by the link-type supplier. Most types leave this empty.
    • snippetReference string example:
      Optional snippet reference returned by the underlying entity (used by some link types to carry a template hint).
    • value string example: 8.1
      Optional raw value associated with the entry (e.g. the VAT percentage as a decimal string).
    • validFrom string (date) format: date example: 2024-01-01
      Inclusive start of the validity window of the underlying entity (ISO yyyy-MM-dd). null when not applicable.
    • validTo string (date) format: date example: 2024-12-31
      Inclusive end of the validity window of the underlying entity (ISO yyyy-MM-dd). null when open-ended.
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 The company associated with the caller's session could not be resolved by the downstream accounting service, or the supplied legal-form value does not match any known legal form. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/accounts/by-code/{accountCode}key / tokenResolve a Klara master account by its chart-of-account code.
Loads a single master account row from Klara's global chart of accounts, identified by its numeric accountCode. The data is global — the same chart of accounts is shared across every tenant, so there are no tenant or company path parameters. When the optional legal-form query parameter is supplied, the name field is resolved from the legal-form-specific translation column instead of the generic one. The Accept-Language header selects which translation is used; if absent or unsupported the platform default applies. The endpoint is a pure read — idempotent, no side effects. Any authenticated bearer token is accepted; the downstream service declares no role or permission requirement on this endpoint.
Required permission

none The specification states that no role or permission is required for this endpoint.

Parameters 3
NameDescription
accountCode required
path string
Numeric chart-of-account code as printed on the Klara master chart of accounts (e.g. 1000 for cash, 6000 for material expense).
example: 6000
legal-form
query string
When supplied, resolves name from the legal-form-specific translation column. Allowed values: LIMITED_LIABILITY, CORPORATION, OR, INDIVIDUALLY_OWNED_COMPANY, ASSOCIATION, SIMPLE_PARTNERSHIP, GENERAL_PARTNERSHIP, LIMITED_PARTNERSHIP, COOPERATIVE_COMPANY, FOUNDATION.
Allowed values: LIMITED_LIABILITY, CORPORATION, OR, INDIVIDUALLY_OWNED_COMPANY, ASSOCIATION, SIMPLE_PARTNERSHIP, GENERAL_PARTNERSHIP, LIMITED_PARTNERSHIP, COOPERATIVE_COMPANY, FOUNDATION
example: CORPORATION
Accept-Language
header string
IETF language tag used to resolve the localized name field of the account. Examples: de-CH, fr-CH, it-CH, en.
example: de-CH
Responses 5
200 The master account matching accountCode. show body

application/json PublicApiAccount

  • id integer (int64) format: int64 example: 42
    Internal identifier of the master account.
  • code integer (int32) format: int32 example: 1020
    Numeric account code as printed on the chart of accounts.
  • name string example: Bank
    Localized account name. Resolved against the request's Accept-Language and, when legal-form is supplied, against the legal-form-specific translation.
  • tags string example: bank;konto
    Free-text keyword tokens associated with the account, used by client-side search. Tokens are delimited by comma or semicolon.
  • links string example: bank_account
    Linked-account references used by report computations.
  • accountReportLinks string example: bank_account
    Report-grouping references used to assemble balance-sheet / P&L groupings.
  • initialBalanceSheet boolean example: False
    True when the account is part of the initial opening-balance sheet.
  • visibleFirstFiscalYear boolean example: True
    True when the account is visible during the first fiscal year of a new company.
  • visibleFromSecondFiscalYear boolean example: True
    True when the account becomes visible from the second fiscal year onwards.
  • vatAccount boolean example: False
    True when the account is reserved for VAT postings.
  • accountReportFilters array of PublicApiAccountReportFilter
    Report-grouping configuration rows attached to this account.
    show fields

    Array of PublicApiAccountReportFilter.

    • display string example: Operating expenses
      Human-readable label of the report bucket this account contributes to.
    • linkAccountValue string example: 6000
      Underlying linked-account value used by the accounting engine to resolve the bucket.
  • notManuallyAdded boolean example: True
    True when the account was seeded automatically (not added by an end user).
401 No Authorization header found or invalid token no response body
404 No master account exists for the supplied accountCode, or the supplied legal-form value does not match any known legal form. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/booking-typeskey / tokenList Klara master accounting booking types.
Returns the canonical catalog of accounting booking types maintained by Klara — the stable set of bookkeeping operations (general-ledger postings, payable / receivable invoices, payments, credit notes, prepayments, amortizations, delimitations) that every Klara company can post against. The data is global — the same catalog is returned for every tenant, so there are no tenant or company path parameters. The Accept-Language header selects which translation of the human-readable description is returned; if absent or unsupported the German translation is used as a fallback. The endpoint is a pure read — idempotent, no side effects. Any authenticated bearer token is accepted; the downstream service declares no role or permission requirement on this endpoint.
Required permission

none The specification states that no role or permission is required for this endpoint.

Parameters 1
NameDescription
Accept-Language
header string
IETF language tag used to resolve the localized description of each booking type. Examples: de-CH, fr-CH, it-CH, en. Falls back to the German translation when no translation exists for the requested language.
example: de-CH
Responses 4
200 Master booking types, ordered by code ascending. Empty array when the catalog has not been seeded yet. show body

application/json array of PublicApiBookingType

Array of PublicApiBookingType.

  • code object example: AP_INVOICE
    Stable machine-readable code of the booking type.
    Allowed values: GENERAL_LEDGER, AP_INVOICE, AP_PAYMENT, AR_INVOICE, AR_PAYMENT, AP_PREPAYMENT, AP_PREPAYUSE, AR_PREPAYMENT, AR_PREPAYUSE, AR_CREDITNOTE, AR_CREDITUSE, AP_CREDITNOTE, AP_CREDITUSE, AMORTIZATION, SELLOFF_AMORTIZATION, DELIMIT
  • description string example: Kreditorenrechnung
    Localized human-readable description of the booking type. Resolved against the request's Accept-Language header; falls back to the German translation when no translation exists for the requested language.
401 No Authorization header found or invalid token no response body
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/business-case-templateskey / tokenList Klara master accounting business-case templates.
Returns the global catalog of business-case templates — the manual-journal categories that drive the booking form (operating expenses, salary payments, asset purchases, …). The catalog is global Klara reference data: the same list is returned for every tenant, so there are no tenant or company path parameters. The Accept-Language header selects which translation of the human-readable display label is returned; if absent or unsupported the German translation is used as a fallback and the full per-language i18n / keywordI18ns maps are returned for client-side rendering. Optional orderColumns / offset / limit query parameters are forwarded verbatim to the downstream catalog for ordering and pagination. The endpoint is a pure read — idempotent, no side effects. Requires a bearer token whose principal carries the ACCOUNTING_GET_BUSINESS_CASE_TEMPLATE permission.
Required permission

ACCOUNTING_GET_BUSINESS_CASE_TEMPLATE

Parameters 4
NameDescription
limit
query integer
Maximum number of templates to return. When omitted, the downstream service returns the full catalog.
example: 50
offset
query integer
Zero-based index of the first template to return. When omitted, the response starts at the first row.
example: 0
orderColumns
query array of string
Names of columns to order the result by, ascending. Repeat the query parameter for multi-column ordering (e.g. ?orderColumns=group&orderColumns=code).
example: code
Accept-Language
header string
IETF language tag used to resolve the localized display label of each template. Examples: de-CH, fr-CH, it-CH, en. Falls back to the German translation when no translation exists for the requested language.
example: de-CH
Responses 5
200 Business-case templates matching the supplied ordering and pagination. show body

application/json array of PublicApiBusinessCaseTemplate

Array of PublicApiBusinessCaseTemplate.

  • id integer (int64) format: int64 example: 101
    Internal id of the template in the Klara catalogue.
  • code string example: OFFICE_SUPPLIES
    Stable catalogue code of the template.
  • display string example: Bürobedarf
    Label of the template, already translated for the request's Accept-Language.
  • i18n object
    All translations of the label, keyed by IETF language tag.
    show fields

    Open map with values of type string.

  • keywordI18ns object
    All translations of the search keywords, keyed by IETF language tag.
    show fields

    Open map with values of type string.

  • group string example: Operating expenses
    Catalogue group the template belongs to.
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/business-case-templates/{businessCaseTemplateId}key / tokenRead a single Klara master accounting business-case template by id.
Returns one business-case template from the global Klara catalog — a manual-journal category usable when entering a booking (for example operating expenses, salary payments, asset purchases). The catalog is global Klara reference data, so this endpoint has no tenant or company path parameters; only the catalogue id selects the template. The Accept-Language header selects which translation of the human-readable display label is returned; if absent or unsupported the German translation is used as a fallback and the full per-language i18n / keywordI18ns maps are returned for client-side rendering. The endpoint is a pure read — idempotent, no side effects. Returns 404 when no template with the requested id exists in the catalog. Requires a bearer token whose principal carries the ACCOUNTING_GET_BUSINESS_CASE_TEMPLATE permission.
Required permission

ACCOUNTING_GET_BUSINESS_CASE_TEMPLATE

Parameters 2
NameDescription
businessCaseTemplateId required
path integer (int64)
Numeric primary-key id of the business-case template in the Klara master catalog. Obtain it from a prior call to GET /core/v1/accounting/business-case-templates.
format: int64 example: 101
Accept-Language
header string
IETF language tag used to resolve the localized display label of the template. Examples: de-CH, fr-CH, it-CH, en. Falls back to the German translation when no translation exists for the requested language.
example: de-CH
Responses 6
200 Business-case template matching the supplied id. show body

application/json PublicApiBusinessCaseTemplate

  • id integer (int64) format: int64 example: 101
    Internal id of the template in the Klara catalogue.
  • code string example: OFFICE_SUPPLIES
    Stable catalogue code of the template.
  • display string example: Bürobedarf
    Label of the template, already translated for the request's Accept-Language.
  • i18n object
    All translations of the label, keyed by IETF language tag.
    show fields

    Open map with values of type string.

  • keywordI18ns object
    All translations of the search keywords, keyed by IETF language tag.
    show fields

    Open map with values of type string.

  • group string example: Operating expenses
    Catalogue group the template belongs to.
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 No business-case template carries the requested id. no response body
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/business-caseskey / tokenHydrate a business case from a template id for the authenticated company.
Loads the fully hydrated business-case aggregate the booking form needs: the template id, the company-VAT and fiscal-year context resolved from the optional date filters, the pre-translated display label, and the recursive snippet / field tree. When dateForFilteringFiscalYear is supplied it drives the fiscal-year resolution; otherwise dateForFilteringCompanyVat is used; otherwise the downstream service resolves the fiscal year that covers today. Tenant and company are derived from the bearer-token session — they are never accepted from the URL. The endpoint is a pure read — idempotent, no side effects. The caller must hold the ACCOUNTING permission on the company in scope.
Required permission

ACCOUNTING

Parameters 4
NameDescription
businessCaseTemplateId required
query integer (int64)
Numeric id of the business-case template to hydrate. Obtain it from GET /core/v1/accounting/companies/current/business-case-templates.
format: int64 example: 101
dateForFilteringCompanyVat
query string (date)
ISO date (yyyy-MM-dd) used to resolve the company-VAT regime applicable to the business case. Used as the fallback for dateForFilteringFiscalYear when that is omitted.
format: date example: 2024-06-15
dateForFilteringFiscalYear
query string (date)
ISO date (yyyy-MM-dd) used to resolve the fiscal year that hydrates the business case. When omitted, falls back to dateForFilteringCompanyVat; when both are omitted the downstream service resolves the fiscal year that covers today.
format: date example: 2024-06-15
Accept-Language
header string
IETF language tag used to translate the snippet labels and field captions. Examples: de-CH, fr-CH, it-CH, en.
example: de-CH
Responses 7
200 Hydrated business-case aggregate for the requested template. show body

application/json PublicApiBusinessCase

  • businessCaseId integer (int64) format: int64 example: null
    Identifier of the business case instance when persisted; null on a freshly hydrated template.
  • businessCaseTemplateId integer (int64) format: int64 example: 101
    Identifier of the business-case template this aggregate was hydrated from.
  • documentId string example: null
    Identifier of the underlying document the business case is attached to; null when the booking is not yet linked to a document.
  • display string example: Bürobedarf
    Pre-translated display label of the business-case template for the request's Accept-Language.
  • bookingNumbers string example:
    Comma-separated list of booking numbers already generated for this business case; empty on a fresh template.
  • effectiveCompanyVatDate string (date) format: date example: 2024-06-15
    Date used to resolve the company-VAT regime applicable to this business case (ISO yyyy-MM-dd).
  • documentDate string (date) format: date example: 2024-06-15
    Document date associated with the business case (ISO yyyy-MM-dd).
  • effectiveFiscalYearDate string (date) format: date example: 2024-06-15
    Date used to resolve the fiscal year applicable to this business case (ISO yyyy-MM-dd).
  • fiscalYearHasCreatedAuto boolean example: False
    True when the downstream service had to auto-create the fiscal year covering the resolved date.
  • withOP boolean example: False
    True when this business case is tracked as an open item (OP). May be null when not applicable.
  • fields object
    Recursive snippet-and-field tree driving the booking form, keyed by snippet code. The shape of each entry follows the downstream BusinessCaseField model (see analysis report §8.2).
    show fields

    Open map with values of type object.

  • entriesDefinition array of object
    Per-field entries definitions used by the booking form to resolve enum-like fields. Each entry mirrors the downstream FieldEntriesDefinition model (see analysis report §8.2).
    show fields

    Array of object.

    Open map with values of type object.

400 One of dateForFilteringFiscalYear / dateForFilteringCompanyVat is not a valid ISO date (yyyy-MM-dd), or the supplied businessCaseTemplateId is not valid for the company's legal form or VAT regime. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 No business-case template matches the supplied businessCaseTemplateId in the caller's company scope. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/business-cases/v2key / tokenHydrate a business case from a template id, scoped to a single snippet.
Snippet-scoped variant of GET /core/v1/accounting/business-cases: hydrates only the template root plus the snippet identified by snippet-id, so the booking UI can stream the form one snippet at a time instead of loading the whole tree up-front. When dateForFilteringFiscalYear is supplied it drives the fiscal-year resolution; otherwise dateForFilteringCompanyVat is used; otherwise the downstream service resolves the fiscal year that covers today. When group-insurance-by-insurer is true (the default), social-insurance entries that share the same display + value pair are collapsed, keeping the entry with the smallest numeric id. Tenant and company are derived from the bearer-token session — they are never accepted from the URL. The endpoint is a pure read — idempotent, no side effects. The caller must hold the ACCOUNTING permission on the company in scope.
Required permission

ACCOUNTING

Parameters 7
NameDescription
businessCaseTemplateId required
query integer (int64)
Numeric id of the business-case template to hydrate. Obtain it from GET /core/v1/accounting/companies/current/business-case-templates.
format: int64 example: 101
dateForFilteringCompanyVat
query string (date)
ISO date (yyyy-MM-dd) used to resolve the company-VAT regime applicable to the business case. Used as the fallback for dateForFilteringFiscalYear when that is omitted.
format: date example: 2024-06-15
dateForFilteringFiscalYear
query string (date)
ISO date (yyyy-MM-dd) used to resolve the fiscal year that hydrates the business case. When omitted, falls back to dateForFilteringCompanyVat; when both are omitted the downstream service resolves the fiscal year that covers today.
format: date example: 2024-06-15
group-insurance-by-insurer
query boolean
When true, collapses social-insurance entries that share the same display + value pair, keeping the entry with the smallest numeric id. Defaults to true. Allowed values: true, false.
default: true example: True
snippet-id
query integer (int64)
Numeric id of the snippet currently activated by the user; v2 hydrates only this snippet plus the template root. When omitted, only the template root is hydrated.
format: int64 example: 42
snippet-value
query string
Currently ignored on the downstream side; reserved for a future optimisation that would load external entries only for the activated value (for example, payment dates of a single employee). Safe to omit.
example: EMP-1001
Accept-Language
header string
IETF language tag used to translate the snippet labels and field captions. Examples: de-CH, fr-CH, it-CH, en.
example: de-CH
Responses 7
200 Hydrated business-case aggregate for the requested template and snippet. show body

application/json PublicApiBusinessCase

  • businessCaseId integer (int64) format: int64 example: null
    Identifier of the business case instance when persisted; null on a freshly hydrated template.
  • businessCaseTemplateId integer (int64) format: int64 example: 101
    Identifier of the business-case template this aggregate was hydrated from.
  • documentId string example: null
    Identifier of the underlying document the business case is attached to; null when the booking is not yet linked to a document.
  • display string example: Bürobedarf
    Pre-translated display label of the business-case template for the request's Accept-Language.
  • bookingNumbers string example:
    Comma-separated list of booking numbers already generated for this business case; empty on a fresh template.
  • effectiveCompanyVatDate string (date) format: date example: 2024-06-15
    Date used to resolve the company-VAT regime applicable to this business case (ISO yyyy-MM-dd).
  • documentDate string (date) format: date example: 2024-06-15
    Document date associated with the business case (ISO yyyy-MM-dd).
  • effectiveFiscalYearDate string (date) format: date example: 2024-06-15
    Date used to resolve the fiscal year applicable to this business case (ISO yyyy-MM-dd).
  • fiscalYearHasCreatedAuto boolean example: False
    True when the downstream service had to auto-create the fiscal year covering the resolved date.
  • withOP boolean example: False
    True when this business case is tracked as an open item (OP). May be null when not applicable.
  • fields object
    Recursive snippet-and-field tree driving the booking form, keyed by snippet code. The shape of each entry follows the downstream BusinessCaseField model (see analysis report §8.2).
    show fields

    Open map with values of type object.

  • entriesDefinition array of object
    Per-field entries definitions used by the booking form to resolve enum-like fields. Each entry mirrors the downstream FieldEntriesDefinition model (see analysis report §8.2).
    show fields

    Array of object.

    Open map with values of type object.

400 One of dateForFilteringFiscalYear / dateForFilteringCompanyVat is not a valid ISO date (yyyy-MM-dd), or the supplied businessCaseTemplateId is not valid for the company's legal form or VAT regime. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 No business-case template matches the supplied businessCaseTemplateId in the caller's company scope. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/business-cases/{businessCaseId}key / tokenRead a persisted business-case instance by its id for the authenticated company.
Loads the fully hydrated business-case aggregate that was previously persisted for the authenticated company: the template id, the company-VAT and fiscal-year context that were in force when the case was booked, the pre-translated display label, the recursive snippet / field tree with the persisted scripted values overlaid, and the comma-separated list of booking numbers already generated for it. Tenant and company are derived from the bearer-token session — they are never accepted from the URL; the supplied businessCaseId is matched against the caller's company so that an id owned by another company surfaces as 404. The endpoint is a pure read — idempotent, no side effects. The caller must hold the ACCOUNTING permission on the company in scope.
Required permission

ACCOUNTING

Parameters 2
NameDescription
businessCaseId required
path integer (int64)
Numeric primary-key id of the persisted business-case instance to hydrate. Obtain it from a prior booking response (for example POST /core/v1/accounting/bookings) or from a journal listing.
format: int64 example: 5001
Accept-Language
header string
IETF language tag used to translate the snippet labels and field captions. Examples: de-CH, fr-CH, it-CH, en.
example: de-CH
Responses 7
200 Hydrated business-case aggregate for the requested id. show body

application/json PublicApiBusinessCase

  • businessCaseId integer (int64) format: int64 example: null
    Identifier of the business case instance when persisted; null on a freshly hydrated template.
  • businessCaseTemplateId integer (int64) format: int64 example: 101
    Identifier of the business-case template this aggregate was hydrated from.
  • documentId string example: null
    Identifier of the underlying document the business case is attached to; null when the booking is not yet linked to a document.
  • display string example: Bürobedarf
    Pre-translated display label of the business-case template for the request's Accept-Language.
  • bookingNumbers string example:
    Comma-separated list of booking numbers already generated for this business case; empty on a fresh template.
  • effectiveCompanyVatDate string (date) format: date example: 2024-06-15
    Date used to resolve the company-VAT regime applicable to this business case (ISO yyyy-MM-dd).
  • documentDate string (date) format: date example: 2024-06-15
    Document date associated with the business case (ISO yyyy-MM-dd).
  • effectiveFiscalYearDate string (date) format: date example: 2024-06-15
    Date used to resolve the fiscal year applicable to this business case (ISO yyyy-MM-dd).
  • fiscalYearHasCreatedAuto boolean example: False
    True when the downstream service had to auto-create the fiscal year covering the resolved date.
  • withOP boolean example: False
    True when this business case is tracked as an open item (OP). May be null when not applicable.
  • fields object
    Recursive snippet-and-field tree driving the booking form, keyed by snippet code. The shape of each entry follows the downstream BusinessCaseField model (see analysis report §8.2).
    show fields

    Open map with values of type object.

  • entriesDefinition array of object
    Per-field entries definitions used by the booking form to resolve enum-like fields. Each entry mirrors the downstream FieldEntriesDefinition model (see analysis report §8.2).
    show fields

    Array of object.

    Open map with values of type object.

400 The supplied businessCaseId is not a valid numeric id. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 No business case matches the supplied businessCaseId in the caller's company scope. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/companies/currentkey / tokenGet the accounting configuration of the authenticated company.
Returns the dunning waiting periods configured for the authenticated caller's company together with the canonical compensation-side company URI. Tenant and company are derived from the bearer token — there are no path or query parameters to override them. When the company has no accounting configuration row persisted yet, the downstream service synthesises a default record (id = null, waitingDunningTime = 5, dunningWaitingTimeLevelOne / Two / Three = 10) so the response shape stays the same. The endpoint is a pure read — idempotent, no side effects. The caller must hold the ACCOUNTING permission on the company in scope.
Required permission

ACCOUNTING

Responses 6
200 Accounting configuration of the caller's company. show body

application/json PublicApiAccountingCompany

  • id integer (int64) format: int64 example: 17
    Internal id of the accounting-configuration row. Null when no configuration has been persisted yet for the company.
  • companyUri string example: /luz_compensation/api/c60d31fa-f335-4957-872a-90b035632081/companies/1
    Canonical compensation-side URI of the company, of the form /luz_compensation/api/{tenant}/companies/{companyId}.
  • waitingDunningTime integer (int64) format: int64 example: 5
    Number of days to wait after the invoice due date before starting the dunning cycle. Defaults to 5 when no configuration exists yet.
  • dunningWaitingTimeLevelOne integer (int64) format: int64 example: 10
    Days to wait between the level-1 dunning notice and the level-2 escalation. Defaults to 10 when no configuration exists yet.
  • dunningWaitingTimeLevelTwo integer (int64) format: int64 example: 10
    Days to wait between the level-2 dunning notice and the level-3 escalation. Defaults to 10 when no configuration exists yet.
  • dunningWaitingTimeLevelThree integer (int64) format: int64 example: 10
    Days to wait between the level-3 dunning notice and the final escalation. Defaults to 10 when no configuration exists yet.
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 The company associated with the caller's session could not be resolved by the downstream accounting service. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/companies/current/business-case-templateskey / tokenList business-case templates available to the authenticated company, grouped by financial-year period.
Returns the manual-journal categories ("business-case templates") the caller's company is allowed to book against, grouped by the financial-year period in which they are valid. Each period carries its periodFrom / periodTo, the company's legalForm and active VAT regime, and the templates that pass the legal-form / VAT-regime filters for that period. Templates are sorted by code; the display field is pre-translated using the Accept-Language header and the full per-language map is also returned in i18n / keywordI18ns. Tenant and company are derived from the bearer token — there are no path or query parameters to override them. The endpoint is a pure read — idempotent, no side effects. The caller must hold the ACCOUNTING permission on the company in scope.
Required permission

ACCOUNTING

Parameters 1
NameDescription
Accept-Language
header string
IETF language tag used to translate the display field of each template. Examples: de-CH, fr-CH, it-CH, en.
example: de-CH
Responses 6
200 Business-case templates grouped by financial-year period. May be an empty array when the company has no open fiscal year yet. show body

application/json array of PublicApiBusinessCasePeriod

Array of PublicApiBusinessCasePeriod.

  • companyId integer (int64) format: int64 example: 1
    Internal id of the company this period belongs to.
  • periodFrom string (date) format: date example: 2024-01-01
    Inclusive start date of the financial year (ISO yyyy-MM-dd).
  • periodTo string (date) format: date example: 2024-12-31
    Inclusive end date of the financial year (ISO yyyy-MM-dd).
  • legalForm string example: EINZEL
    Legal form of the company during this period. Allowed values include EINZEL, GMBH, AG, KOLLEKTIV, KOMMANDIT, GENOSSENSCHAFT, VEREIN, STIFTUNG.
  • companyVat object
    VAT regime of a company within a fiscal period.
    show fields
    • id integer (int64) format: int64 example: 42
      Internal id of the company VAT row.
    • reportingVat string example: EFFECTIVE
      Reporting method used to declare VAT. Allowed values: EFFECTIVE, NET_TAX_RATE, FLAT_TAX_RATE.
    • billing string example: AGREED
      Billing method used to determine VAT liability. Allowed values: AGREED, RECEIVED.
    • code string example: EFFECTIVE_AGREED
      Composite VAT code combining reporting method and billing, or NON_VAT when the company is not VAT-liable.
    • hasVat boolean example: True
      True when the company is VAT-liable in this period.
    • validFrom string (date) format: date example: 2024-01-01
      Inclusive start date of the VAT regime (ISO yyyy-MM-dd).
    • validTo string (date) format: date example: 2024-12-31
      Inclusive end date of the VAT regime (ISO yyyy-MM-dd).
    • yearlySettlement boolean example: False
      True for yearly VAT settlement, false for quarterly/semi-annual.
  • status string example: OPEN
    Status of the fiscal year. Allowed values: OPEN, CLOSING, CLOSED.
  • businessCaseTemplates array of PublicApiBusinessCaseTemplate
    Business-case templates valid for the company's legal form and VAT regime within this period, sorted by code.
    show fields

    Array of PublicApiBusinessCaseTemplate.

    • id integer (int64) format: int64 example: 101
      Internal id of the template in the Klara catalogue.
    • code string example: OFFICE_SUPPLIES
      Stable catalogue code of the template.
    • display string example: Bürobedarf
      Label of the template, already translated for the request's Accept-Language.
    • i18n object
      All translations of the label, keyed by IETF language tag.
      show fields

      Open map with values of type string.

    • keywordI18ns object
      All translations of the search keywords, keyed by IETF language tag.
      show fields

      Open map with values of type string.

    • group string example: Operating expenses
      Catalogue group the template belongs to.
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 The company associated with the caller's session could not be resolved by the downstream accounting service. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/companies/current/financial-yearskey / tokenList active financial-year periods of the authenticated company.
Returns the company's currently active fiscal-year periods (status OPEN or CLOSING), one entry per legal-form / VAT-regime combination valid in the period. When every period shares the same legalForm and VAT regime the downstream service collapses them into a single aggregated period with periodFrom set to the earliest start date and periodTo set to the latest end date; otherwise the individual periods are returned. The businessCaseTemplates field is intentionally left empty on this endpoint — use GET /core/v1/accounting/companies/current/business-case-templates to retrieve the templates valid per period. Tenant and company are derived from the bearer token — there are no path or query parameters to override them. The endpoint is a pure read — idempotent, no side effects. The caller must hold the ACCOUNTING permission on the company in scope.
Required permission

ACCOUNTING

Parameters 1
NameDescription
Accept-Language
header string
IETF language tag forwarded to the downstream accounting service. Examples: de-CH, fr-CH, it-CH, en.
example: de-CH
Responses 6
200 Active financial-year periods of the caller's company. May be an empty array when the company has no open fiscal year yet. show body

application/json array of PublicApiBusinessCasePeriod

Array of PublicApiBusinessCasePeriod.

  • companyId integer (int64) format: int64 example: 1
    Internal id of the company this period belongs to.
  • periodFrom string (date) format: date example: 2024-01-01
    Inclusive start date of the financial year (ISO yyyy-MM-dd).
  • periodTo string (date) format: date example: 2024-12-31
    Inclusive end date of the financial year (ISO yyyy-MM-dd).
  • legalForm string example: EINZEL
    Legal form of the company during this period. Allowed values include EINZEL, GMBH, AG, KOLLEKTIV, KOMMANDIT, GENOSSENSCHAFT, VEREIN, STIFTUNG.
  • companyVat object
    VAT regime of a company within a fiscal period.
    show fields
    • id integer (int64) format: int64 example: 42
      Internal id of the company VAT row.
    • reportingVat string example: EFFECTIVE
      Reporting method used to declare VAT. Allowed values: EFFECTIVE, NET_TAX_RATE, FLAT_TAX_RATE.
    • billing string example: AGREED
      Billing method used to determine VAT liability. Allowed values: AGREED, RECEIVED.
    • code string example: EFFECTIVE_AGREED
      Composite VAT code combining reporting method and billing, or NON_VAT when the company is not VAT-liable.
    • hasVat boolean example: True
      True when the company is VAT-liable in this period.
    • validFrom string (date) format: date example: 2024-01-01
      Inclusive start date of the VAT regime (ISO yyyy-MM-dd).
    • validTo string (date) format: date example: 2024-12-31
      Inclusive end date of the VAT regime (ISO yyyy-MM-dd).
    • yearlySettlement boolean example: False
      True for yearly VAT settlement, false for quarterly/semi-annual.
  • status string example: OPEN
    Status of the fiscal year. Allowed values: OPEN, CLOSING, CLOSED.
  • businessCaseTemplates array of PublicApiBusinessCaseTemplate
    Business-case templates valid for the company's legal form and VAT regime within this period, sorted by code.
    show fields

    Array of PublicApiBusinessCaseTemplate.

    • id integer (int64) format: int64 example: 101
      Internal id of the template in the Klara catalogue.
    • code string example: OFFICE_SUPPLIES
      Stable catalogue code of the template.
    • display string example: Bürobedarf
      Label of the template, already translated for the request's Accept-Language.
    • i18n object
      All translations of the label, keyed by IETF language tag.
      show fields

      Open map with values of type string.

    • keywordI18ns object
      All translations of the search keywords, keyed by IETF language tag.
      show fields

      Open map with values of type string.

    • group string example: Operating expenses
      Catalogue group the template belongs to.
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 The company associated with the caller's session could not be resolved by the downstream accounting service. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/currencies/exchange-ratekey / tokenGet the CHF exchange rate for a currency on a given date.
Returns the Swiss National Bank reference rate that converts one unit of from-currency-code into CHF on exchange-date. When from-currency-code equals CHF (case-insensitive) the rate is always 1. The exchange-rate table is global SNB data — the same response is returned for every tenant, so there are no tenant or company path parameters. If no rate is stored for the requested day, the downstream service transparently fetches the SNB feed for that date and persists the result; if the feed has no entry either, the most recent rate strictly before exchange-date is returned instead. The endpoint is a pure read for the caller — idempotent. Requires a bearer token whose principal carries the ACCOUNTING permission.
Required permission

ACCOUNTING

Parameters 2
NameDescription
exchange-date required
query string (date)
Reference date for the exchange rate, expressed as an ISO-8601 calendar date (yyyy-MM-dd).
format: date example: 2024-09-30
from-currency-code required
query string
ISO-4217 alpha-3 currency code of the source amount. Case-insensitive; CHF short-circuits to a rate of 1.
example: EUR
Responses 5
200 Exchange rate as a JSON number; the value 1 when from-currency-code is CHF. show body

application/json number

400 exchange-date is not a valid ISO-8601 calendar date, or no rate could be resolved for the supplied from-currency-code. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/master-vatskey / tokenList the master VAT catalog used by Klara Accounting.
Returns the global master VAT catalog — the table of supported VAT rates with their validity ranges and translated labels. The downstream handler is a dispatcher driven by the query string: when code is non-blank only rows whose vatCode matches one of the semicolon-separated codes are returned (and when combined with current-period=true, only the ones valid today); otherwise when default-vat=true only the company-default rows are returned; otherwise the full catalog is returned, ordered by rate ascending, optionally paginated via offset / limit. Pagination is honoured only on the full-catalog branch — it is silently ignored when code or default-vat is set. The endpoint is a pure read and idempotent. Requires a bearer token whose principal carries the ACCOUNTING_GET_MASTER_VAT permission.
Required permission

ACCOUNTING_GET_MASTER_VAT

Parameters 6
NameDescription
code
query string
Semicolon-separated list of vatCodes to filter on. When set, switches the response to the by-code branch and ignores default-vat.
example: 1;3;4
current-period
query boolean
When combined with code, restricts the result to master VAT rows whose validity range covers today. Defaults to false.
default: false example: False
default-vat
query boolean
When true, restricts the result to the company-default master VAT rows. Defaults to false. Ignored when code is set.
default: false example: False
includeHiddenVatCase
query boolean
When true, the response also includes hidden VAT-case ids that are not directly mapped to a master VAT row. Defaults to false.
default: false example: False
limit
query integer
Maximum number of results to return. Only honoured on the full-catalog branch.
example: 50
offset
query integer
Zero-based index of the first result. Only honoured on the full-catalog branch (when neither code nor default-vat is set).
example: 0
Responses 4
200 Array of master VAT rows matching the filters. show body

application/json array of PublicApiMasterVat

Array of PublicApiMasterVat.

  • id integer (int64) format: int64 example: 12
    Internal id of the master VAT row.
  • vatCode string example: 1
    Short numeric VAT code as configured in the Klara accounting plan.
  • rate number example: 8.1
    VAT rate as a percentage value (8.10 means 8.10 %).
  • validFrom string (date) format: date example: 2024-01-01
    Inclusive start date of the validity range (ISO yyyy-MM-dd). May be null when open-ended.
  • validTo string (date) format: date example: 2030-12-31
    Inclusive end date of the validity range (ISO yyyy-MM-dd). May be null when open-ended.
  • defaultVat boolean example: True
    True when the row is one of the company-default VAT entries.
  • masterVatMulties array of PublicApiMasterVatMulti
    Localized labels keyed by language tag.
    show fields

    Array of PublicApiMasterVatMulti.

    • id integer (int64) format: int64 example: 101
      Internal id of the translation row.
    • language string example: de
      Language tag of the translation (ISO 639-1).
    • description string example: Normalsatz 8.1 %
      Human-readable VAT description in the matching language.
  • referenceVatCaseId string example: VC-7
    Optional reference to a hidden VAT case id not directly mapped to a master VAT.
  • createDate string (date-time) format: date-time example: 2024-01-01T08:00:00
    Timestamp when the row was created (ISO yyyy-MM-dd'T'HH:mm:ss).
  • updateDate string (date-time) format: date-time example: 2024-06-15T14:30:00
    Timestamp of the last update (ISO yyyy-MM-dd'T'HH:mm:ss).
401 No Authorization header found or invalid token no response body
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/master-vats/currentkey / tokenList the master VAT rows valid for today.
Returns the subset of the master VAT catalog whose validity range (validFrom / validTo) covers the server's current day. Useful for booking and invoicing UIs that need only the VAT rates that may legally be applied right now. The endpoint is a pure read and idempotent; the downstream handler caches the filtered list in-process. Requires a bearer token whose principal carries the ACCOUNTING_GET_MASTER_VAT permission.
Required permission

ACCOUNTING_GET_MASTER_VAT

Responses 4
200 Array of master VAT rows valid for the current day. show body

application/json array of PublicApiMasterVat

Array of PublicApiMasterVat.

  • id integer (int64) format: int64 example: 12
    Internal id of the master VAT row.
  • vatCode string example: 1
    Short numeric VAT code as configured in the Klara accounting plan.
  • rate number example: 8.1
    VAT rate as a percentage value (8.10 means 8.10 %).
  • validFrom string (date) format: date example: 2024-01-01
    Inclusive start date of the validity range (ISO yyyy-MM-dd). May be null when open-ended.
  • validTo string (date) format: date example: 2030-12-31
    Inclusive end date of the validity range (ISO yyyy-MM-dd). May be null when open-ended.
  • defaultVat boolean example: True
    True when the row is one of the company-default VAT entries.
  • masterVatMulties array of PublicApiMasterVatMulti
    Localized labels keyed by language tag.
    show fields

    Array of PublicApiMasterVatMulti.

    • id integer (int64) format: int64 example: 101
      Internal id of the translation row.
    • language string example: de
      Language tag of the translation (ISO 639-1).
    • description string example: Normalsatz 8.1 %
      Human-readable VAT description in the matching language.
  • referenceVatCaseId string example: VC-7
    Optional reference to a hidden VAT case id not directly mapped to a master VAT.
  • createDate string (date-time) format: date-time example: 2024-01-01T08:00:00
    Timestamp when the row was created (ISO yyyy-MM-dd'T'HH:mm:ss).
  • updateDate string (date-time) format: date-time example: 2024-06-15T14:30:00
    Timestamp of the last update (ISO yyyy-MM-dd'T'HH:mm:ss).
401 No Authorization header found or invalid token no response body
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/master-vats/{masterVatId}key / tokenResolve a master VAT catalog row by its numeric id.
Loads a single master VAT row from Klara's global master VAT catalog, identified by its numeric primary-key masterVatId. The catalog is global Klara reference data — the same row is returned for every tenant, so there are no tenant or company path parameters. The endpoint is a pure read and idempotent. Requires a bearer token whose principal carries the ACCOUNTING_GET_MASTER_VAT permission.
Required permission

ACCOUNTING_GET_MASTER_VAT

Parameters 1
NameDescription
masterVatId required
path integer (int64)
Numeric primary-key id of the master VAT row to resolve. Obtain it from GET /core/v1/accounting/master-vats or GET /core/v1/accounting/master-vats/current.
format: int64 example: 12
Responses 5
200 The master VAT row matching masterVatId, including its rate, VAT code and validity range. show body

application/json PublicApiMasterVat

  • id integer (int64) format: int64 example: 12
    Internal id of the master VAT row.
  • vatCode string example: 1
    Short numeric VAT code as configured in the Klara accounting plan.
  • rate number example: 8.1
    VAT rate as a percentage value (8.10 means 8.10 %).
  • validFrom string (date) format: date example: 2024-01-01
    Inclusive start date of the validity range (ISO yyyy-MM-dd). May be null when open-ended.
  • validTo string (date) format: date example: 2030-12-31
    Inclusive end date of the validity range (ISO yyyy-MM-dd). May be null when open-ended.
  • defaultVat boolean example: True
    True when the row is one of the company-default VAT entries.
  • masterVatMulties array of PublicApiMasterVatMulti
    Localized labels keyed by language tag.
    show fields

    Array of PublicApiMasterVatMulti.

    • id integer (int64) format: int64 example: 101
      Internal id of the translation row.
    • language string example: de
      Language tag of the translation (ISO 639-1).
    • description string example: Normalsatz 8.1 %
      Human-readable VAT description in the matching language.
  • referenceVatCaseId string example: VC-7
    Optional reference to a hidden VAT case id not directly mapped to a master VAT.
  • createDate string (date-time) format: date-time example: 2024-01-01T08:00:00
    Timestamp when the row was created (ISO yyyy-MM-dd'T'HH:mm:ss).
  • updateDate string (date-time) format: date-time example: 2024-06-15T14:30:00
    Timestamp of the last update (ISO yyyy-MM-dd'T'HH:mm:ss).
401 No Authorization header found or invalid token no response body
404 No master VAT row exists for the supplied masterVatId. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/vat-profilekey / tokenGet the authenticated company's VAT reporting profile.
Returns the company's VAT regime (effective vs net-tax-rate), billing method and flat net-tax rates, so an integration knows when the Saldosteuersatz flat-rate layer applies.
Parameters 1
NameDescription
date
query string
Date (ISO yyyy-MM-dd) to resolve the company VAT config for; defaults to today. Use the date you intend to book on — the company VAT must be valid for it.
example: 2025-05-08
Responses 4
200 VAT profile. show body

application/json PublicApiVatProfile

  • hasVat boolean example: True
    Whether the company is VAT-registered.
  • reportingMode string example: EFFECTIVE_CLEARING
    VAT regime. EFFECTIVE_CLEARING or REPORTING_USING_NET_TAX_RATES.
  • billing string example: BILLED
    Billing method. BILLED or COLLECTED.
  • sss1 number example: 1
    Flat net-tax rate 1 (percent), when reporting under net tax rates.
  • sss2 number example: 0.5
    Flat net-tax rate 2 (percent), when reporting under net tax rates.
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/vat-suggestionskey / tokenSuggest ready-to-use VAT case / rate / account bundles for a booking line.
Turns a plain-language context — a purchase vs a sale — into ranked, copy-paste-ready VAT bundles. Each bundle carries the verbatim vatCaseLink and vatRateLink to drop into a booking line's links, plus a suggested vatAccountCode. Supply amount to also receive a net/VAT preview. The bundle marked recommended is the server's best guess.

Rebuilding the Manual-booking VAT UI from this response (read this if you are generating a UI). This endpoint returns a flat array, but the Manual-booking screen renders it as three linked dropdowns plus two toggles and an auto-computed amount. Map each control as follows:<table border="1" cellpadding="4"><tr><th>GUI control</th><th>Driven by</th><th>How to build it</th></tr><tr><td>VAT on/off toggle</td><td>client-side state (not in this response)</td><td>OFF → the line has no VAT: don't call this endpoint, add no VAT links/fields. ON → call this endpoint and show the dropdowns below.</td></tr><tr><td>VAT case dropdown (e.g. "taxable supply")</td><td>distinct vatCaseCode (label it with label)</td><td>Group the array by vatCaseCode; one entry per distinct case.</td></tr><tr><td>VAT rate dropdown (e.g. "8.1%")</td><td>vatRateDisplay</td><td>Cascades from the chosen case: the rows sharing the selected vatCaseCode are the rate options.</td></tr><tr><td>VAT account dropdown (e.g. "1170 | Input tax VAT")</td><td>vatAccountCodes</td><td>List all vatAccountCodes; preselect vatAccountCode.</td></tr><tr><td>including / excluding toggle</td><td>the amountKind query param</td><td>including = GROSS_INCLUSIVE; excluding = NET_EXCLUSIVE. Flipping it means re-calling this endpoint to refresh the preview.</td></tr><tr><td>Debit / Credit amount preview</td><td>previewNet / previewVat</td><td>Null until you pass amount. Re-call with the new amount/amountKind to refresh.</td></tr></table>End-to-end recipe (call → render → book):
  1. User turns the VAT toggle ON. Call this endpoint with direction (PURCHASE/SALE), the line's accountCode, the user's amount, the amountKind from the including/excluding toggle, and the date you will book on.
  2. Render the dropdowns per the table above; preselect the row where recommended = true.
  3. When the user picks a row, send it to POST /core/v1/bookings?autoCalculateVat=true: on the VAT-bearing line set links = "<vatCaseLink>,<vatRateLink>" (both verbatim), vatAccountCode = <vatAccountCode>, your amount, and isExcludeVatAmount matching the amountKind you queried — then omit the VAT counterpart line; the server generates it (matching previewNet/previewVat). Pass the same date you will book on.

    Coverage: the response mirrors the booking GUI's two dropdowns. The VAT-case list is direction-agnostic (every configured case is offered regardless of direction), and the rate list includes every configured version of each rate code the case references — current and historical — so a line dated before a rate change still finds its rate.
Parameters 7
NameDescription
accountCode required
query integer (int32)
Main account being booked against (e.g. 1020); drives VAT-account resolution. Required.
format: int32 example: 4000
direction required
query string
PURCHASE (you are buying) or SALE (you are selling). Required. It does not restrict which VAT cases are returned (the full case list is always offered); it only selects the fallback VAT account — purchases vs sales — and the recommendation wording.
Allowed values: PURCHASE, SALE
example: PURCHASE
amount
query number
Amount to preview the net/VAT split for (optional).
example: 1000
amountKind
query string
GROSS_INCLUSIVE (default) or NET_EXCLUSIVE.
default: GROSS_INCLUSIVE example: GROSS_INCLUSIVE
date
query string
Date (ISO yyyy-MM-dd) to resolve the company VAT config for; defaults to today.
example: 2025-05-08
vatCase
query string
VAT case code to restrict suggestions to a single case; returns all its rate/account bundles (optional). Any valid case code is accepted regardless of direction — e.g. a sales case such as TAXABLE_SUPPLY can be requested with direction=PURCHASE.
Allowed values: TAXABLE_SUPPLY, SUPPLY_WITH_OPTION_ART_22, TAX_EXEMPT_SUPPLY, EXPORT, SUPPLY_ABROAD, EXCLUDED_SUPPLY, DECREASE_IN_PROFITS, INTERNAL_CONSUMPTION, SUBVENTION, CONTRIBUTIONS_DIVIDEND_DAMAGE_COMPENSION, DOMESTIC_PURCHASE, IMPORT_WITH_CUSTOMS, IMPORT_WITH_REVERSE_CHARGE, PURCHASE_ABROAD, TRANSFER_SUPPLY, MISCELLANEOUS, DE_TAXATION, MIXED_USE, REDUCTION, TAX_CREDIT_1050, TAX_CREDIT_1055_1056
example: DOMESTIC_PURCHASE
Accept-Language
header string
Preferred language for the bundle labels.
example: de-CH
Responses 5
200 Ranked VAT suggestions. show body

application/json array of PublicApiVatSuggestion

Array of PublicApiVatSuggestion.

  • label string example: Domestic purchase — 8.1%
    Human-meaningful label. Use it as the option text in the VAT-rate dropdown.
  • recommended boolean example: True
    True on the server's recommended default bundle — preselect this row in the dropdowns.
  • reason string example: Default VAT rate for DOMESTIC_PURCHASE.
    Why this bundle is suggested.
  • vatCaseCode string example: DOMESTIC_PURCHASE
    VAT case code. Group rows by this value to build the VAT-case dropdown.
  • vatCaseLink string example: vat_case:/luz_accounting/api/vat-cases/1
    Verbatim link to copy into a booking line's links (comma-joined with vatRateLink).
  • vatRateDisplay string example: 8.1%
    Display string of the VAT rate — the VAT-rate dropdown option within the selected VAT case.
  • vatRateLink string example: vat_rate:/luz_accounting/api/master-vats/59
    Verbatim link to copy into a booking line's links (comma-joined with vatCaseLink).
  • vatAccountCode integer (int32) format: int32 example: 1170
    Suggested VAT account for the generated VAT line — preselect this in the VAT-account dropdown; the first of vatAccountCodes (confirm against your chart of accounts).
  • vatAccountCodes array of integer (int32)
    All VAT accounts the company's chart maps to this account + VAT case; the options for the GUI's VAT-account dropdown.
  • previewNet number example: 925.93
    Net amount preview — the Debit/Credit preview shown in the GUI. Null until an amount is supplied; refreshes when amount/amountKind change.
  • previewVat number example: 74.07
    VAT amount preview — the VAT portion shown in the GUI. Null until an amount is supplied; refreshes when amount/amountKind change.
400 Data invalid show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/vat-typeskey / tokenList Klara master VAT-type catalogue rows.
Returns every VAT-type row maintained by Klara — the canonical VAT codes that can participate in a booking together with their posting formulas. The data is global — the same catalogue is returned for every tenant, so there are no tenant or company path parameters. The Accept-Language header selects which translation is used for the description and vatTypeShortName fields; if absent or unsupported, German is used as the fallback. The endpoint is a pure read — idempotent, no side effects. Any authenticated bearer token is accepted; the downstream service declares no role or permission requirement on this endpoint.
Required permission

none The specification states that no role or permission is required for this endpoint.

Parameters 1
NameDescription
Accept-Language
header string
IETF language tag used to resolve the localized description and vatTypeShortName fields. Examples: de-CH, fr-CH, it-CH, en. When the header is missing or the language is unknown, the downstream service falls back to German.
example: de-CH
Responses 4
200 Master VAT-type rows. Empty array when the catalogue has not been seeded yet. show body

application/json array of PublicApiVatType

Array of PublicApiVatType.

  • vatTypeCode string example: M81
    Klara VAT-type code that identifies the row.
  • companyType string example: LIMITED_LIABILITY
    Company-type bucket the VAT type applies to.
  • description string example: Vorsteuer Material- und Dienstleistungsaufwand
    Localized description, resolved against the request Accept-Language header (German fallback).
  • vatTypeShortName string example: VSt MA
    Localized short name, resolved against the request Accept-Language header (German fallback).
  • i18n object
    Raw description translations keyed by lowercase IETF language tag. Useful when a client renders its own language picker; otherwise prefer the resolved description field.
    show fields

    Open map with values of type string.

  • i18nShortName object
    Raw short-name translations keyed by lowercase IETF language tag.
    show fields

    Open map with values of type string.

  • vatTypeFormula array of PublicApiVatTypeFormula
    Posting formulas attached to this VAT type, one per associated VAT case.
    show fields

    Array of PublicApiVatTypeFormula.

    • vatCaseCode string example: VAT_RECEIVABLE
      Linked VAT-case code this formula belongs to.
    • vatTypeCode string example: M81
      VAT-type code this formula belongs to.
    • companyType string example: LIMITED_LIABILITY
      Company-type bucket the formula applies to.
    • account string example: 2200
      Account number on which the VAT entry is booked.
    • contraAccount string example: 1170
      Contra-account number for the VAT entry.
    • linkedBookingAccount string example: 2201
      Linked auxiliary account, when applicable.
    • specialRatesType string example: STANDARD
      Special-rates flag (enum name from the upstream model). Surfaced as a string so future internal enum additions stay backwards compatible.
    • value string example: NORMAL
      Formula value flag (enum name from the upstream model). Surfaced as a string for forward compatibility.
401 No Authorization header found or invalid token no response body
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/accounting/vat-types/{vatTypeId}key / tokenResolve a Klara master VAT-type row by its numeric id.
Loads a single VAT-type row from Klara's global master VAT-type catalogue, identified by its numeric primary-key vatTypeId. The data is global — the same catalogue is shared across every tenant, so there are no tenant or company path parameters. The Accept-Language header selects which translation is used for the description and vatTypeShortName fields; if absent or unsupported, German is used as the fallback. The endpoint is a pure read — idempotent, no side effects. Any authenticated bearer token is accepted; the downstream service declares no role or permission requirement on this endpoint.
Required permission

none The specification states that no role or permission is required for this endpoint.

Parameters 2
NameDescription
vatTypeId required
path integer (int64)
Numeric primary-key id of the master VAT-type row to resolve. Obtain it from GET /core/v1/accounting/vat-types.
format: int64 example: 1
Accept-Language
header string
IETF language tag used to resolve the localized description and vatTypeShortName fields. Examples: de-CH, fr-CH, it-CH, en. When the header is missing or the language is unknown, the downstream service falls back to German.
example: de-CH
Responses 5
200 The master VAT-type row matching vatTypeId, including its localized description, short name and posting formulas. show body

application/json PublicApiVatType

  • vatTypeCode string example: M81
    Klara VAT-type code that identifies the row.
  • companyType string example: LIMITED_LIABILITY
    Company-type bucket the VAT type applies to.
  • description string example: Vorsteuer Material- und Dienstleistungsaufwand
    Localized description, resolved against the request Accept-Language header (German fallback).
  • vatTypeShortName string example: VSt MA
    Localized short name, resolved against the request Accept-Language header (German fallback).
  • i18n object
    Raw description translations keyed by lowercase IETF language tag. Useful when a client renders its own language picker; otherwise prefer the resolved description field.
    show fields

    Open map with values of type string.

  • i18nShortName object
    Raw short-name translations keyed by lowercase IETF language tag.
    show fields

    Open map with values of type string.

  • vatTypeFormula array of PublicApiVatTypeFormula
    Posting formulas attached to this VAT type, one per associated VAT case.
    show fields

    Array of PublicApiVatTypeFormula.

    • vatCaseCode string example: VAT_RECEIVABLE
      Linked VAT-case code this formula belongs to.
    • vatTypeCode string example: M81
      VAT-type code this formula belongs to.
    • companyType string example: LIMITED_LIABILITY
      Company-type bucket the formula applies to.
    • account string example: 2200
      Account number on which the VAT entry is booked.
    • contraAccount string example: 1170
      Contra-account number for the VAT entry.
    • linkedBookingAccount string example: 2201
      Linked auxiliary account, when applicable.
    • specialRatesType string example: STANDARD
      Special-rates flag (enum name from the upstream model). Surfaced as a string so future internal enum additions stay backwards compatible.
    • value string example: NORMAL
      Formula value flag (enum name from the upstream model). Surfaced as a string for forward compatibility.
401 No Authorization header found or invalid token no response body
404 No master VAT-type row exists for the supplied vatTypeId. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/bank-reconciliation/open-positionskey / tokenList the bank-reconciliation open positions of the authenticated company.
Returns the list of open booking-detail positions (AR / AP invoices, payments, prepayments, credit notes, general-ledger entries) of the caller's company that match the supplied filters, enriched with partner-name display, business-case message id, computed open amount and a stable booking-detail URI. Used by the bank-reconciliation UI to populate the open-position picker for a selected bank or credit-card transaction. The action parameter selects the multi-condition combinator: search (default) is OR-of-conditions, filter is AND-of-conditions. Tenant and company are derived from the bearer-token session — they are never accepted from the URL. The endpoint is a pure read — idempotent, no side effects. The caller must hold the ACCOUNTING_GET_OPEN_POSITION permission on the company in scope.
Required permission

ACCOUNTING_GET_OPEN_POSITION

Parameters 12
NameDescription
action
query string
Multi-condition combinator. search (default) = OR-of-conditions; filter = AND-of-conditions.
Allowed values: search, filter
default: search example: filter
booking-type-codes
query string
Comma-separated list of booking-type codes to restrict to. Allowed values: GENERAL_LEDGER, AP_INVOICE, AP_PAYMENT, AR_INVOICE, AR_PAYMENT, AP_PREPAYMENT, AP_PREPAYUSE, AR_PREPAYMENT, AR_PREPAYUSE, AR_CREDITNOTE, AR_CREDITUSE, AP_CREDITNOTE, AP_CREDITUSE, AMORTIZATION, SELLOFF_AMORTIZATION, DELIMIT.
example: AR_PREPAYMENT,AR_CREDITNOTE
crdr-type
query string
Restrict to credit (CR) or debit (DR) postings.
Allowed values: CR, DR
example: CR
credit-card-not-reconciled
query boolean
When true, restricts to credit-card transactions still pending reconciliation.
example: True
general-search
query string
Free-text search across description, partner name, document id and reference fields. Combined with the other filters using the mode selected by action.
maxLength: 256 example: Migros
invoice-date
query string (date)
Exact-match invoice (document) date filter (ISO date yyyy-MM-dd).
format: date example: 2026-04-15
partner
query string
Klara partner URI to filter by. Format: /api/luz_person/api/{tenantId}/companies/{companyId}/partners/{partnerId}. Construct from the partner id returned by the public partner endpoints.
example: /api/luz_person/api/c60d31fa-f335-4957-872a-90b035632081/companies/1/partners/123
payment-date
query string (date)
Exact-match payment date filter (ISO date yyyy-MM-dd).
format: date example: 2026-05-28
payment-date-from
query string (date)
Inclusive lower bound of the payment-date range filter (ISO date yyyy-MM-dd).
format: date example: 2026-01-01
payment-date-to
query string (date)
Inclusive upper bound of the payment-date range filter (ISO date yyyy-MM-dd).
format: date example: 2026-06-30
position-status
query string
Comma-separated list of open-position lifecycle statuses to restrict to. Allowed values: OPEN, PARTLY_PAID, PAID, PARTLY_CLEARED, CLEARED.
example: OPEN,PARTLY_CLEARED
tags
query string
Comma-separated list of tag names to filter by (free-form).
maxLength: 256 example: vendor-x,q2
Responses 6
200 List of open positions matching the filters. Empty array when nothing matches. show body

application/json array of PublicApiSuitableOpenPosition

Array of PublicApiSuitableOpenPosition.

  • id integer (int64) format: int64 example: 98765
    Booking-detail row id (database primary key).
  • bookingHeaderId integer (int64) format: int64 example: 4321
    Id of the booking header this detail belongs to.
  • bookingHeaderComment string example: Invoice 2026-0123 from Migros AG
    Free-text comment of the booking header.
  • businessCaseId integer (int64) format: int64 example: 12345
    Id of the parent business case.
  • accountCode string example: 1100
    Numeric account code on which the booking is posted.
  • accountLinkDisplay string example: Forderungen aus L+L
    Localized account label.
  • crdrType object example: DR
    Credit / debit indicator.
    Allowed values: CR, DR
  • description string example: Rechnung Nr. 2026-0123
    Free-text description of the booking line.
  • bookingTypeCode object example: AR_INVOICE
    Stable booking-type code of the underlying business case.
    Allowed values: GENERAL_LEDGER, AP_INVOICE, AP_PAYMENT, AR_INVOICE, AR_PAYMENT, AP_PREPAYMENT, AP_PREPAYUSE, AR_PREPAYMENT, AR_PREPAYUSE, AR_CREDITNOTE, AR_CREDITUSE, AP_CREDITNOTE, AP_CREDITUSE, AMORTIZATION, SELLOFF_AMORTIZATION, DELIMIT
  • openPositionStatus object example: OPEN
    Open-position lifecycle status.
    Allowed values: OPEN, PARTLY_PAID, PAID, PARTLY_CLEARED, CLEARED
  • amount number example: 1250
    Gross posted amount of the booking line.
  • partialPaymentAmount number example: 0
    Sum of payments / clearings already applied to this position.
  • openAmount number example: 1250
    Computed remaining amount still to be cleared (amount - partialPaymentAmount).
  • vatAmount number example: 94.05
    VAT amount included in the gross posting.
  • vatRate number example: 0.081
    VAT rate applied to the line as a decimal (e.g. 0.077).
  • vatRateDisplay string example: 8.1 %
    Localized VAT-rate display string.
  • vatBookingDetailLink string
    Self-link of the companion VAT booking-detail line, when present.
  • vatBookingDetail boolean example: False
    Whether this row is itself a derived VAT booking-detail line.
  • foreignCurrencyAmount number example: 1250
    Posted amount in the document's foreign currency, when applicable.
  • foreignCurrencyUnit string example: EUR
    ISO-4217 currency code of foreignCurrencyAmount.
  • tags string example: test manual
    Free-form tag string attached to the booking line.
  • documentDate string (date) format: date example: 2026-04-15
    Document (invoice) date of the underlying business case.
  • bookingDate string (date) format: date example: 2026-04-15
    Date the booking was journaled.
  • paidDate string (date) format: date example: 2026-05-10
    Date the position was last (partially) paid, if any.
  • dueDate string (date) format: date example: 2026-05-15
    Due date for payment.
  • paymentDate string (date) format: date example: 2026-05-12
    Effective payment date of the booking line.
  • servicePeriodFrom string (date) format: date example: 2026-04-01
    Inclusive lower bound of the service period this booking covers.
  • servicePeriodTo string (date) format: date example: 2026-04-30
    Inclusive upper bound of the service period this booking covers.
  • createDate string (date-time) format: date-time example: 2026-04-15T08:30:00
    Timestamp at which the booking detail was created.
  • updateDate string (date-time) format: date-time example: 2026-05-12T14:15:00
    Timestamp at which the booking detail was last updated.
  • documentId array of string
    List of document ids attached to the booking line.
  • partnerName string example: Migros AG
    Resolved partner display name for the position.
  • bookingDetailUri string example: /api/luz_accounting/api/{tenantId}/companies/{companyId}/booking-headers/4321/booking-details/98765
    Stable URI of the booking-detail row, for cross-service linking.
  • orderManagementInvoiceLink string
    Self-link of the linked order-management invoice, when applicable.
  • orderManagementInvoiceNumber string example: INV-2026-0123
    Resolved order-management invoice number for display.
  • msgId string example: MSG-7788
    Business-case message id, used by the eletter / inbox subsystems.
  • creditorReference string
    Creditor reference (Swiss QR-IBAN reference number) of the position.
  • isrReference string
    ISR reference of the position, when applicable.
  • isrMember string
    ISR member number, when applicable.
  • partnerIban string
    IBAN of the partner / counterparty.
  • endToEndId string
    End-to-end identifier carried on the bank transaction.
400 One of the date filters is not a valid ISO date (yyyy-MM-dd), or one of the enum filters (position-status, booking-type-codes, crdr-type) carries a value that is not in the documented value set, or a free-text filter exceeds 256 characters. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
POST/core/v1/bookingskey / tokenCreate a new manual booking for the authenticated company.
Records a manual journal entry against the authenticated caller's company and returns the persisted booking with its server-assigned identifiers. The booking must contain at least two debit/credit lines whose totals balance — the downstream service rejects unbalanced postings. By default the bookingDate must fall inside an open fiscal year; set confirmDontMindClosingFiscalYear to true to accept a booking that targets a closing fiscal year. Set ignore-unsubscripted-dates to true to bypass the subscription-period guard that normally rejects bookings outside the active Klara Accounting subscription window. Tenant and company are derived from the bearer token — the request body's id and companyId are ignored. The caller must hold the ACCOUNTING permission on the targeted company.
Required permission

ACCOUNTING

Parameters 4
NameDescription
autoCalculateVat
query boolean
When true, the server recalculates VAT like the Manual booking GUI: each VAT-bearing line sends a single gross/net amount + a vat_rate link + vatAccountCode + isExcludeVatAmount and omits its VAT counterpart line; the server derives the net/VAT split and generates the VAT line so the entry balances. When false (default), the caller must pre-split and pre-compute every line (current behaviour). Obtain valid VAT values from GET /core/latest/vat-cases and GET /core/v1/accounting/master-vats.
default: false example: False
confirmDontMindClosingFiscalYear
query boolean
When true, accept the booking even if its bookingDate falls in a closing fiscal year. Defaults to false.
default: false example: False
ignore-unsubscripted-dates
query boolean
When true, accept the booking even if its date falls outside the active Klara Accounting subscription period. Defaults to false.
default: false example: False
Accept-Language
header string
Preferred language for any localized error messages produced downstream. Examples: de-CH, fr-CH, it-CH, en. Defaults to the tenant's configured language when omitted.
example: de-CH
Request body required
The booking to create, including its at-least-two balanced debit/credit lines.

Prerequisite APIs — call these first to obtain valid values:
  • GET /core/v1/accounting/accounts → provides valid accountCode values (e.g. 1020, 1100, 2000, 3200). Only use this endpoint when you want to implement a seperate combobox with a flat master account list without sub-account context.
  • GET /core/v1/accounting/accounts/account-displaying → provide full details about all valid, selectable accounts (combine name, combine code, master account, sub-account details when available). PREFERRED to use this endpoint as the booking line for some account code MUST include sub-account links if the sub-account exists.
  • POST /core/latest/companies/{company-id}/documents → upload supporting documents (invoices, receipts, bank statements) and collect the returned documentId values to populate documentIds. This step should be done BEFORE invoking the booking creation. Important: when calling this endpoint for booking creation, always use category = LIABILITY_UPLOAD — no other category is permitted in this context (the documents are automatically moved to LIABILITIES when the booking is created successfully). The GUI for booking creation must always provide a document-upload step using the LIABILITY_UPLOAD category.
  • GET /core/v1/accounting/booking-types → provides valid bookingTypeCode values (e.g. AR_PAYMENT, AP_INVOICE, GENERAL_LEDGER)
  • GET /core/latest/vat-cases → provides VAT case IDs for the vat_case link key
  • GET /core/v1/accounting/master-vats → provides master VAT rate IDs for the vat_rate link key
  • GET /core/v1/accounting/vat-suggestions?direction=PURCHASE|SALE&amount=…&date=… → RECOMMENDED for VAT. Returns ready-to-use bundles; from the recommended row copy vatCaseLink and vatRateLink straight into the line's links (comma-joined) and vatAccountCode onto the line. Use with autoCalculateVat=true (see VAT auto-calculation below).
  • GET /core/v1/accounting/vat-profile?date=… → the company VAT regime (effective vs net-tax-rate). Informational: it explains how the server will split the amount; you do not copy it into the booking.
Top-level fields:
  • id (long) — Server-assigned. Set to 0 for new bookings.
  • companyId (long) — Server-derived from token. Set to 0.
  • bookingDate (string, yyyy-MM-ddT00:00:00Z, required) — Must fall in an open fiscal year.
  • documentIds (array of string) — IDs of attached documents (gather from POST /core/latest/companies/{company-id}/documents with category = LIABILITY_UPLOAD). The documents are automatically moved to LIABILITIES on success booking creation. A GUI implementing booking creation must always provide a document-upload step — omitting it is only acceptable for purely internal adjustments where no document exists, in which case documentIds may be left empty ([]).
  • internalComment (string) — Internal note visible only to accounting users.
  • bookingStatus (string) — Allowed: DRAFT, BOOKED, CANCELLED.
  • bookingDetails (array, required) — At least 2 balanced debit/credit lines (see below).
  • expand (boolean) — UI hint. Use false.
  • viewDocument (boolean) — UI hint. Use false.
bookingDetails[] fields:
  • id (long) — Server-assigned. Set to 0.
  • seq (int) — Line order starting at 0.
  • accountCode (int, required) — From GET /core/v1/accounting/accounts or GET /core/v1/accounting/accounts/account-displaying (preferred; includes sub-account context when it exists).
  • crdrType (string, required) — DR (debit) or CR (credit).
  • description (string) — Free-text line description.
  • amount (decimal, required) — Always positive. Total DR must equal total CR.
  • tags (string, required) — Comma-separated list of string tags. Each tag should represent a topic that the booking line should be associated with, e.g. Operating Expenses. Tags are free-form and have no semantic meaning to Klara; they are simply stored and returned as-is. Provide at least one tag per line.
  • links (string) — Comma-separated structured links. Two uses: (a) sub-account entities for the line's account code (from GET /core/v1/accounting/accounts/account-displaying); and (b) VAT links vat_case:… + vat_rate:… (from GET /core/v1/accounting/vat-suggestions) when this line carries VAT. Can be empty when neither applies.
  • bookingTypeCode (string) — From GET /core/v1/accounting/booking-types.
  • vatAccountCode (int) — Only with autoCalculateVat=true. The account the generated VAT line posts to (e.g. 1170); from the vatAccountCode of a vat-suggestions row.
  • isExcludeVatAmount (boolean) — Only with autoCalculateVat=true. false = amount includes VAT (gross); true = amount excludes VAT (net base).
  • isrReference (string) — ISR/QR-bill reference. Empty if not applicable.
  • isrMember (string) — ISR participant number. Empty if not applicable.
  • partnerIban (string) — Counterpart IBAN for payments. Empty if not applicable.
  • vatBookingDetail (boolean) — Set to false for manual lines.
VAT auto-calculation (autoCalculateVat=true) — book like the Manual booking GUI without doing VAT math:
  1. Call GET /core/v1/accounting/vat-suggestions?direction=PURCHASE|SALE&amount=<gross>&date=<bookingDate> and take the recommended row.
  2. On the VAT-bearing line set: links = "<vatCaseLink>,<vatRateLink>" (both values verbatim from that row), vatAccountCode = <row.vatAccountCode>, amount = <your gross or net>, and isExcludeVatAmount matching the amountKind you queried (false = gross).
  3. Do NOT add the VAT counterpart line yourself — the server derives the net/VAT split and generates it (matching the row's previewNet/previewVat). Provide only your account line(s) + the balancing line.
The split depends on the company VAT regime from vat-profile (effective → net + VAT line; net-tax-rate → flat-rate split; reverse-charge → an extra reverse VAT line). When autoCalculateVat is omitted/false you must instead pre-split and pre-compute every line yourself (see the "Invoice received/sent" examples).

Rules: Minimum 2 lines; total DR = total CR (after server VAT expansion when autoCalculateVat=true); amounts always positive; bookingDate in open fiscal year.

application/json PublicApiBookingHeader

  • id integer (int64) format: int64 example: 12345
    Internal id of the booking. Assigned by the server on creation; omit when sending a new booking.
  • companyId integer (int64) format: int64 example: 1
    Internal id of the company this booking belongs to. Filled by the server from the caller's session; ignored on input.
  • documentDate string (date-time) required format: date-time example: 2024-06-15T00:00:00Z
    Date printed on the underlying document, e.g. supplier invoice date (yyyy-MM-ddT00:00:00Z).
  • bookingDate string (date-time) required format: date-time example: 2024-06-15T00:00:00Z
    Effective accounting date of the booking; must fall inside an open fiscal year unless confirmDontMindClosingFiscalYear is set (yyyy-MM-ddT00:00:00Z).
  • documentIds array of string
    Ids of supporting documents (uploaded files / e-mails) attached to this booking.
  • businessCase string example: Office supplies
    Free-text business case label shown on the journal.
  • snippets array of string
    Snippet identifiers applied to this booking, copied from the booking template.
  • bookingStatus string example: BOOKED
    Status of the booking. Allowed values: DRAFT, BOOKED, CANCELLED.
  • internalComment string
    Internal comment, visible only to accounting users.
  • businessCaseId string
    Reference to the business-case document (workflow id) that produced this booking, when applicable.
  • relatedBookingHeaderLinks array of string
    URIs of bookings that are related to this one (e.g. payment ↔ invoice, original ↔ delimitation).
  • bookingDetails array of PublicApiBookingDetail required minItems: 2
    Debit and credit lines of the booking. Must contain at least two lines whose debit and credit totals balance.
    show fields

    Array of PublicApiBookingDetail.

    • id integer (int64) format: int64 example: 1001
      Internal id of the booking detail. Assigned by the server on creation; omit when sending a new booking.
    • accountCode integer (int32) required format: int32 min: 1 example: 1020
      Ledger account number the amount is posted to (Swiss SME chart of accounts).
    • crdrType string required example: DR
      Whether this line is a credit or a debit. Allowed values: CR, DR.
    • description string required pattern: \S example: Office supplies — invoice 2024-019
      Free-text description shown on the journal report.
    • amount number required example: 150
      Absolute posting amount in the company main currency. Always positive; sign is carried by crdrType.
    • partialPaymentAmount number example: 0
      Amount already paid against this line — only used for open-position bookings (invoices, credit notes).
    • tags string required example: project-alpha,q2
      Comma-separated list of string tags. Each tag is free-form and should represent a topic that the booking line should be associated with. Provide at least one tag per line.
    • links string example: bank_account:/luzfin_finance/api/388c822c-7860-41ae-94ac-330684bb63e0/companies/1/bank-accounts/85,vat_case:/luz_accounting/api/vat-cases/1
      Comma-separated list of structured links of entities that are considered the sub-accounts associated with an account code when making a booking line.This string can be empty when no sub-account is required for the current account code of the booking line.Each link has the format key:uri-path. Important: the exact URI values — including the tenant UUID and company ID segments — are returned verbatim by GET /core/v1/accounting/accounts/account-displaying in the account's specificationItem.link field; copy them as-is, do not construct them manually.

      Supported link type keys:
      Bank / cash sub-accounts (secondary dropdown in GUI for accounts 1000, 1020, 1030, 1040, and similar):
      • bank_account — company bank account; URI from /luzfin_finance/api/{tenant}/companies/{cid}/bank-accounts/{id}
      • cash — cash register; URI from /luz_accounting/api/{tenant}/companies/{cid}/cash/{id}
      • transfer_account — transfer account; URI from /luz_accounting/api/{tenant}/companies/{cid}/transfer/{id}
      • interest_bearing_current_account — interest-bearing current account; URI from /luz_accounting/api/{tenant}/companies/{cid}/interest-bearing-current/{id}
      • non_interest_bearing_current_account — non-interest-bearing current account; URI from /luz_accounting/api/{tenant}/companies/{cid}/non-interest-bearing/{id}
      Counterpart links (customer / supplier / employee sub-ledger):
      • customer — accounts-receivable customer; URI from /luzfin_finance/api/{tenant}/companies/{cid}/customers/{id}
      • supplier — accounts-payable supplier; URI from /luzfin_finance/api/{tenant}/companies/{cid}/customers/{id}
      • employee — employee (payroll/HR); URI from /luz_compensation/api/{tenant}/companies/{cid}/employees/{id}
      Tax / VAT links:
      • vat_case — VAT case; URI from /luz_accounting/api/vat-cases/{id} (obtain from GET /core/latest/vat-cases)
      • vat_rate — master VAT rate; URI from /luz_accounting/api/master-vats/{id} (obtain from GET /core/v1/accounting/master-vats)
      • social_insurance — social insurance contract; URI from /luz_compensation/api/{tenant}/companies/{cid}/insurance-contracts/{id}
      • tax_at_source — tax-at-source (withholding tax) state; URI from /luz_person/api/states/{id}
      Asset / liability / equity links:
      • financial_asset — financial asset; URI from /luz_accounting/api/{tenant}/companies/{cid}/financial-asset/{id}
      • intangible_asset — intangible asset; URI from /luz_accounting/api/{tenant}/companies/{cid}/intangible-asset/{id}
      • equity — equity account; URI from /luz_accounting/api/{tenant}/companies/{cid}/equity/{id}
      • long_term_interest_bearing_liability — long-term loan; URI from /luz_accounting/api/{tenant}/companies/{cid}/long-term-interest-bearing/{id}
      • statutory_profit_reserve — statutory profit reserve; URI from /luz_accounting/api/{tenant}/companies/{cid}/statutory-profit-reserve/{id}
      • deferrals — accrual/deferral position; URI from /luz_accounting/api/{tenant}/companies/{cid}/deferral/{id}
      Revenue / inventory / other links:
      • gift_card — gift card; URI from /luz_accounting/api/{tenant}/companies/{cid}/gift-cards/{id}
      • not_billed_services — unbilled service position; URI from /luz_accounting/api/{tenant}/companies/{cid}/not-billed-services/{id}
      • various — miscellaneous counterpart; URI from /luz_accounting/api/{tenant}/companies/{cid}/various/{id}
      • inventory_change_goods — inventory type (static); URI: /luz_accounting/api/inventory-types/inventory-change-goods
      • inventory_change_material — inventory type (static); URI: /luz_accounting/api/inventory-types/inventory-change-material
      • non_billed_services — inventory type (static); URI: /luz_accounting/api/inventory-types/non-billed-services
      • finished_products — inventory type (static); URI: /luz_accounting/api/inventory-types/finished-products
      • unfinished_products — inventory type (static); URI: /luz_accounting/api/inventory-types/unfinished-products
      Multiple entries are comma-separated. Leave empty when none apply.
    • seq integer (int32) format: int32 example: 0
      Ordering of the line inside the booking, starting at 0.
    • vatAccountCode integer (int32) format: int32 example: 1170
      GUI-style VAT input, used only with autoCalculateVat=true: the account the automatically generated VAT counterpart line is posted to (the GUI "VAT account", e.g. 1170). Required on a VAT-bearing line when the line carries a vat_rate link and omits its own VAT line. Ignored when autoCalculateVat is false (caller pre-splits the lines).
    • vatTypeDescription string example: INCLUSIVE
      How VAT is recorded for this line. Allowed values: INCLUSIVE, EXCLUSIVE, NONE.
    • vatBookingDetailLink string
      URI of the companion VAT booking detail, when one was generated automatically.
    • vatAmount number example: 11.4
      VAT amount carried on this line, in the company main currency.
    • vatRate number example: 7.7
      Effective VAT rate (percent) applied to this line.
    • vatRateDisplay string example: 7.7%
      Display string of the VAT rate as rendered in the UI.
    • vatBookingDetail boolean example: False
      True when this line is the automatically generated VAT counterpart of another line.
    • bookingTypeCode string required example: GENERAL_LEDGER
      Business meaning of the booking line. Allowed values include GENERAL_LEDGER, AR_INVOICE, AP_INVOICE, AR_PAYMENT, AP_PAYMENT, AR_CREDIT_NOTE, AP_CREDIT_NOTE.
    • openPositionStatus string example: OPEN
      Lifecycle of the open position represented by this line. Allowed values include OPEN, PARTIALLY_PAID, PAID, CLOSED.
    • creditorReference string
      Creditor reference (QR-bill / ISO 11649) attached to the open position.
    • isrReference string
      ISR reference number attached to the open position.
    • isrMember string
      ISR participant (member) number of the creditor.
    • partnerIban string
      IBAN of the counterpart used for outgoing payments.
    • endToEndId string
      Pain.001 end-to-end id, propagated to the outgoing payment instruction.
    • isExcludeVatAmount boolean example: False
      When true, the gross amount on this line excludes VAT; otherwise it includes VAT.
    • foreignCurrencyAmount number
      Posting amount in the foreign currency, when the line is booked in a non-main currency.
    • foreignCurrencyUnit string example: EUR
      ISO 4217 code of the foreign currency.
    • paidDate string (date-time) format: date-time example: 2024-06-15T00:00:00Z
      Date on which the open position was settled (yyyy-MM-ddT00:00:00Z).
    • dueDate string (date-time) format: date-time example: 2024-06-30T00:00:00Z
      Date on which the open position becomes overdue (yyyy-MM-ddT00:00:00Z).
    • paymentDate string (date-time) format: date-time example: 2024-06-28T00:00:00Z
      Date on which the payment instruction is scheduled (yyyy-MM-ddT00:00:00Z).
    • servicePeriodFrom string (date-time) format: date-time example: 2024-06-01T00:00:00Z
      Start of the service period covered by the line (yyyy-MM-ddT00:00:00Z).
    • servicePeriodTo string (date-time) format: date-time example: 2024-06-30T00:00:00Z
      End of the service period covered by the line (yyyy-MM-ddT00:00:00Z).
    • paymentPercentage number example: 0
      Percentage of the open-position amount already settled.
    • isDunningBlocked boolean example: False
      When true, dunning reminders are suppressed for this open position.
  • invoiceNumber string example: 2024-019
    Invoice number printed on the document.
  • orderManagementInvoiceLink string
    Klara order-management invoice URI when the booking was generated from a Klara invoice.
  • bookingTemplateId integer (int64) format: int64 example: 501
    Id of the booking template the user picked when creating this entry.
  • bookingTitle string example: Office supplies — June 2024
    Short title of the booking shown in lists.
  • totalAmount number example: 150
    Sum of the absolute amounts of the booking lines, in the company main currency.
  • bookingTypeCode string example: GENERAL_LEDGER
    Business meaning of the booking. Allowed values include GENERAL_LEDGER, AR_INVOICE, AP_INVOICE, AR_PAYMENT, AP_PAYMENT, AR_CREDIT_NOTE, AP_CREDIT_NOTE.
Responses 6
200 Booking created. show body

application/json PublicApiBookingHeader

  • id integer (int64) format: int64 example: 12345
    Internal id of the booking. Assigned by the server on creation; omit when sending a new booking.
  • companyId integer (int64) format: int64 example: 1
    Internal id of the company this booking belongs to. Filled by the server from the caller's session; ignored on input.
  • documentDate string (date-time) required format: date-time example: 2024-06-15T00:00:00Z
    Date printed on the underlying document, e.g. supplier invoice date (yyyy-MM-ddT00:00:00Z).
  • bookingDate string (date-time) required format: date-time example: 2024-06-15T00:00:00Z
    Effective accounting date of the booking; must fall inside an open fiscal year unless confirmDontMindClosingFiscalYear is set (yyyy-MM-ddT00:00:00Z).
  • documentIds array of string
    Ids of supporting documents (uploaded files / e-mails) attached to this booking.
  • businessCase string example: Office supplies
    Free-text business case label shown on the journal.
  • snippets array of string
    Snippet identifiers applied to this booking, copied from the booking template.
  • bookingStatus string example: BOOKED
    Status of the booking. Allowed values: DRAFT, BOOKED, CANCELLED.
  • internalComment string
    Internal comment, visible only to accounting users.
  • businessCaseId string
    Reference to the business-case document (workflow id) that produced this booking, when applicable.
  • relatedBookingHeaderLinks array of string
    URIs of bookings that are related to this one (e.g. payment ↔ invoice, original ↔ delimitation).
  • bookingDetails array of PublicApiBookingDetail required minItems: 2
    Debit and credit lines of the booking. Must contain at least two lines whose debit and credit totals balance.
    show fields

    Array of PublicApiBookingDetail.

    • id integer (int64) format: int64 example: 1001
      Internal id of the booking detail. Assigned by the server on creation; omit when sending a new booking.
    • accountCode integer (int32) required format: int32 min: 1 example: 1020
      Ledger account number the amount is posted to (Swiss SME chart of accounts).
    • crdrType string required example: DR
      Whether this line is a credit or a debit. Allowed values: CR, DR.
    • description string required pattern: \S example: Office supplies — invoice 2024-019
      Free-text description shown on the journal report.
    • amount number required example: 150
      Absolute posting amount in the company main currency. Always positive; sign is carried by crdrType.
    • partialPaymentAmount number example: 0
      Amount already paid against this line — only used for open-position bookings (invoices, credit notes).
    • tags string required example: project-alpha,q2
      Comma-separated list of string tags. Each tag is free-form and should represent a topic that the booking line should be associated with. Provide at least one tag per line.
    • links string example: bank_account:/luzfin_finance/api/388c822c-7860-41ae-94ac-330684bb63e0/companies/1/bank-accounts/85,vat_case:/luz_accounting/api/vat-cases/1
      Comma-separated list of structured links of entities that are considered the sub-accounts associated with an account code when making a booking line.This string can be empty when no sub-account is required for the current account code of the booking line.Each link has the format key:uri-path. Important: the exact URI values — including the tenant UUID and company ID segments — are returned verbatim by GET /core/v1/accounting/accounts/account-displaying in the account's specificationItem.link field; copy them as-is, do not construct them manually.

      Supported link type keys:
      Bank / cash sub-accounts (secondary dropdown in GUI for accounts 1000, 1020, 1030, 1040, and similar):
      • bank_account — company bank account; URI from /luzfin_finance/api/{tenant}/companies/{cid}/bank-accounts/{id}
      • cash — cash register; URI from /luz_accounting/api/{tenant}/companies/{cid}/cash/{id}
      • transfer_account — transfer account; URI from /luz_accounting/api/{tenant}/companies/{cid}/transfer/{id}
      • interest_bearing_current_account — interest-bearing current account; URI from /luz_accounting/api/{tenant}/companies/{cid}/interest-bearing-current/{id}
      • non_interest_bearing_current_account — non-interest-bearing current account; URI from /luz_accounting/api/{tenant}/companies/{cid}/non-interest-bearing/{id}
      Counterpart links (customer / supplier / employee sub-ledger):
      • customer — accounts-receivable customer; URI from /luzfin_finance/api/{tenant}/companies/{cid}/customers/{id}
      • supplier — accounts-payable supplier; URI from /luzfin_finance/api/{tenant}/companies/{cid}/customers/{id}
      • employee — employee (payroll/HR); URI from /luz_compensation/api/{tenant}/companies/{cid}/employees/{id}
      Tax / VAT links:
      • vat_case — VAT case; URI from /luz_accounting/api/vat-cases/{id} (obtain from GET /core/latest/vat-cases)
      • vat_rate — master VAT rate; URI from /luz_accounting/api/master-vats/{id} (obtain from GET /core/v1/accounting/master-vats)
      • social_insurance — social insurance contract; URI from /luz_compensation/api/{tenant}/companies/{cid}/insurance-contracts/{id}
      • tax_at_source — tax-at-source (withholding tax) state; URI from /luz_person/api/states/{id}
      Asset / liability / equity links:
      • financial_asset — financial asset; URI from /luz_accounting/api/{tenant}/companies/{cid}/financial-asset/{id}
      • intangible_asset — intangible asset; URI from /luz_accounting/api/{tenant}/companies/{cid}/intangible-asset/{id}
      • equity — equity account; URI from /luz_accounting/api/{tenant}/companies/{cid}/equity/{id}
      • long_term_interest_bearing_liability — long-term loan; URI from /luz_accounting/api/{tenant}/companies/{cid}/long-term-interest-bearing/{id}
      • statutory_profit_reserve — statutory profit reserve; URI from /luz_accounting/api/{tenant}/companies/{cid}/statutory-profit-reserve/{id}
      • deferrals — accrual/deferral position; URI from /luz_accounting/api/{tenant}/companies/{cid}/deferral/{id}
      Revenue / inventory / other links:
      • gift_card — gift card; URI from /luz_accounting/api/{tenant}/companies/{cid}/gift-cards/{id}
      • not_billed_services — unbilled service position; URI from /luz_accounting/api/{tenant}/companies/{cid}/not-billed-services/{id}
      • various — miscellaneous counterpart; URI from /luz_accounting/api/{tenant}/companies/{cid}/various/{id}
      • inventory_change_goods — inventory type (static); URI: /luz_accounting/api/inventory-types/inventory-change-goods
      • inventory_change_material — inventory type (static); URI: /luz_accounting/api/inventory-types/inventory-change-material
      • non_billed_services — inventory type (static); URI: /luz_accounting/api/inventory-types/non-billed-services
      • finished_products — inventory type (static); URI: /luz_accounting/api/inventory-types/finished-products
      • unfinished_products — inventory type (static); URI: /luz_accounting/api/inventory-types/unfinished-products
      Multiple entries are comma-separated. Leave empty when none apply.
    • seq integer (int32) format: int32 example: 0
      Ordering of the line inside the booking, starting at 0.
    • vatAccountCode integer (int32) format: int32 example: 1170
      GUI-style VAT input, used only with autoCalculateVat=true: the account the automatically generated VAT counterpart line is posted to (the GUI "VAT account", e.g. 1170). Required on a VAT-bearing line when the line carries a vat_rate link and omits its own VAT line. Ignored when autoCalculateVat is false (caller pre-splits the lines).
    • vatTypeDescription string example: INCLUSIVE
      How VAT is recorded for this line. Allowed values: INCLUSIVE, EXCLUSIVE, NONE.
    • vatBookingDetailLink string
      URI of the companion VAT booking detail, when one was generated automatically.
    • vatAmount number example: 11.4
      VAT amount carried on this line, in the company main currency.
    • vatRate number example: 7.7
      Effective VAT rate (percent) applied to this line.
    • vatRateDisplay string example: 7.7%
      Display string of the VAT rate as rendered in the UI.
    • vatBookingDetail boolean example: False
      True when this line is the automatically generated VAT counterpart of another line.
    • bookingTypeCode string required example: GENERAL_LEDGER
      Business meaning of the booking line. Allowed values include GENERAL_LEDGER, AR_INVOICE, AP_INVOICE, AR_PAYMENT, AP_PAYMENT, AR_CREDIT_NOTE, AP_CREDIT_NOTE.
    • openPositionStatus string example: OPEN
      Lifecycle of the open position represented by this line. Allowed values include OPEN, PARTIALLY_PAID, PAID, CLOSED.
    • creditorReference string
      Creditor reference (QR-bill / ISO 11649) attached to the open position.
    • isrReference string
      ISR reference number attached to the open position.
    • isrMember string
      ISR participant (member) number of the creditor.
    • partnerIban string
      IBAN of the counterpart used for outgoing payments.
    • endToEndId string
      Pain.001 end-to-end id, propagated to the outgoing payment instruction.
    • isExcludeVatAmount boolean example: False
      When true, the gross amount on this line excludes VAT; otherwise it includes VAT.
    • foreignCurrencyAmount number
      Posting amount in the foreign currency, when the line is booked in a non-main currency.
    • foreignCurrencyUnit string example: EUR
      ISO 4217 code of the foreign currency.
    • paidDate string (date-time) format: date-time example: 2024-06-15T00:00:00Z
      Date on which the open position was settled (yyyy-MM-ddT00:00:00Z).
    • dueDate string (date-time) format: date-time example: 2024-06-30T00:00:00Z
      Date on which the open position becomes overdue (yyyy-MM-ddT00:00:00Z).
    • paymentDate string (date-time) format: date-time example: 2024-06-28T00:00:00Z
      Date on which the payment instruction is scheduled (yyyy-MM-ddT00:00:00Z).
    • servicePeriodFrom string (date-time) format: date-time example: 2024-06-01T00:00:00Z
      Start of the service period covered by the line (yyyy-MM-ddT00:00:00Z).
    • servicePeriodTo string (date-time) format: date-time example: 2024-06-30T00:00:00Z
      End of the service period covered by the line (yyyy-MM-ddT00:00:00Z).
    • paymentPercentage number example: 0
      Percentage of the open-position amount already settled.
    • isDunningBlocked boolean example: False
      When true, dunning reminders are suppressed for this open position.
  • invoiceNumber string example: 2024-019
    Invoice number printed on the document.
  • orderManagementInvoiceLink string
    Klara order-management invoice URI when the booking was generated from a Klara invoice.
  • bookingTemplateId integer (int64) format: int64 example: 501
    Id of the booking template the user picked when creating this entry.
  • bookingTitle string example: Office supplies — June 2024
    Short title of the booking shown in lists.
  • totalAmount number example: 150
    Sum of the absolute amounts of the booking lines, in the company main currency.
  • bookingTypeCode string example: GENERAL_LEDGER
    Business meaning of the booking. Allowed values include GENERAL_LEDGER, AR_INVOICE, AP_INVOICE, AR_PAYMENT, AP_PAYMENT, AR_CREDIT_NOTE, AP_CREDIT_NOTE.
400 Data invalid show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
PUT/core/v1/bookings/{id}/documentskey / tokenReplace the document attachments and document date of an existing booking.
Replaces the set of supporting-document identifiers and the document date stored on an existing accounting booking. The operation is a full replacement — pass an empty documentIds array to clear all existing attachments, or omit documentDate / set it to null to clear it. By default the operation fails when the booking's existing bookingDate falls outside the active Klara Accounting subscription window; set ignore-unsubscripted-dates to true to bypass this guard. Tenant and company are derived from the bearer token — the booking {id} must belong to the caller's company. The caller must hold the ACCOUNTING permission on that company. The endpoint is idempotent: re-sending the same body produces the same state. Returns HTTP 200 with no body on success.
Required permission

ACCOUNTING

Parameters 2
NameDescription
id required
path integer (int64)
Internal id of the booking whose documents should be replaced. Obtain from the id field returned by POST /core/v1/bookings.
format: int64 example: 12345
ignore-unsubscripted-dates
query boolean
When true, accept the update even if the booking's bookingDate falls outside the active Klara Accounting subscription period. Defaults to false.
default: false example: False
Request body required
Document metadata to apply to the booking. The operation is a full replacement of both documentDate and documentIds.

Prerequisite APIs — call these first to obtain valid values:
  • POST /core/v1/bookings → provides the booking id used in the URL.
  • POST /core/latest/companies/{company-id}/documents → upload the file first and use the returned documentId as an entry in documentIds. Each entry is either a numeric Klara document id (e.g. "98765") or a Klara document URI.
Top-level fields:
  • documentDate (string, ISO date yyyy-MM-dd, optional) — date printed on the underlying paper document. Set to null or omit to clear the existing value.
  • documentIds (array of string, optional, max 50 entries, each ≤ 512 chars) — full replacement of the attached document references. Send [] to clear.
Rules:
  • Replacement semantics — missing or empty documentIds clears all existing attachments on the booking.
  • The booking must belong to the caller's company; tenant and company are derived from the bearer token.
  • By default the booking's existing bookingDate must fall in an active Klara Accounting subscription window; use ignore-unsubscripted-dates=true to bypass.

application/json object

  • documentDate string (date) format: date example: 2024-06-15
    Date printed on the underlying paper document (e.g. supplier invoice date). When omitted or null, the booking's existing documentDate is cleared.
  • documentIds array of string maxItems: 50
    Identifiers of supporting documents attached to the booking. Replaces the current set on the booking; pass an empty array to clear. Obtain each id by first uploading a file with POST /core/latest/companies/{company-id}/documents and then copying the returned documentId into this array.
Responses 6
200 Document attachments and date applied to the booking (or accepted as a no-op when the booking does not exist on the downstream side). no response body
400 Data invalid show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
POST/core/v1/vat-clearing-reports/{year}/{quarter}key / tokenGet or recompute the VAT clearing report of a company for a given period.
Returns the VAT clearing report of the caller's company for the requested calendar year and reporting quarter (quarter, semester or yearly). When recalculate=true the report is recomputed from the current bookings and the stored CALCULATED snapshot is rewritten before being returned; this is why the operation uses POST rather than GET. When recalculate=false the latest CALCULATED snapshot is returned as-is, or — if only a SEALED snapshot exists — that one. The caller must hold the ACCOUNTING permission on the targeted company.
Required permission

ACCOUNTING

Parameters 4
NameDescription
quarter required
path string
Reporting period within the year. Allowed values: Q1, Q2, Q3, Q4, S1, S2, YEAR_NET_TAX_RATE, YEAR_EFFECTIVE.
Allowed values: Q1, Q2, Q3, Q4, S1, S2, YEAR_NET_TAX_RATE, YEAR_EFFECTIVE
example: Q1
year required
path integer
Calendar year of the reporting period.
example: 2024
recalculate
query boolean
If true, recompute the report from current bookings and overwrite the stored CALCULATED snapshot before returning. Defaults to false.
default: false example: False
Accept-Language
header string
Preferred language for localized labels in the response. Examples: de-CH, de, fr-CH, it-CH, en.
example: de-CH
Responses 6
200 The VAT clearing report. show body

application/json VatClearingReport

  • id integer (int64) format: int64 example: 987
    Internal id of the report.
  • codeBoxes array of VatClearingReportCodeBox
    Code boxes that compose the VAT statement.
    show fields

    Array of VatClearingReportCodeBox.

    • id integer (int64) format: int64 example: 1234
      Internal id of the code box.
    • code string example: 302
      Code of the box on the VAT statement.
    • value number example: 12345.67
      Computed amount of the box.
    • description string example: Steuerbarer Umsatz
      Localized description of the box.
    • editable boolean example: False
      Whether the value of this box is editable by the user.
    • editableDescription boolean example: True
      Whether the description of this box is editable by the user.
    • rate number example: 8.1
      VAT rate applied to this code box, in percent.
  • status object example: CALCULATED
    Current status of a VAT clearing report.
  • year integer (int32) format: int32 example: 2024
    Calendar year of the reporting period.
  • period object example: Q1
    Reporting period of a VAT clearing report.
  • correctionCount integer (int32) format: int32 example: 0
    Number of booking corrections detected versus the sealed snapshot.
  • formerVatRateReleaseDate string (date) format: date example: 2023-12-31T00:00:00Z
    Release date of the former VAT rates that still apply to a part of the period.
  • newVatRatesReleased boolean example: False
    Whether new VAT rates have been released and apply to part of the period.
  • periodFrom string (date) format: date example: 2024-01-01T00:00:00Z
    Start date of the reporting period.
  • periodTo string (date) format: date example: 2024-03-31T00:00:00Z
    End date of the reporting period.
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found no response body
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. no response body

Accounting Interface1

POST/core/latest/payroll-interface-filekey / tokenReturn payroll interface file
Return the payroll accounting interface file for a given salary run or payslips in CSV or JSON format
Parameters 3
NameDescription
file-format
query object
File format
payslip-ids
query string
List of payslip ids, separate by comma
example: 1,2,3,4
salary-run-id
query integer
Salary run id
example: 1
Responses 7
200 Return the payroll accounting interface file for a given salary run or payslips in CSV or JSON format show body

application/octet-stream any

400 Data invalid show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. no response body

Finance11

GET/core/v1/company-bank-accountskey / tokenList the bank accounts of the authenticated company.
Returns the bank accounts of the company resolved from the bearer JWT, optionally filtered by business type. The caller must hold the FINANCE_BANK_ACCOUNT permission on the target company. The result is sorted by Swiss-bank name then IBAN. This operation is idempotent and read-only — it can be safely retried.
Required permission

FINANCE_BANK_ACCOUNT

Parameters 2
NameDescription
iban-number
query string
Optional IBAN filter. When provided, the response contains the single matching bank account (returned as a one-element array for a uniform response shape) or HTTP 404 if no account exists with that IBAN. Spaces in the IBAN are tolerated. When provided, the type parameter is ignored.
example: CH7109000000252946932
type
query string
Optional business-type filter. Allowed values: AR (Accounts Receivable), AP (Accounts Payable), HR (Salary / HR payments). When omitted, all bank accounts are returned. Ignored when iban-number is provided.
Allowed values: AR, AP, HR
example: AR
Responses 6
200 Bank accounts of the authenticated company. show body

application/json array of CompanyBankAccount

Array of CompanyBankAccount.

  • id integer (int64) format: int64 example: 1
    Internal database id of the bank account.
  • companyId integer (int64) format: int64 example: 1
    KLARA company id this bank account belongs to.
  • shortName string example: PostFinance CHF
    User-defined short label for the bank account.
  • ibanNumber string example: CH71 0900 0000 2529 4693 2
    IBAN in pretty-printed form (groups of 4 characters).
  • qrIbanNumber string example: CH44 3199 9123 0008 8901 2
    QR-IBAN (only set when markedQrIban is true).
  • currency string example: CHF
    ISO-style currency code. Allowed values: CHF, CHW.
  • wirAcceptanceRate number example: 0
    WIR acceptance percentage (0–100).
  • markedHRPayment boolean example: False
    Default account for salary / HR payments.
  • markedARAccount boolean example: True
    Default account for Accounts Receivable.
  • markedAPAccount boolean example: False
    Default account for Accounts Payable.
  • markedPaymentSlip boolean example: False
    ESR / red payment-slip enabled.
  • markedQrInvoice boolean example: True
    QR-invoice payment enabled.
  • markedQrIban boolean example: False
    QR-IBAN flow enabled.
  • participantNumber string example: 01-12345-6
    ESR participant number (only when markedPaymentSlip).
  • customerIdentificationNumber string example: 123456
    ESR customer identification number (only when markedPaymentSlip and not PostFinance).
  • printParticipantNumber boolean example: False
    Print the participant number on payment slips.
  • printBankAddress boolean example: False
    Print the bank address on payment slips.
  • printBeneficiary boolean example: False
    Print the beneficiary on payment slips.
  • esrPrintingType string example: INTEGRATE
    ESR printing type. Allowed values: INTEGRATE, SEPARATE.
  • contractNumber string example:
    Bank contract number.
  • batchBooking string example: DEFAULT
    Batch-booking preference. Allowed values: DEFAULT, ACTIVE, INACTIVE.
  • debitAdvice string example: DEFAULT
    Debit-advice preference. Allowed values: DEFAULT, NO_ADVICE, SINGLE_ADVICE, ADVICE_WITHOUT_DETAILS, ADVICE_WITH_DETAIL.
  • notMarkedSalaryPayments boolean example: False
    When true, exclude this bank account from salary-payment runs.
  • swissBank object
    Resolved Swiss-bank master-data record (name, address, BCNR). May have empty fields when the IBAN's clearing number does not match a known Swiss bank.
    show fields
    • id integer (int64) format: int64 example: 100
      Internal Swiss-bank master-data id.
    • group string example: 1
      Master-data group code.
    • bankClearingNumber string example: 100
      Bank clearing number (BCNR).
    • branchId string example: 1
      Branch identifier.
    • newBankClearingNumber string example:
      Successor BCNR if the bank has been replaced.
    • sicNumber string example: 100000
      SIC member number.
    • headOfficeNumber string example: 100
      Head-office BCNR.
    • bankClearingType string example: 1
      Bank-clearing classification code.
    • euroSic string example:
      SIC participation in EUR.
    • language string example: de
      Master-data language code.
    • shortName string example: PostFinance AG
      Bank short name.
    • name string example: PostFinance AG
      Bank legal name.
    • address string example: Mingerstrasse 20
      Bank street address.
    • postalAddress string example: Postfach
      Postal address (PO Box).
    • place string example: Bern
      City / locality.
    • phone string example: +41 58 338 25 00
      Bank phone number.
    • fax string example:
      Bank fax number.
    • dailingCode string example: 41
      International dialling code.
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found no response body
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. no response body
POST/core/v1/invoiceskey / tokenCreate 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 id must be 0 or omitted — this endpoint does not support updating existing invoices.

Typical flow:
  1. Call GET /core/v1/invoices/next-invoice-number to obtain the next invoice number.
  2. Look up the customer via GET /core/latest/customers (with search filters).
  3. Look up company bank accounts via GET /core/v1/company-bank-accounts.
  4. Search articles via GET /core/latest/articles/search or GET /core/latest/articles/article-numbers to populate order items.
  5. (Optional) Look up open positions via GET /core/v1/bank-reconciliation/open-positions to reconcile prepayments / credit notes.
  6. (Optional) Call POST /core/v1/orders/next-order-number to obtain the next order.orderNumber.
  7. (Optional) Call GET /core/latest/company-configuration/including-vat to determine the company default for usingVAT.
  8. Build the invoice payload with order items.
  9. Call this endpoint with status=INVOICED to save and book, or status=DRAFT to save without booking.
On status INVOICED or SENT 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 postMethod or a SENT status; retrieve the PDF via POST /core/v1/invoices/{id}/printed-document and deliver it yourself. The caller must hold the FINANCE permission on the target company.

Status is caller-controlled. The Klara GUI keeps an invoice in DRAFT until the user posts it in the final step; via the API you choose — send status=DRAFT to save without booking, or status=INVOICED (or SENT) to book immediately. A DRAFT can be finalized later with PUT /core/v1/invoices (status=INVOICED).

Important — booking is created without a printed invoice. When you book via this endpoint (status=INVOICED/SENT), 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) POST /core/v1/invoices/{id}/printed-document to render the PDF and store its printedFileId on the invoice, then (2) PUT /core/v1/bookings/{id}/documents to link that printedFileId (in documentIds) to the booking returned in bookingNumbers.
Required permission

FINANCE

Parameters 2
NameDescription
confirmDontMindClosingFiscalYear
query boolean
When true, allows save/booking even if the document date falls inside a closing or closed fiscal year. Defaults to false.
default: false example: False
Accept-Language
header string
Preferred response language as a BCP-47 tag (e.g. en, de, fr, it). Forwarded to luzfin_finance.
example: en
Request body required
Creates a new invoice for an existing customer. The id field must be 0 or omitted. This endpoint does not support updating existing invoices.

Prerequisite APIs (call these first):
  • GET /core/v1/invoices/next-invoice-number → provides invoiceCode and invoiceNumber (the next available invoice number for the company).
  • GET /core/latest/customers?searchKey=...&limit=... → provides order.customer.id, order.customer.company (with addresses, emails), and order.customer.customerType.
  • GET /core/v1/company-bank-accounts → provides ibanNumberCHF / ibanNumberCHW for payment accounts.
  • GET /core/latest/articles/search?keyword=... → search articles by keyword for the autocomplete; provides orderItems[].itemNumer, description, price, vat, unit.
  • GET /core/latest/articles/article-numbers?article-numbers=... → fetch full article data by article number(s) to fill orderItems[].
  • GET /core/latest/articles/{article-id}/article-set-items → expands article set/bundle into component line items for orderItems[].
  • GET /core/v1/bank-reconciliation/open-positions → lists customer's open prepayments / credit notes that can be reconciled; provides openPositionsLinkedToInvoice[].bookingTypeCode, bookingDetailUri, partialPaymentAmount.
  • (Optional) POST /core/v1/orders/next-order-number → provides order.orderNumber; each call advances the in-memory counter — call immediately before creating the invoice, not speculatively.
  • (Optional) GET /core/latest/company-configuration/including-vat → provides the company-level default for usingVAT; returns false when no configuration record exists.
  • printedFileId (String, server-assigned) — populated automatically by POST /core/v1/invoices/{id}/printed-document after PDF generation; omit on creation.

Top-level fields:
  • id (long, required) — must be 0 for creation.
  • invoiceCode (String, required) — unique invoice code; obtain from GET /core/v1/invoices/next-invoice-number.
  • orderType (String, required) — must be INVOICE.
  • status (String, required) — determines booking behavior (not delivery). Allowed: DRAFT (saves without booking), INVOICED (saves and books into accounting), SENT (saves and books; does not send/deliver the invoice).
  • postMethod (String, optional) — distribution channel recorded on the invoice only; this endpoint does not deliver the invoice. Allowed: A_POST, B_POST, SEND_EMAIL, PRINT_AND_MANUAL_SEND, EPOST, EBILL.
  • documentDate (date, required) — invoice issue date, format yyyy-MM-dd.
  • paymentDate (date, required) — payment due date, must be on or after documentDate.
  • ibanNumberCHF (String, conditional) — CHF IBAN for payment; required when booking is triggered.
  • ibanNumberCHW (String, optional) — WIR IBAN for combined payments.
  • wirAcceptanceRate (int, optional) — WIR acceptance percentage (0–100).
  • invoiceType (String, required) — MANUAL or RECURRING.
  • amount (BigDecimal, required) — total invoice amount over all items. Caller-supplied; not recomputed by the server. With usingVAT=false this is net + VAT; with usingVAT=true it is the sum of the gross item amounts.
  • usingVAT (boolean) — GUI checkbox "VAT included in amount of each item". Controls whether item price/amount are VAT-inclusive (true, gross) or VAT-exclusive (false, net). It does not switch VAT on/off (that is the company's VAT registration). Use GET /core/latest/company-configuration/including-vat for the company default. See VAT handling below.
  • usingExportVat (boolean, optional) — GUI checkbox "Export". When true, the invoice is an export: set every orderItems[].vat.rate to 0 so no VAT is charged. Defaults to false.
  • subject (String, optional) — invoice subject/title.
  • ourReference / yourReference (String, optional) — reference texts.
  • companyCityAndDate (String, optional) — city and date line printed on invoice.
  • closeAndSignature (String, optional) — closing text and signature block.
  • printedFileId (String, optional) — document ID of uploaded PDF from partner system.

Nested fields — order (required):
  • order.id (long) — must be 0 for new orders.
  • order.orderNumber (int, required) — unique order number; must be > 0 (validated). Obtain from POST /core/v1/orders/next-order-number (not idempotent — each call advances the counter).
  • order.orderName (String, optional) — order description.
  • order.companyId (long, required) — company ID from bearer token scope.
  • order.customer (object, required) — existing customer; obtain from GET /core/v1/customers. Must include customer.id, customer.company (with addresses), and customer.customerType (COMPANY or PERSON).

Nested fields — orderItems[] (required, at least 1):
  • orderItems[].position (int) — line item position (1-based).
  • orderItems[].itemNumer (String) — article number.
  • orderItems[].description (String) — item description.
  • orderItems[].quantity (double) — quantity.
  • orderItems[].unit (String) — unit of measure (e.g. Unit, Hour).
  • orderItems[].price (double) — unit price (negative for credit notes). VAT-inclusive (gross) when usingVAT=true, VAT-exclusive (net) when usingVAT=false. Both variants are available from the article lookup APIs.
  • orderItems[].discount (double) — discount percentage.
  • orderItems[].amount (double) — line total = quantity × price × (1 − discount/100), rounded to the nearest 0.05. Gross or net following usingVAT (same basis as price).
  • orderItems[].tag (String, required for booking) — tags field; must not be empty when status is INVOICED/SENT.
  • orderItems[].vatCase (String) — TAXABLE_SUPPLY, EXEMPT_SUPPLY, REVERSE_CHARGE.
  • orderItems[].articleType (String) — PRODUCTION, PREPAYMENT, SERVICE.
  • orderItems[].vat (object) — VAT details: vatCode, rate, description, masterId. For an export invoice (usingExportVat=true) set rate=0 and the export/zero vatCode.
  • orderItems[].id (long) — must be 0 for new items.

VAT handling — the server does not recalculate amounts. Unlike the Klara GUI (which recomputes line amounts, VAT and totals whenever you toggle the "VAT included in amount of each item" or "Export" checkbox), this endpoint stores the amounts you send verbatim and performs no VAT recalculation or consistency check. Send orderItems[].price, orderItems[].amount, orderItems[].vat and the document amount already consistent with the two flags:
  • usingVAT=false (VAT-exclusive) — price/amount are net; document amount = net + VAT.
  • usingVAT=true (VAT-inclusive) — price/amount are gross (VAT already inside); document amount = sum of gross item amounts.
  • usingExportVat=true (export) — set every orderItems[].vat.rate to 0; VAT = 0 and document amount = sum of net item amounts.
To reproduce the GUI figures exactly: per line amount = round0.05(quantity × price × (1 − discount/100)); VAT per rate group = amount × rate/100 when VAT-exclusive, or amount × (rate/100) / (1 + rate/100) when VAT-inclusive — each rounded to the nearest 0.05 (Swiss commercial rounding). Article unit prices for the inclusive, exclusive and export cases come from the article lookup APIs above (each article exposes both a VAT-inclusive and a VAT-exclusive price); pick the one matching usingVAT/usingExportVat.

Nested fields — attachments[] (optional):
  • attachments[].fileId (String) — document file ID uploaded via partner system.
  • attachments[].orderDetailId (long) — set to 0 for new invoices.
  • attachments[].id (long) — set to 0 for new attachments.

Nested fields — openPositionsLinkedToInvoice[] (optional, for reconciliation):
  • openPositionsLinkedToInvoice[].bookingTypeCode (String) — AR_PREPAYMENT or AR_CREDITNOTE.
  • openPositionsLinkedToInvoice[].bookingDetailUri (String) — internal URI of the booking detail to reconcile (format: /luz_accounting/api/{tenant-id}/companies/{companyId}/bookings/{bookingId}/booking-details/{detailId}).
  • openPositionsLinkedToInvoice[].partialPaymentAmount (BigDecimal) — amount to offset from this open position.

Validation rules:
  • paymentDate must be on or after documentDate (when amount > 0).
  • order.orderNumber must be > 0.
  • invoiceCode must be unique within the company.
  • status must not be null.
  • IBAN format is validated when provided.
  • When status is SENT, credit notes (negative total) are not allowed.
  • Each orderItems[].tag must be present when status triggers booking (INVOICED/SENT).

Server-managed fields (ignored on input, populated on output): vatDate, lastModified, createDate, bookingDueDate, bookingNumbers, businessCaseId, bookingStatus, bookingMessage, bookingSealed, fiscalYearHasCreatedAuto, createBy, issuedDate.

application/json Invoice

  • id integer (int64) format: int64 example: 0
    Invoice id. Must be 0 or omitted when creating a new invoice. This endpoint only supports creation; updating an existing invoice is not supported.
  • orderType string default: INVOICE example: INVOICE
    Polymorphic discriminator. Must be INVOICE. Allowed values: INVOICE.
  • status string example: INVOICED
    Invoice status. Allowed values: DRAFT, INVOICED, SENT, PAID, CANCELLED. Required. Status INVOICED or SENT triggers accounting booking.
  • invoiceCode string required maxLength: 64 pattern: \S example: INV-2026-001
    Human-readable invoice code. Required and unique per company.
  • invoiceNumber integer (int64) format: int64 example: 2026001
    Sequential invoice number, typically obtained from GET /invoices/next-invoice-number.
  • documentDate string (date) format: date example: 2026-05-28
    Invoice document date (ISO 8601). Required when amount is greater than 0. Must fall inside the company's active Order Management subscription period.
  • paymentDate string (date) format: date example: 2026-06-27
    Payment due date (ISO 8601). Required when amount is greater than 0. Must be on or after documentDate.
  • deliveryDate string (date) format: date example: 2026-05-25
    Service delivery date (ISO 8601).
  • issuedDate string (date) format: date example: 2026-05-28
    Date the invoice was issued (ISO 8601).
  • servicePeriodFrom string (date) format: date example: 2026-05-01
    Service period start date (ISO 8601).
  • servicePeriodTo string (date) format: date example: 2026-05-31
    Service period end date (ISO 8601).
  • servicePeriodPattern string maxLength: 32 example: MONTHLY
    Service period pattern label (e.g. MONTHLY, YEARLY).
  • vatDate string (date) format: date
    VAT date. Server-managed (read-only).
  • bookingDueDate string (date) format: date
    Booking due date returned by accounting. Server-managed (read-only).
  • lastModified string (date-time) format: date-time
    Last modification timestamp. Server-managed (read-only).
  • createDate string (date-time) format: date-time
    Creation timestamp. Server-managed (read-only).
  • amount number example: 1080
    Invoice total. When usingVAT=false (VAT-exclusive items) this is the gross total = net + VAT; when usingVAT=true (VAT-inclusive items) it is the sum of the gross item amounts (VAT already inside). Caller-supplied — the server does not recompute it.
  • usingVAT boolean default: false example: True
    Controls whether each item price/amount is VAT-inclusive (gross) or VAT-exclusive (net). This is the GUI checkbox "VAT included in amount of each item". true = amounts already include VAT (INCLUDE_VAT); false = 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 GET /core/latest/company-configuration/including-vat for the company default. The server stores the amounts you send verbatim and does not recompute them from this flag — send price/amount consistent with the chosen mode (see the create operation's VAT-handling notes).
  • usingExportVat boolean default: false example: False
    Export invoice flag — the GUI "Export" checkbox. When true, the invoice is treated as an export: every orderItems[].vat.rate must be 0 (export/zero VAT code), so no VAT is charged. When false (default) the items' normal VAT rates apply. The server does not recompute item VAT from this flag — set the per-item VAT accordingly.
  • subject string maxLength: 1024 example: Invoice 2026-001
    Free-text invoice subject.
  • closeAndSignature string maxLength: 4096 example: Thank you for your business.
    Free-text closing remarks / signature block.
  • ourReference string maxLength: 128 example: ACC-2026
    Internal sender reference.
  • yourReference string maxLength: 128 example: PO-9981
    Customer-side reference (e.g. PO number).
  • companyCityAndDate string maxLength: 256 example: Zurich, 28.05.2026
    Header line such as 'Zurich, 28.05.2026'.
  • postMethod string example: SEND_EMAIL
    Distribution channel recorded on the invoice. Stored only — creating an invoice does not deliver it (no email/ePost/eBill/print&send). Allowed values: A_POST, B_POST, SEND_EMAIL, PRINT_AND_MANUAL_SEND, EPOST, EBILL.
  • delivery string maxLength: 64 example: DHL
    Delivery method label (free text).
  • ibanNumberCHF string example: CH9300762011623852957
    CHF IBAN for payment. Validated by downstream service.
  • ibanNumberCHW string example: CH9300762011623852957
    WIR-franc IBAN for payment.
  • wirAcceptanceRate number example: 0
    WIR acceptance percentage.
  • referenceNumber string maxLength: 64 example: 21 00000 00003 13947 14300 09017
    QR / ISR reference number.
  • qrInvoice boolean default: false example: True
    When true, the invoice is rendered/booked as a Swiss QR-invoice. Defaults to false.
  • fromAutoInvoicing boolean default: false example: False
    Indicates the invoice was generated by auto-invoicing. Defaults to false.
  • fromInvoiceRun boolean default: false example: False
    Indicates the invoice was produced by a recurring invoice run. When true, accounting booking and inventory transactions are skipped. Defaults to false.
  • invoiceType string example: MANUAL
    Invoice type. Allowed values: MANUAL, CREDIT_DEBIT.
  • originDistributionMethod string example: SEND_EMAIL
    Origin distribution method. Allowed values: A_POST, B_POST, SEND_EMAIL, PRINT_AND_MANUAL_SEND, EPOST, EBILL.
  • templateId integer (int64) format: int64 example: 0
    Template id used to create this invoice.
  • runHistoryId integer (int64) format: int64 example: 0
    Recurring invoice run history id.
  • settledAmount number example: 0
    Klara-Pay settled amount (online shop only).
  • bookingNumbers string
    Accounting booking-number string. Server-managed (read-only).
  • businessCaseId integer (int64) format: int64
    Accounting business case id. Server-managed (read-only).
  • bookingStatus string
    Booking status (e.g. OPEN, PARTIAL, PAID). Server-managed (read-only).
  • bookingMessage string
    Optional booking error/info code (e.g. INVALID_SUBSCRIPTION_FOR_ACCOUNTING). 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).
Responses 7
200 Invoice persisted successfully. show body

application/json Invoice

  • id integer (int64) format: int64 example: 0
    Invoice id. Must be 0 or omitted when creating a new invoice. This endpoint only supports creation; updating an existing invoice is not supported.
  • orderType string default: INVOICE example: INVOICE
    Polymorphic discriminator. Must be INVOICE. Allowed values: INVOICE.
  • status string example: INVOICED
    Invoice status. Allowed values: DRAFT, INVOICED, SENT, PAID, CANCELLED. Required. Status INVOICED or SENT triggers accounting booking.
  • invoiceCode string required maxLength: 64 pattern: \S example: INV-2026-001
    Human-readable invoice code. Required and unique per company.
  • invoiceNumber integer (int64) format: int64 example: 2026001
    Sequential invoice number, typically obtained from GET /invoices/next-invoice-number.
  • documentDate string (date) format: date example: 2026-05-28
    Invoice document date (ISO 8601). Required when amount is greater than 0. Must fall inside the company's active Order Management subscription period.
  • paymentDate string (date) format: date example: 2026-06-27
    Payment due date (ISO 8601). Required when amount is greater than 0. Must be on or after documentDate.
  • deliveryDate string (date) format: date example: 2026-05-25
    Service delivery date (ISO 8601).
  • issuedDate string (date) format: date example: 2026-05-28
    Date the invoice was issued (ISO 8601).
  • servicePeriodFrom string (date) format: date example: 2026-05-01
    Service period start date (ISO 8601).
  • servicePeriodTo string (date) format: date example: 2026-05-31
    Service period end date (ISO 8601).
  • servicePeriodPattern string maxLength: 32 example: MONTHLY
    Service period pattern label (e.g. MONTHLY, YEARLY).
  • vatDate string (date) format: date
    VAT date. Server-managed (read-only).
  • bookingDueDate string (date) format: date
    Booking due date returned by accounting. Server-managed (read-only).
  • lastModified string (date-time) format: date-time
    Last modification timestamp. Server-managed (read-only).
  • createDate string (date-time) format: date-time
    Creation timestamp. Server-managed (read-only).
  • amount number example: 1080
    Invoice total. When usingVAT=false (VAT-exclusive items) this is the gross total = net + VAT; when usingVAT=true (VAT-inclusive items) it is the sum of the gross item amounts (VAT already inside). Caller-supplied — the server does not recompute it.
  • usingVAT boolean default: false example: True
    Controls whether each item price/amount is VAT-inclusive (gross) or VAT-exclusive (net). This is the GUI checkbox "VAT included in amount of each item". true = amounts already include VAT (INCLUDE_VAT); false = 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 GET /core/latest/company-configuration/including-vat for the company default. The server stores the amounts you send verbatim and does not recompute them from this flag — send price/amount consistent with the chosen mode (see the create operation's VAT-handling notes).
  • usingExportVat boolean default: false example: False
    Export invoice flag — the GUI "Export" checkbox. When true, the invoice is treated as an export: every orderItems[].vat.rate must be 0 (export/zero VAT code), so no VAT is charged. When false (default) the items' normal VAT rates apply. The server does not recompute item VAT from this flag — set the per-item VAT accordingly.
  • subject string maxLength: 1024 example: Invoice 2026-001
    Free-text invoice subject.
  • closeAndSignature string maxLength: 4096 example: Thank you for your business.
    Free-text closing remarks / signature block.
  • ourReference string maxLength: 128 example: ACC-2026
    Internal sender reference.
  • yourReference string maxLength: 128 example: PO-9981
    Customer-side reference (e.g. PO number).
  • companyCityAndDate string maxLength: 256 example: Zurich, 28.05.2026
    Header line such as 'Zurich, 28.05.2026'.
  • postMethod string example: SEND_EMAIL
    Distribution channel recorded on the invoice. Stored only — creating an invoice does not deliver it (no email/ePost/eBill/print&send). Allowed values: A_POST, B_POST, SEND_EMAIL, PRINT_AND_MANUAL_SEND, EPOST, EBILL.
  • delivery string maxLength: 64 example: DHL
    Delivery method label (free text).
  • ibanNumberCHF string example: CH9300762011623852957
    CHF IBAN for payment. Validated by downstream service.
  • ibanNumberCHW string example: CH9300762011623852957
    WIR-franc IBAN for payment.
  • wirAcceptanceRate number example: 0
    WIR acceptance percentage.
  • referenceNumber string maxLength: 64 example: 21 00000 00003 13947 14300 09017
    QR / ISR reference number.
  • qrInvoice boolean default: false example: True
    When true, the invoice is rendered/booked as a Swiss QR-invoice. Defaults to false.
  • fromAutoInvoicing boolean default: false example: False
    Indicates the invoice was generated by auto-invoicing. Defaults to false.
  • fromInvoiceRun boolean default: false example: False
    Indicates the invoice was produced by a recurring invoice run. When true, accounting booking and inventory transactions are skipped. Defaults to false.
  • invoiceType string example: MANUAL
    Invoice type. Allowed values: MANUAL, CREDIT_DEBIT.
  • originDistributionMethod string example: SEND_EMAIL
    Origin distribution method. Allowed values: A_POST, B_POST, SEND_EMAIL, PRINT_AND_MANUAL_SEND, EPOST, EBILL.
  • templateId integer (int64) format: int64 example: 0
    Template id used to create this invoice.
  • runHistoryId integer (int64) format: int64 example: 0
    Recurring invoice run history id.
  • settledAmount number example: 0
    Klara-Pay settled amount (online shop only).
  • bookingNumbers string
    Accounting booking-number string. Server-managed (read-only).
  • businessCaseId integer (int64) format: int64
    Accounting business case id. Server-managed (read-only).
  • bookingStatus string
    Booking status (e.g. OPEN, PARTIAL, PAID). Server-managed (read-only).
  • bookingMessage string
    Optional booking error/info code (e.g. INVALID_SUBSCRIPTION_FOR_ACCOUNTING). 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).
400 Data invalid show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found no response body
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. no response body
PUT/core/v1/invoiceskey / tokenUpdate an existing DRAFT invoice for the authenticated company.
Updates a DRAFT invoice identified by invoice.id in the request body. Only invoices in DRAFT status can be updated — any other status returns 400. If the incoming status is INVOICED or SENT, the invoice is booked into KLARA accounting and inventory transactions are created, identical to the booking behavior of POST /core/v1/invoices. This is the call that finalizes a DRAFT — the GUI equivalent of posting in the final step; status is caller-controlled, so keep it DRAFT to re-save without booking. This endpoint does not send/deliver the invoice (no email/ePost/eBill/print&send), regardless of postMethod; retrieve the PDF via POST /core/v1/invoices/{id}/printed-document and deliver it yourself. The caller must hold the FINANCE permission on the target company.

Important — finalizing a DRAFT books it without a printed invoice. Setting status=INVOICED/SENT here creates the accounting booking but renders/stores no PDF. To attach the printed invoice to the booking, after this call run (1) POST /core/v1/invoices/{id}/printed-document to render and store the printedFileId, then (2) PUT /core/v1/bookings/{id}/documents to link that printedFileId (in documentIds) to the booking from bookingNumbers.
Required permission

FINANCE

Parameters 1
NameDescription
confirmDontMindClosingFiscalYear
query boolean
When true, allows save/booking even if the document date falls inside a closing or closed fiscal year. Defaults to false.
default: false example: False
Request body required
Updates an existing DRAFT invoice. The body structure is identical to POST /core/v1/invoices with one critical difference: id must be the numeric primary key of an existing invoice currently in DRAFT status.

Typical flow:
  1. Call POST /core/v1/invoices with status=DRAFT to create the invoice.
  2. Call GET /core/v1/invoices/{id} to retrieve the current state.
  3. Modify the desired fields (items, amounts, dates, etc.).
  4. Call this endpoint to update — or to book it by changing status to INVOICED/SENT.
Prerequisite APIs (call these first if modifying related data):
  • GET /core/v1/invoices/{id} → provides the current invoice body to modify and re-submit.
  • GET /core/v1/company-bank-accounts → provides updated ibanNumberCHF / ibanNumberCHW.
  • GET /core/latest/articles/search?keyword=... → search for articles to add/change order items.
  • GET /core/v1/bank-reconciliation/open-positions → provides openPositionsLinkedToInvoice[] for reconciliation.
  • GET /core/latest/company-configuration/including-vat → provides usingVAT default.

Key differences from POST (create):
  • id (long, required) — must be > 0 and match an existing DRAFT invoice. Returns 400 if the stored invoice is not in DRAFT status.
  • invoiceCode — uniqueness is NOT re-validated; retain the original value.
  • order.id — must match the existing order; retain from the original invoice.
  • status — set to INVOICED or SENT to book the invoice (triggers accounting); set to DRAFT to save without booking.

Top-level fields:
  • id (long, required) — must be > 0 (existing DRAFT invoice id).
  • invoiceCode (String, required) — must not be empty; retain the original value.
  • orderType (String, required) — must be INVOICE.
  • status (String, required) — DRAFT (saves without booking), INVOICED (saves and books into accounting), SENT (saves and books; does not send/deliver the invoice).
  • postMethod (String, optional) — distribution channel recorded on the invoice only; not delivered. Allowed: A_POST, B_POST, SEND_EMAIL, PRINT_AND_MANUAL_SEND, EPOST, EBILL.
  • documentDate (date, required) — invoice issue date, format yyyy-MM-dd; must fall inside the active subscription period.
  • paymentDate (date, required when amount > 0) — must be on or after documentDate.
  • ibanNumberCHF (String, conditional) — CHF IBAN; format validated when provided.
  • ibanNumberCHW (String, optional) — WIR IBAN; format validated when provided.
  • wirAcceptanceRate (int, optional) — WIR acceptance percentage (0–100).
  • amount (BigDecimal, required) — total invoice amount. Caller-supplied; not recomputed by the server.
  • usingVAT (boolean) — GUI checkbox "VAT included in amount of each item": item price/amount are VAT-inclusive (true, gross) or VAT-exclusive (false, net). It does not switch VAT on/off. Same VAT-handling rules as POST /core/v1/invoices (server stores amounts verbatim).
  • usingExportVat (boolean, optional) — GUI checkbox "Export"; when true set every orderItems[].vat.rate to 0. Defaults to false.
  • subject, ourReference, yourReference, companyCityAndDate, closeAndSignature — optional text fields.

Nested fields — order (required):
  • order.id (long) — must be the existing order id; retain from the original invoice.
  • order.orderNumber (int) — retain from the original invoice.
  • order.companyId (long) — must match the authenticated company; set from bearer token on the downstream.
  • order.customer (object, required) — existing customer; retain from original invoice.

Nested fields — orderItems[] (required, at least 1):
  • Same structure as POST /core/v1/invoices. Existing item ids (> 0) update items in-place; id = 0 adds new items.
  • orderItems[].tag (String, required when booking) — must not be empty when status is INVOICED/SENT.

Nested fields — attachments[] and openPositionsLinkedToInvoice[]:
  • Same structure and semantics as POST /core/v1/invoices.

Validation rules:
  • id must be > 0 (adapter guard) and the stored invoice must be DRAFT (downstream guard).
  • paymentDate must be on or after documentDate when amount > 0.
  • IBAN format is validated when provided.
  • Each orderItems[].tag must be present when status triggers booking (INVOICED/SENT).
  • Subscription for Order Management must be active for documentDate.

Server-managed fields (same as POST): vatDate, lastModified, createDate, bookingDueDate, bookingNumbers, businessCaseId, bookingStatus, bookingMessage, bookingSealed.

application/json Invoice

  • id integer (int64) format: int64 example: 0
    Invoice id. Must be 0 or omitted when creating a new invoice. This endpoint only supports creation; updating an existing invoice is not supported.
  • orderType string default: INVOICE example: INVOICE
    Polymorphic discriminator. Must be INVOICE. Allowed values: INVOICE.
  • status string example: INVOICED
    Invoice status. Allowed values: DRAFT, INVOICED, SENT, PAID, CANCELLED. Required. Status INVOICED or SENT triggers accounting booking.
  • invoiceCode string required maxLength: 64 pattern: \S example: INV-2026-001
    Human-readable invoice code. Required and unique per company.
  • invoiceNumber integer (int64) format: int64 example: 2026001
    Sequential invoice number, typically obtained from GET /invoices/next-invoice-number.
  • documentDate string (date) format: date example: 2026-05-28
    Invoice document date (ISO 8601). Required when amount is greater than 0. Must fall inside the company's active Order Management subscription period.
  • paymentDate string (date) format: date example: 2026-06-27
    Payment due date (ISO 8601). Required when amount is greater than 0. Must be on or after documentDate.
  • deliveryDate string (date) format: date example: 2026-05-25
    Service delivery date (ISO 8601).
  • issuedDate string (date) format: date example: 2026-05-28
    Date the invoice was issued (ISO 8601).
  • servicePeriodFrom string (date) format: date example: 2026-05-01
    Service period start date (ISO 8601).
  • servicePeriodTo string (date) format: date example: 2026-05-31
    Service period end date (ISO 8601).
  • servicePeriodPattern string maxLength: 32 example: MONTHLY
    Service period pattern label (e.g. MONTHLY, YEARLY).
  • vatDate string (date) format: date
    VAT date. Server-managed (read-only).
  • bookingDueDate string (date) format: date
    Booking due date returned by accounting. Server-managed (read-only).
  • lastModified string (date-time) format: date-time
    Last modification timestamp. Server-managed (read-only).
  • createDate string (date-time) format: date-time
    Creation timestamp. Server-managed (read-only).
  • amount number example: 1080
    Invoice total. When usingVAT=false (VAT-exclusive items) this is the gross total = net + VAT; when usingVAT=true (VAT-inclusive items) it is the sum of the gross item amounts (VAT already inside). Caller-supplied — the server does not recompute it.
  • usingVAT boolean default: false example: True
    Controls whether each item price/amount is VAT-inclusive (gross) or VAT-exclusive (net). This is the GUI checkbox "VAT included in amount of each item". true = amounts already include VAT (INCLUDE_VAT); false = 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 GET /core/latest/company-configuration/including-vat for the company default. The server stores the amounts you send verbatim and does not recompute them from this flag — send price/amount consistent with the chosen mode (see the create operation's VAT-handling notes).
  • usingExportVat boolean default: false example: False
    Export invoice flag — the GUI "Export" checkbox. When true, the invoice is treated as an export: every orderItems[].vat.rate must be 0 (export/zero VAT code), so no VAT is charged. When false (default) the items' normal VAT rates apply. The server does not recompute item VAT from this flag — set the per-item VAT accordingly.
  • subject string maxLength: 1024 example: Invoice 2026-001
    Free-text invoice subject.
  • closeAndSignature string maxLength: 4096 example: Thank you for your business.
    Free-text closing remarks / signature block.
  • ourReference string maxLength: 128 example: ACC-2026
    Internal sender reference.
  • yourReference string maxLength: 128 example: PO-9981
    Customer-side reference (e.g. PO number).
  • companyCityAndDate string maxLength: 256 example: Zurich, 28.05.2026
    Header line such as 'Zurich, 28.05.2026'.
  • postMethod string example: SEND_EMAIL
    Distribution channel recorded on the invoice. Stored only — creating an invoice does not deliver it (no email/ePost/eBill/print&send). Allowed values: A_POST, B_POST, SEND_EMAIL, PRINT_AND_MANUAL_SEND, EPOST, EBILL.
  • delivery string maxLength: 64 example: DHL
    Delivery method label (free text).
  • ibanNumberCHF string example: CH9300762011623852957
    CHF IBAN for payment. Validated by downstream service.
  • ibanNumberCHW string example: CH9300762011623852957
    WIR-franc IBAN for payment.
  • wirAcceptanceRate number example: 0
    WIR acceptance percentage.
  • referenceNumber string maxLength: 64 example: 21 00000 00003 13947 14300 09017
    QR / ISR reference number.
  • qrInvoice boolean default: false example: True
    When true, the invoice is rendered/booked as a Swiss QR-invoice. Defaults to false.
  • fromAutoInvoicing boolean default: false example: False
    Indicates the invoice was generated by auto-invoicing. Defaults to false.
  • fromInvoiceRun boolean default: false example: False
    Indicates the invoice was produced by a recurring invoice run. When true, accounting booking and inventory transactions are skipped. Defaults to false.
  • invoiceType string example: MANUAL
    Invoice type. Allowed values: MANUAL, CREDIT_DEBIT.
  • originDistributionMethod string example: SEND_EMAIL
    Origin distribution method. Allowed values: A_POST, B_POST, SEND_EMAIL, PRINT_AND_MANUAL_SEND, EPOST, EBILL.
  • templateId integer (int64) format: int64 example: 0
    Template id used to create this invoice.
  • runHistoryId integer (int64) format: int64 example: 0
    Recurring invoice run history id.
  • settledAmount number example: 0
    Klara-Pay settled amount (online shop only).
  • bookingNumbers string
    Accounting booking-number string. Server-managed (read-only).
  • businessCaseId integer (int64) format: int64
    Accounting business case id. Server-managed (read-only).
  • bookingStatus string
    Booking status (e.g. OPEN, PARTIAL, PAID). Server-managed (read-only).
  • bookingMessage string
    Optional booking error/info code (e.g. INVALID_SUBSCRIPTION_FOR_ACCOUNTING). 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).
Responses 7
200 Invoice updated successfully. show body

application/json Invoice

  • id integer (int64) format: int64 example: 0
    Invoice id. Must be 0 or omitted when creating a new invoice. This endpoint only supports creation; updating an existing invoice is not supported.
  • orderType string default: INVOICE example: INVOICE
    Polymorphic discriminator. Must be INVOICE. Allowed values: INVOICE.
  • status string example: INVOICED
    Invoice status. Allowed values: DRAFT, INVOICED, SENT, PAID, CANCELLED. Required. Status INVOICED or SENT triggers accounting booking.
  • invoiceCode string required maxLength: 64 pattern: \S example: INV-2026-001
    Human-readable invoice code. Required and unique per company.
  • invoiceNumber integer (int64) format: int64 example: 2026001
    Sequential invoice number, typically obtained from GET /invoices/next-invoice-number.
  • documentDate string (date) format: date example: 2026-05-28
    Invoice document date (ISO 8601). Required when amount is greater than 0. Must fall inside the company's active Order Management subscription period.
  • paymentDate string (date) format: date example: 2026-06-27
    Payment due date (ISO 8601). Required when amount is greater than 0. Must be on or after documentDate.
  • deliveryDate string (date) format: date example: 2026-05-25
    Service delivery date (ISO 8601).
  • issuedDate string (date) format: date example: 2026-05-28
    Date the invoice was issued (ISO 8601).
  • servicePeriodFrom string (date) format: date example: 2026-05-01
    Service period start date (ISO 8601).
  • servicePeriodTo string (date) format: date example: 2026-05-31
    Service period end date (ISO 8601).
  • servicePeriodPattern string maxLength: 32 example: MONTHLY
    Service period pattern label (e.g. MONTHLY, YEARLY).
  • vatDate string (date) format: date
    VAT date. Server-managed (read-only).
  • bookingDueDate string (date) format: date
    Booking due date returned by accounting. Server-managed (read-only).
  • lastModified string (date-time) format: date-time
    Last modification timestamp. Server-managed (read-only).
  • createDate string (date-time) format: date-time
    Creation timestamp. Server-managed (read-only).
  • amount number example: 1080
    Invoice total. When usingVAT=false (VAT-exclusive items) this is the gross total = net + VAT; when usingVAT=true (VAT-inclusive items) it is the sum of the gross item amounts (VAT already inside). Caller-supplied — the server does not recompute it.
  • usingVAT boolean default: false example: True
    Controls whether each item price/amount is VAT-inclusive (gross) or VAT-exclusive (net). This is the GUI checkbox "VAT included in amount of each item". true = amounts already include VAT (INCLUDE_VAT); false = 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 GET /core/latest/company-configuration/including-vat for the company default. The server stores the amounts you send verbatim and does not recompute them from this flag — send price/amount consistent with the chosen mode (see the create operation's VAT-handling notes).
  • usingExportVat boolean default: false example: False
    Export invoice flag — the GUI "Export" checkbox. When true, the invoice is treated as an export: every orderItems[].vat.rate must be 0 (export/zero VAT code), so no VAT is charged. When false (default) the items' normal VAT rates apply. The server does not recompute item VAT from this flag — set the per-item VAT accordingly.
  • subject string maxLength: 1024 example: Invoice 2026-001
    Free-text invoice subject.
  • closeAndSignature string maxLength: 4096 example: Thank you for your business.
    Free-text closing remarks / signature block.
  • ourReference string maxLength: 128 example: ACC-2026
    Internal sender reference.
  • yourReference string maxLength: 128 example: PO-9981
    Customer-side reference (e.g. PO number).
  • companyCityAndDate string maxLength: 256 example: Zurich, 28.05.2026
    Header line such as 'Zurich, 28.05.2026'.
  • postMethod string example: SEND_EMAIL
    Distribution channel recorded on the invoice. Stored only — creating an invoice does not deliver it (no email/ePost/eBill/print&send). Allowed values: A_POST, B_POST, SEND_EMAIL, PRINT_AND_MANUAL_SEND, EPOST, EBILL.
  • delivery string maxLength: 64 example: DHL
    Delivery method label (free text).
  • ibanNumberCHF string example: CH9300762011623852957
    CHF IBAN for payment. Validated by downstream service.
  • ibanNumberCHW string example: CH9300762011623852957
    WIR-franc IBAN for payment.
  • wirAcceptanceRate number example: 0
    WIR acceptance percentage.
  • referenceNumber string maxLength: 64 example: 21 00000 00003 13947 14300 09017
    QR / ISR reference number.
  • qrInvoice boolean default: false example: True
    When true, the invoice is rendered/booked as a Swiss QR-invoice. Defaults to false.
  • fromAutoInvoicing boolean default: false example: False
    Indicates the invoice was generated by auto-invoicing. Defaults to false.
  • fromInvoiceRun boolean default: false example: False
    Indicates the invoice was produced by a recurring invoice run. When true, accounting booking and inventory transactions are skipped. Defaults to false.
  • invoiceType string example: MANUAL
    Invoice type. Allowed values: MANUAL, CREDIT_DEBIT.
  • originDistributionMethod string example: SEND_EMAIL
    Origin distribution method. Allowed values: A_POST, B_POST, SEND_EMAIL, PRINT_AND_MANUAL_SEND, EPOST, EBILL.
  • templateId integer (int64) format: int64 example: 0
    Template id used to create this invoice.
  • runHistoryId integer (int64) format: int64 example: 0
    Recurring invoice run history id.
  • settledAmount number example: 0
    Klara-Pay settled amount (online shop only).
  • bookingNumbers string
    Accounting booking-number string. Server-managed (read-only).
  • businessCaseId integer (int64) format: int64
    Accounting business case id. Server-managed (read-only).
  • bookingStatus string
    Booking status (e.g. OPEN, PARTIAL, PAID). Server-managed (read-only).
  • bookingMessage string
    Optional booking error/info code (e.g. INVALID_SUBSCRIPTION_FOR_ACCOUNTING). 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).
400 Data invalid show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found no response body
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. no response body
GET/core/v1/invoices/next-invoice-numberkey / tokenGet the next available invoice number for the authenticated company.
Returns the next available invoice number for the company resolved from the bearer JWT. The caller must hold the FINANCE permission on the target company. This operation is NOT idempotent — each successful call advances the persisted next-invoice-number counter on luzfin_finance, so the returned value is reserved and will not be returned again. Do not retry on success.
Required permission

FINANCE

Responses 6
200 Next available invoice number returned. show body

application/json NextInvoiceNumberResponse

  • nextInvoiceNumber integer (int64) format: int64 example: 2026001
    The next available invoice number reserved for the authenticated company. Each successful call advances the persisted counter; the value is therefore unique per call.
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found no response body
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. no response body
GET/core/v1/invoices/{id}key / tokenGet a single invoice by its numeric id.
Returns the fully-enriched invoice document for the given id under the company resolved from the bearer JWT. The response includes order items enriched with inventory selection data and accounting booking-status fields (bookingStatus, bookingDueDate, bookingSealed) populated by luz_accounting. The caller must hold the FINANCE permission on the target company.
Required permission

FINANCE

Parameters 1
NameDescription
id required
path integer
Numeric primary key of the invoice to retrieve. Obtain this from the id field of a previously created invoice (POST /core/v1/invoices).
example: 42
Responses 6
200 Invoice found and returned. show body

application/json Invoice

  • id integer (int64) format: int64 example: 0
    Invoice id. Must be 0 or omitted when creating a new invoice. This endpoint only supports creation; updating an existing invoice is not supported.
  • orderType string default: INVOICE example: INVOICE
    Polymorphic discriminator. Must be INVOICE. Allowed values: INVOICE.
  • status string example: INVOICED
    Invoice status. Allowed values: DRAFT, INVOICED, SENT, PAID, CANCELLED. Required. Status INVOICED or SENT triggers accounting booking.
  • invoiceCode string required maxLength: 64 pattern: \S example: INV-2026-001
    Human-readable invoice code. Required and unique per company.
  • invoiceNumber integer (int64) format: int64 example: 2026001
    Sequential invoice number, typically obtained from GET /invoices/next-invoice-number.
  • documentDate string (date) format: date example: 2026-05-28
    Invoice document date (ISO 8601). Required when amount is greater than 0. Must fall inside the company's active Order Management subscription period.
  • paymentDate string (date) format: date example: 2026-06-27
    Payment due date (ISO 8601). Required when amount is greater than 0. Must be on or after documentDate.
  • deliveryDate string (date) format: date example: 2026-05-25
    Service delivery date (ISO 8601).
  • issuedDate string (date) format: date example: 2026-05-28
    Date the invoice was issued (ISO 8601).
  • servicePeriodFrom string (date) format: date example: 2026-05-01
    Service period start date (ISO 8601).
  • servicePeriodTo string (date) format: date example: 2026-05-31
    Service period end date (ISO 8601).
  • servicePeriodPattern string maxLength: 32 example: MONTHLY
    Service period pattern label (e.g. MONTHLY, YEARLY).
  • vatDate string (date) format: date
    VAT date. Server-managed (read-only).
  • bookingDueDate string (date) format: date
    Booking due date returned by accounting. Server-managed (read-only).
  • lastModified string (date-time) format: date-time
    Last modification timestamp. Server-managed (read-only).
  • createDate string (date-time) format: date-time
    Creation timestamp. Server-managed (read-only).
  • amount number example: 1080
    Invoice total. When usingVAT=false (VAT-exclusive items) this is the gross total = net + VAT; when usingVAT=true (VAT-inclusive items) it is the sum of the gross item amounts (VAT already inside). Caller-supplied — the server does not recompute it.
  • usingVAT boolean default: false example: True
    Controls whether each item price/amount is VAT-inclusive (gross) or VAT-exclusive (net). This is the GUI checkbox "VAT included in amount of each item". true = amounts already include VAT (INCLUDE_VAT); false = 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 GET /core/latest/company-configuration/including-vat for the company default. The server stores the amounts you send verbatim and does not recompute them from this flag — send price/amount consistent with the chosen mode (see the create operation's VAT-handling notes).
  • usingExportVat boolean default: false example: False
    Export invoice flag — the GUI "Export" checkbox. When true, the invoice is treated as an export: every orderItems[].vat.rate must be 0 (export/zero VAT code), so no VAT is charged. When false (default) the items' normal VAT rates apply. The server does not recompute item VAT from this flag — set the per-item VAT accordingly.
  • subject string maxLength: 1024 example: Invoice 2026-001
    Free-text invoice subject.
  • closeAndSignature string maxLength: 4096 example: Thank you for your business.
    Free-text closing remarks / signature block.
  • ourReference string maxLength: 128 example: ACC-2026
    Internal sender reference.
  • yourReference string maxLength: 128 example: PO-9981
    Customer-side reference (e.g. PO number).
  • companyCityAndDate string maxLength: 256 example: Zurich, 28.05.2026
    Header line such as 'Zurich, 28.05.2026'.
  • postMethod string example: SEND_EMAIL
    Distribution channel recorded on the invoice. Stored only — creating an invoice does not deliver it (no email/ePost/eBill/print&send). Allowed values: A_POST, B_POST, SEND_EMAIL, PRINT_AND_MANUAL_SEND, EPOST, EBILL.
  • delivery string maxLength: 64 example: DHL
    Delivery method label (free text).
  • ibanNumberCHF string example: CH9300762011623852957
    CHF IBAN for payment. Validated by downstream service.
  • ibanNumberCHW string example: CH9300762011623852957
    WIR-franc IBAN for payment.
  • wirAcceptanceRate number example: 0
    WIR acceptance percentage.
  • referenceNumber string maxLength: 64 example: 21 00000 00003 13947 14300 09017
    QR / ISR reference number.
  • qrInvoice boolean default: false example: True
    When true, the invoice is rendered/booked as a Swiss QR-invoice. Defaults to false.
  • fromAutoInvoicing boolean default: false example: False
    Indicates the invoice was generated by auto-invoicing. Defaults to false.
  • fromInvoiceRun boolean default: false example: False
    Indicates the invoice was produced by a recurring invoice run. When true, accounting booking and inventory transactions are skipped. Defaults to false.
  • invoiceType string example: MANUAL
    Invoice type. Allowed values: MANUAL, CREDIT_DEBIT.
  • originDistributionMethod string example: SEND_EMAIL
    Origin distribution method. Allowed values: A_POST, B_POST, SEND_EMAIL, PRINT_AND_MANUAL_SEND, EPOST, EBILL.
  • templateId integer (int64) format: int64 example: 0
    Template id used to create this invoice.
  • runHistoryId integer (int64) format: int64 example: 0
    Recurring invoice run history id.
  • settledAmount number example: 0
    Klara-Pay settled amount (online shop only).
  • bookingNumbers string
    Accounting booking-number string. Server-managed (read-only).
  • businessCaseId integer (int64) format: int64
    Accounting business case id. Server-managed (read-only).
  • bookingStatus string
    Booking status (e.g. OPEN, PARTIAL, PAID). Server-managed (read-only).
  • bookingMessage string
    Optional booking error/info code (e.g. INVALID_SUBSCRIPTION_FOR_ACCOUNTING). 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).
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 No invoice with the given id exists for the authenticated company. no response body
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
POST/core/v1/invoices/{id}/printed-documentkey / tokenReturn the invoice as a PDF (rendering it if needed).
Returns the invoice document as a binary application/pdf stream via the internal Klara printing pipeline (luz_web + Aspose Words), mirroring the behaviour of the Klara GUI. The caller must hold the FINANCE permission on the target company.

Reuse vs. render (mirrors the Klara GUI): if the invoice was already printed, the previously rendered PDF is fetched from storage and returned as-is; if it was not yet printed, it is rendered now and the printedFileId is stored on the invoice record. In both cases the response body is the binary PDF with a Content-Disposition: attachment header containing the suggested filename. This is a POST (not GET) because the first print persists the printedFileId.
Required permission

FINANCE

Parameters 1
NameDescription
id required
path integer
ID of the invoice to return as PDF. Must belong to the company resolved from the bearer JWT.
example: 42
Responses 6
200 Invoice PDF returned as a binary application/pdf stream with a Content-Disposition: attachment header — either freshly rendered (first print) or the previously stored PDF (already printed). show body

application/pdf any

401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Invoice not found. no response body
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. no response body
POST/core/v1/invoices/{id}/sendkey / tokenSend a booked invoice (smart delivery or a forced channel).
Sends an already-booked invoice to its recipient, synchronously, under the company resolved from the bearer JWT.

Omit channel for smart delivery: the system auto-routes through EPOST, EBILL, SEND_EMAIL and Print&Send and only fails if none can deliver. Provide channel to force that exact channel: if the recipient is not eligible (e.g. no email on file, not eBill-registered, Print&Send not subscribed) the call fails with 400. The invoice PDF is rendered on demand when it has not been printed yet.

Prerequisites: the invoice must already be booked — DRAFT and cancelled invoices are rejected with 400. Create/book it via POST /core/v1/invoices (status=INVOICED) first.

Not idempotent: each successful call performs a real delivery (sends an email / hands a letter to the postal channel) and overwrites the invoice's recorded post method — do not retry blindly on success.

channel uses the same values as Invoice.postMethod, except PRINT_AND_MANUAL_SEND, which is not a deliverable channel and is rejected with 400. Authentication is API key + bearer JWT; the caller must hold the FINANCE permission on the target company.
Required permission

FINANCE

Parameters 2
NameDescription
id required
path integer
Numeric primary key of the booked invoice to send. Must belong to the company resolved from the bearer JWT. Obtain it from the id of a previously created invoice (POST /core/v1/invoices).
example: 42
channel
query string
Forced distribution channel. Leave empty for smart delivery (auto-routing) — the default is no forced channel. Allowed values: EPOST, EBILL, SEND_EMAIL, A_POST, B_POST. PRINT_AND_MANUAL_SEND is rejected with 400 (not a deliverable channel).
Allowed values: A_POST, B_POST, SEND_EMAIL, PRINT_AND_MANUAL_SEND, EPOST, EBILL
Responses 7
200 Invoice delivered. Returns the channel actually used, whether it was smart-routed, the OneAPI delivery id and the archived PDF's printedFileId. show body

application/json SendInvoiceResult

  • delivered boolean example: True
    true when delivery was confirmed via the channel actually used.
  • smart boolean example: True
    true when the channel was auto-selected (smart delivery, i.e. no channel was forced); false when a channel was forced.
  • channel object example: SEND_EMAIL
    The channel actually used to deliver the invoice. For physical post this is the resolved postage method (e.g. A_POST).
    Allowed values: A_POST, B_POST, SEND_EMAIL, PRINT_AND_MANUAL_SEND, EPOST, EBILL
  • deliveryId string example: 9b1f4c8e-2d3a-4f6b-8c7d-1e2f3a4b5c6d
    OneAPI delivery id, when available (forced sends only; null for smart delivery).
  • printedFileId string example: 1771764
    The printedFileId of the archived invoice PDF rendered/reused during the send.
400 Invoice is DRAFT/cancelled, the channel is unsupported (PRINT_AND_MANUAL_SEND), the recipient is not eligible for the forced channel, or smart delivery found no channel. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 No invoice with the given id exists for the authenticated company. no response body
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/order-documents/filter/type-and-order-numberkey / tokenList order-management documents by type and order number.
Returns every order-management document of the company resolved from the bearer JWT that has the given type and business order-number. Used to discover sibling documents on the same order chain (e.g. find the DELIVERY_NOTEs for an order number before creating an INVOICE from them). The caller must hold the FINANCE permission on the target company. This operation is idempotent and read-only — it can be safely retried.
Required permission

FINANCE

Parameters 2
NameDescription
order-number required
query integer
Business order number shared by all documents in the same order chain (e.g. the order.orderNumber returned by POST /core/v1/invoices). Exact match. Required.
example: 377
type required
query string
Order-document type to filter by. Allowed values: OFFER, CONFIRMATION, DELIVERY_NOTE, INVOICE, CREDIT_NOTE, FRIENDLY_REMINDER, FIRST_REMINDER, SECOND_REMINDER, PAYSLIP, RECURRING_INVOICE_TEMPLATE. Required.
Allowed values: OFFER, CONFIRMATION, DELIVERY_NOTE, INVOICE, CREDIT_NOTE, FRIENDLY_REMINDER, FIRST_REMINDER, SECOND_REMINDER, PAYSLIP, RECURRING_INVOICE_TEMPLATE
example: DELIVERY_NOTE
Responses 6
200 Matching order-management documents. show body

application/json array of OrderDocument

Array of OrderDocument.

  • id integer (int64) format: int64 example: 1234
    Document id (database primary key).
  • orderType string example: DELIVERY_NOTE
    Polymorphic discriminator. Allowed values: OFFER, CONFIRMATION, DELIVERY_NOTE, INVOICE, CREDIT_NOTE, FRIENDLY_REMINDER, FIRST_REMINDER, SECOND_REMINDER, PAYSLIP, RECURRING_INVOICE_TEMPLATE.
  • status string example: SENT
    Document status (subtype-specific). For invoices: DRAFT, INVOICED, SENT, PAID, CANCELLED.
  • documentDate string (date) format: date example: 2026-05-28
    Document creation/business date (ISO 8601).
  • issuedDate string (date) format: date example: 2026-05-28
    Date the document was issued (ISO 8601).
  • amount number example: 500
    Document gross total (incl. VAT when applicable).
  • ourReference string example: ACC-2026
    Internal sender reference.
  • yourReference string example: PO-9981
    Customer-side reference (e.g. PO number).
  • subject string example: Delivery note 377
    Free-text document subject.
  • closeAndSignature string example: Thank you for your business.
    Free-text closing remarks / signature block.
  • companyCityAndDate string example: Zurich, 28.05.2026
    Header line such as 'Zurich, 28.05.2026'.
  • usingVAT boolean default: false example: True
    Whether VAT is applied on this document.
  • vatDate string (date) format: date
    VAT date. Server-managed (read-only).
  • printedFileId string example: 1771764
    Document file id of the rendered PDF (if any).
400 Data invalid show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. no response body
GET/core/v1/order-documents/{order-type}/next-document-numberkey / tokenGet the next document number for a given order-document type.
Returns the next available sequence number and its formatted document code for the authenticated company and the given order-type. Use the returned documentCode as invoiceCode / offerCode when subsequently creating a document with POST /core/v1/invoices. Side effect for INVOICE: the persisted counter is advanced on every call — do not call speculatively. Only meaningful for OFFER, CONFIRMATION, DELIVERY_NOTE, and INVOICE; other types always return documentNumber = 0. If the company has configured MANUAL numbering for the requested type, the downstream service returns HTTP 500 — check GET /core/v1/order-numbering-configurations first. The caller must hold the FINANCE permission on the target company.
Required permission

FINANCE

Parameters 1
NameDescription
order-type required
path string
Order-document type whose counter to advance. Meaningful values: OFFER, CONFIRMATION, DELIVERY_NOTE, INVOICE. Other enum values (CREDIT_NOTE, FRIENDLY_REMINDER, FIRST_REMINDER, SECOND_REMINDER, PAYSLIP, RECURRING_INVOICE_TEMPLATE) are accepted but always return documentNumber = 0. An invalid value returns HTTP 400.
Allowed values: OFFER, CONFIRMATION, DELIVERY_NOTE, INVOICE, CREDIT_NOTE, FRIENDLY_REMINDER, FIRST_REMINDER, SECOND_REMINDER, PAYSLIP, RECURRING_INVOICE_TEMPLATE
example: INVOICE
Responses 6
200 Next document number and formatted code for the requested order type. show body

application/json OrderNumberingResult

  • orderType object example: INVOICE
    Order-management document type. Used as the discriminator on OrderDocument.orderType.
  • orderNumberingType object example: STANDARD
    Strategy used to assign document numbers for an order type. STANDARD — server auto-increments; MANUAL — caller supplies the number; CUSTOMISED — caller supplies a formatted code matching the configured pattern.
  • startingNumber integer (int64) format: int64 example: 1000
    Starting sequence number for STANDARD and CUSTOMISED strategies.
  • increment integer (int64) format: int64 example: 1
    Step size between successive auto-incremented numbers.
  • format string example: INV-2026-
    Alphanumeric prefix for CUSTOMISED numbering (the server appends the sequence number).
  • documentNumber integer (int64) format: int64 example: 1001
    The next document number to use (the sequence integer). For INVOICE this counter is persisted on every call — do not call speculatively.
  • documentCode string example: 1001
    The next document code to use as invoiceCode / offerCode. For STANDARD and MANUAL this equals String.valueOf(documentNumber); for CUSTOMISED it equals format + documentNumber (e.g. "INV-2026-1001").
400 Data invalid show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/order-numbering-configurationskey / tokenGet the order-numbering configuration for a document type.
Returns the numbering strategy configured for the given order-type of the company resolved from the bearer JWT. Use this before creating a document to decide how to supply the document number in POST /core/v1/invoices: STANDARD — server auto-assigns; MANUAL — set invoiceCode yourself; CUSTOMISED — set invoiceCode to a value matching the returned format pattern. If no configuration has been saved by the company administrator, a default STANDARD configuration is returned. The caller must hold the FINANCE permission on the target company. This operation is idempotent and read-only.
Required permission

FINANCE

Parameters 1
NameDescription
order-type
query string
Document type to retrieve the numbering configuration for. Allowed values: OFFER, CONFIRMATION, DELIVERY_NOTE, INVOICE, CREDIT_NOTE, FRIENDLY_REMINDER, FIRST_REMINDER, SECOND_REMINDER, PAYSLIP, RECURRING_INVOICE_TEMPLATE. Recommended — omitting it returns a generic default with a null orderType field.
Allowed values: OFFER, CONFIRMATION, DELIVERY_NOTE, INVOICE, CREDIT_NOTE, FRIENDLY_REMINDER, FIRST_REMINDER, SECOND_REMINDER, PAYSLIP, RECURRING_INVOICE_TEMPLATE
example: INVOICE
Responses 6
200 Numbering configuration for the requested document type. show body

application/json OrderNumberingConfiguration

  • orderType object example: INVOICE
    Order-management document type. Used as the discriminator on OrderDocument.orderType.
  • orderNumberingType object example: STANDARD
    Strategy used to assign document numbers for an order type. STANDARD — server auto-increments; MANUAL — caller supplies the number; CUSTOMISED — caller supplies a formatted code matching the configured pattern.
  • startingNumber integer (int64) format: int64 example: 1000
    The first number in the auto-increment sequence (relevant for STANDARD). Null when not configured.
  • increment integer (int64) format: int64 example: 1
    Step size between successive auto-incremented numbers (relevant for STANDARD). Null when not configured.
  • format string example: INV-2026-{SEQ}
    Alphanumeric format pattern for CUSTOMISED numbering (e.g. INV-{YYYY}-{SEQ}). Null when not configured.
400 Data invalid show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/v1/orders/next-order-numberkey / tokenGet the next available order number for the authenticated company.
Returns the next available business order number for the company resolved from the bearer JWT. Use the returned nextOrderNumber as the orderNumber field when subsequently creating an order. Not idempotent: each call reserves and advances the in-memory counter — call this immediately before creating the order and do not call speculatively. Gaps may appear in the sequence if the subsequent order creation fails. The caller must hold the FINANCE permission on the target company.
Required permission

FINANCE

Responses 5
200 Next available order number for the authenticated company. show body

application/json OrderNextNumberResult

  • nextOrderNumber integer (int32) format: int32 example: 10041
    The next available business order number for the authenticated company. Reserved exclusively for this call — use it as the orderNumber when subsequently creating the order. Gaps may appear in the sequence if the order creation fails after this call.
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated

Sales & Articles

Article28

GET/core/latest/article-categorieskey / tokenGet all categories
Parameters 4
NameDescription
active-status
query boolean
Active status
keyword
query string
Name
limit
query integer (int32)
Limit filters returned
format: int32 min: 1
Accept-Language
header string
Language code is used for filtering by the keyword with multilingual
example: en
Responses 5
200 Return successfully show body

application/json array of ArticleCategory

Array of ArticleCategory.

  • id string read-only example: 1
    Id of the category. Does not need to be included when creating article category
  • nameDE string required example: German name
    Name of the category in German
  • nameEN string example: English name
    Name of the category in English
  • nameFR string example: French name
    Name of the category in French
  • nameIT string example: Italian name
    Name of the category in Italian
  • order integer (int32) format: int32 read-only
    Order of this category.
    Does not need to be included when creating article category.
  • active boolean
    Indicates if the category is active or not
  • imageId string read-only example: 1
    Image Id of the category. Does not need to be included when creating article category
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
400 Data invalid show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
POST/core/latest/article-categorieskey / tokenCreate a new category
Request body

application/json ArticleCategory

  • id string read-only example: 1
    Id of the category. Does not need to be included when creating article category
  • nameDE string required example: German name
    Name of the category in German
  • nameEN string example: English name
    Name of the category in English
  • nameFR string example: French name
    Name of the category in French
  • nameIT string example: Italian name
    Name of the category in Italian
  • order integer (int32) format: int32 read-only
    Order of this category.
    Does not need to be included when creating article category.
  • active boolean
    Indicates if the category is active or not
  • imageId string read-only example: 1
    Image Id of the category. Does not need to be included when creating article category
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
Responses 5
201 Category created show body

application/json ArticleCategory

  • id string read-only example: 1
    Id of the category. Does not need to be included when creating article category
  • nameDE string required example: German name
    Name of the category in German
  • nameEN string example: English name
    Name of the category in English
  • nameFR string example: French name
    Name of the category in French
  • nameIT string example: Italian name
    Name of the category in Italian
  • order integer (int32) format: int32 read-only
    Order of this category.
    Does not need to be included when creating article category.
  • active boolean
    Indicates if the category is active or not
  • imageId string read-only example: 1
    Image Id of the category. Does not need to be included when creating article category
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
400 Data invalid show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
DELETE/core/latest/article-categories/{category-id}key / tokenDelete category by Id
Parameters 1
NameDescription
category-id required
path string
Responses 6
204 Deleted successfully no response body
400 Data invalid show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found no response body
429 API rate limit exceeded no response body
GET/core/latest/article-categories/{category-id}key / tokenGet category by id
Parameters 1
NameDescription
category-id required
path string
Responses 5
200 Return successfully show body

application/json ArticleCategory

  • id string read-only example: 1
    Id of the category. Does not need to be included when creating article category
  • nameDE string required example: German name
    Name of the category in German
  • nameEN string example: English name
    Name of the category in English
  • nameFR string example: French name
    Name of the category in French
  • nameIT string example: Italian name
    Name of the category in Italian
  • order integer (int32) format: int32 read-only
    Order of this category.
    Does not need to be included when creating article category.
  • active boolean
    Indicates if the category is active or not
  • imageId string read-only example: 1
    Image Id of the category. Does not need to be included when creating article category
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found no response body
429 API rate limit exceeded no response body
PUT/core/latest/article-categories/{category-id}key / tokenUpdate category by Id
Parameters 1
NameDescription
category-id required
path string
Request body

application/json ArticleCategory

  • id string read-only example: 1
    Id of the category. Does not need to be included when creating article category
  • nameDE string required example: German name
    Name of the category in German
  • nameEN string example: English name
    Name of the category in English
  • nameFR string example: French name
    Name of the category in French
  • nameIT string example: Italian name
    Name of the category in Italian
  • order integer (int32) format: int32 read-only
    Order of this category.
    Does not need to be included when creating article category.
  • active boolean
    Indicates if the category is active or not
  • imageId string read-only example: 1
    Image Id of the category. Does not need to be included when creating article category
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
Responses 6
200 Updated successfully show body

application/json ArticleCategory

  • id string read-only example: 1
    Id of the category. Does not need to be included when creating article category
  • nameDE string required example: German name
    Name of the category in German
  • nameEN string example: English name
    Name of the category in English
  • nameFR string example: French name
    Name of the category in French
  • nameIT string example: Italian name
    Name of the category in Italian
  • order integer (int32) format: int32 read-only
    Order of this category.
    Does not need to be included when creating article category.
  • active boolean
    Indicates if the category is active or not
  • imageId string read-only example: 1
    Image Id of the category. Does not need to be included when creating article category
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
400 Data invalid show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found no response body
429 API rate limit exceeded no response body
POST/core/latest/article-categories/{category-id}/assign-to-articleskey / tokenAssign category to articles
Assign the specified article category to multiple articles for usage in Online Booking, Online shop, and Point of sale.
Only the articles entered in the request body will have the specified article category added to their respective filters.
Other articles will not be affected
Parameters 1
NameDescription
category-id required
path string
Request body

application/json CategoryAssigningGroup

  • articleIdsForOnlineShop array of string
    Article ids need to be assigned with a online shop category
  • articleIdsForBooking array of string
    Article ids need to be assigned with a booking category
  • articleIdsForPos array of string
    Article ids need to be assigned with a pos category
Responses 6
204 Assigned successfully no response body
400 Data invalid show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found no response body
429 API rate limit exceeded no response body
GET/core/latest/article-filterskey / tokenSearch article filters
Parameters 4
NameDescription
active-status
query boolean
Active status
keyword
query string
Name
limit
query integer (int32)
Limit filters returned
format: int32 min: 1
Accept-Language
header string
Language code is used for filtering by the keyword with multilingual
example: en
Responses 4
200 Filters show body

application/json array of ArticleFilter

Array of ArticleFilter.

  • id string read-only example: 1
    Id of the filter. Does not need to be included when creating article filter
  • nameDE string required example: shop
    Name of the filter in german
  • nameEN string example: shop
    Name of the filter in english
  • nameFR string example: shop
    Name of the filter in french
  • nameIT string example: shop
    Name of the filter in italy
  • order integer (int32) format: int32
    Order of this filter.
    Does not need to be included when creating article filter.
  • active boolean
    Indicates if the filter is active or not
  • imageId string read-only
    The image id of the filter. Does not need to be included when creating article
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
POST/core/latest/article-filterskey / tokenCreate a article filter
Request body required
Filter data

application/json ArticleFilter

  • id string read-only example: 1
    Id of the filter. Does not need to be included when creating article filter
  • nameDE string required example: shop
    Name of the filter in german
  • nameEN string example: shop
    Name of the filter in english
  • nameFR string example: shop
    Name of the filter in french
  • nameIT string example: shop
    Name of the filter in italy
  • order integer (int32) format: int32
    Order of this filter.
    Does not need to be included when creating article filter.
  • active boolean
    Indicates if the filter is active or not
  • imageId string read-only
    The image id of the filter. Does not need to be included when creating article
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
Responses 5
201 Filter created show body

application/json ArticleFilter

  • id string read-only example: 1
    Id of the filter. Does not need to be included when creating article filter
  • nameDE string required example: shop
    Name of the filter in german
  • nameEN string example: shop
    Name of the filter in english
  • nameFR string example: shop
    Name of the filter in french
  • nameIT string example: shop
    Name of the filter in italy
  • order integer (int32) format: int32
    Order of this filter.
    Does not need to be included when creating article filter.
  • active boolean
    Indicates if the filter is active or not
  • imageId string read-only
    The image id of the filter. Does not need to be included when creating article
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
400 Data invalid show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
DELETE/core/latest/article-filters/{filter-id}key / tokenDelete article filter by id
This filter will be removed from all articles
Parameters 1
NameDescription
filter-id required
path string
Responses 5
204 Delete successfully no response body
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found no response body
429 API rate limit exceeded no response body
GET/core/latest/article-filters/{filter-id}key / tokenGet article filter by id
Parameters 1
NameDescription
filter-id required
path string
Responses 5
200 Filter show body

application/json ArticleFilter

  • id string read-only example: 1
    Id of the filter. Does not need to be included when creating article filter
  • nameDE string required example: shop
    Name of the filter in german
  • nameEN string example: shop
    Name of the filter in english
  • nameFR string example: shop
    Name of the filter in french
  • nameIT string example: shop
    Name of the filter in italy
  • order integer (int32) format: int32
    Order of this filter.
    Does not need to be included when creating article filter.
  • active boolean
    Indicates if the filter is active or not
  • imageId string read-only
    The image id of the filter. Does not need to be included when creating article
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found no response body
429 API rate limit exceeded no response body
PUT/core/latest/article-filters/{filter-id}key / tokenUpdate article filter by id
Parameters 1
NameDescription
filter-id required
path string
Request body required
Filter data

application/json ArticleFilter

  • id string read-only example: 1
    Id of the filter. Does not need to be included when creating article filter
  • nameDE string required example: shop
    Name of the filter in german
  • nameEN string example: shop
    Name of the filter in english
  • nameFR string example: shop
    Name of the filter in french
  • nameIT string example: shop
    Name of the filter in italy
  • order integer (int32) format: int32
    Order of this filter.
    Does not need to be included when creating article filter.
  • active boolean
    Indicates if the filter is active or not
  • imageId string read-only
    The image id of the filter. Does not need to be included when creating article
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
Responses 6
200 Update successfully show body

application/json ArticleFilter

  • id string read-only example: 1
    Id of the filter. Does not need to be included when creating article filter
  • nameDE string required example: shop
    Name of the filter in german
  • nameEN string example: shop
    Name of the filter in english
  • nameFR string example: shop
    Name of the filter in french
  • nameIT string example: shop
    Name of the filter in italy
  • order integer (int32) format: int32
    Order of this filter.
    Does not need to be included when creating article filter.
  • active boolean
    Indicates if the filter is active or not
  • imageId string read-only
    The image id of the filter. Does not need to be included when creating article
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
400 Data invalid show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found no response body
429 API rate limit exceeded no response body
POST/core/latest/article-filters/{filter-id}/assign-to-articleskey / tokenAssign filter to articles
Assign the specified article filter to multiple articles for usage in Online Booking, Online shop, and Point of sale.
Only the articles entered in the request body will have the specified article filter added to their respective filters.
Other articles will not be affected
Parameters 1
NameDescription
filter-id required
path string
Request body required
Article ids

application/json FilterAssigningGroup

  • assignedPosArticleIds array of string
    Article ids will have the filter as a pos filter
  • assignedOnlineShopArticleIds array of string
    Article ids will have the filter as a online shop filter
  • assignedBookingArticleIds array of string
    Article ids will have the filter as a booking filter
Responses 6
204 Successfully no response body
400 Data invalid show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found no response body
429 API rate limit exceeded no response body
GET/core/latest/articleskey / tokenReturns article list of a company
Parameters 3
NameDescription
limit
query integer (int32)
Define the limit of the article list that this API returns.
For example, if a company have 20 articles in total, and this limit parameter is 5, and the offset parameter is 0,
then this API will return article list containing the first 5 articles
If not set, then default value of 48 is used
format: int32 min: 1 max: 1000 default: 48
offset
query integer (int32)
Define which position to start getting article list.
For example, if a company have 20 articles in total, and this offset parameter is 5,
then this API will return article list from the 5th article.
If not set, then default value of 0 is used
format: int32 min: 0 default: 0
product-type
query string
Filter articles with this product type.
Allowed values: SERVICE, PRODUCTION, TRADE, OTHER, GIFT_CARD, PREPAYMENT
Responses 4
200 Articles show body

application/json array of Article

Array of Article.

  • id string read-only example: 1
    Id of the article. Does not need to be included when creating article
  • nameDE string required
    Name of the article in German
  • nameEN string
    Name of the article in English
  • nameFR string
    Name of the article in French
  • nameIT string
    Name of the article in Italian
  • descriptionDE string
    Description of the article in German
  • descriptionEN string
    Description of the article in English
  • descriptionFR string
    Description of the article in French
  • descriptionIT string
    Description of the article in Italian
  • extendedDescriptionDE string
    Extended description of the article in German
  • extendedDescriptionEN string
    Extended description of the article in English
  • extendedDescriptionFR string
    Extended description of the article in French
  • extendedDescriptionIT string
    Extended description of the article in Italian
  • unitDE string required
    Unit of the article in German
  • unitEN string
    Unit of the article in English
  • unitFR string
    Unit of the article in French
  • unitIT string
    Unit of the article in Italian
  • barcode string
    Barcode of the article
  • usePos boolean
    Decides if this article is used for POS or not
  • pricePeriods array of PricePeriod
    Price periods for the article.
    If article only has single price period, ignore and don't include validFrom and validTo in the PricePeriod.
    If article have different prices valid for different periods, set value for validFrom for each price period or that price period is ignored.
    show fields

    Array of PricePeriod.

    • validFrom string (date) format: date
      The price period is valid from this time
    • validTo string (date) format: date read-only
      The price period is invalid after this time
    • price number pattern: ^\d{1,19}([.]\d{1,2})?$
      The price used for an article within this price period
    • priceCategories array of PriceCategory
      List of price categories effective for this price period
      show fields

      Array of PriceCategory.

      • name string
        Name of the price category
      • price number pattern: ^\d{1,19}([.]\d{1,2})?$
        Effective price of this price category
  • options array of ArticleOption
    Options for the article. If specify, variants for this article will be generated.
    show fields

    Array of ArticleOption.

    • name string example: color
      Name of the article option
    • values array of string
      Available choices for the article option
  • imageHrefs array of string read-only
    Reference uris for the images of this article if present.
  • isArticleSet boolean
    Decides if this article is an article set
  • articleSetName string
    Name of the article set. Does not need to be included if article is not an article set.
  • defaultQuantity number pattern: ^\d{1,19}([.]\d{1,2})?$
    The default quantity of the article
  • accountingTags array of string required
    Tags used for accounting. Articles with the same tag, same VAT case and same VAT rate are grouped together in the posting
  • articleNumber string required example: ABC123
    Article number
  • hasVariant boolean
    Specify if the article has variants or not
  • includedInArticleSets array of string
    Names of the article sets that the article is included in.
    If the article have some variants, then only the variants will show the article set name they belong to, not the parent article (null value is shown).
  • sellInOnlineShop boolean
    Specify if the article is able to be sold on the Online shop or not
  • isAdultArticle boolean
    Specify if the article is only used for adult or not
  • productType object required
    Type of product used for an article
  • posCategories array of ArticleCategoryRef
    Categories used for Point of Sale of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • posFilters array of ArticleFilterRef
    Filters used for Point of Sale of the article
    Provide only either id or href of each filter when creating Article
    show fields

    Array of ArticleFilterRef.

    • id string read-only example: 1
      Id of the filter. Does not need to be included when creating article.
    • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
      Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
    • nameDE string read-only example: shop
      Name of the filter in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the filter in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the filter in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the filter in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this filter.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the filter is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • onlineShopCategories array of ArticleCategoryRef
    Categories used for Online shop of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • onlineShopFilters array of ArticleFilterRef
    Filters used for Online shop of the article
    Provide only either id or href of each filter when creating Article
    show fields

    Array of ArticleFilterRef.

    • id string read-only example: 1
      Id of the filter. Does not need to be included when creating article.
    • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
      Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
    • nameDE string read-only example: shop
      Name of the filter in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the filter in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the filter in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the filter in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this filter.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the filter is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • bookingCategories array of ArticleCategoryRef
    Categories used for Online Booking of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • searchTags array of string
    Search tags make it easier for your customer to find your product in the online shop
  • shippingInfo object
    shipping information for an article.
    show fields
    • shippingAttributes array of string
      List of attributes used for shipping
    • weightUnit string
      Weight unit used for shipping of the article
      Allowed values: GRAM, KILOGRAM
    • dimensionUnit string
      Dimension unit used for shipping of the article
      Allowed values: CENTIMETER, METER
    • weight number pattern: ^\d{1,19}([.]\d{1,2})?$
      Weight of this article
    • width number pattern: ^\d{1,19}([.]\d{1,2})?$
      Width of this article
    • height number pattern: ^\d{1,19}([.]\d{1,2})?$
      Height of this article
    • depth number pattern: ^\d{1,19}([.]\d{1,2})?$
      Depth of this article
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
  • vats array of ArticleVat
    VAT information for the article
    show fields

    Array of ArticleVat.

    • vatType object example: NORMAL
      Article vat type of the article
    • vatCase string example: TAXABLE_SUPPLY
      VAT case of the article
    • vatCode string example: 1
      VAT code of the article VAT
    • sss1 boolean example: False
      Reporting net tax rate with SSS1 option
    • sss2 boolean example: False
      Reporting net tax rate with SSS2 option
    • reportingNetTaxRate boolean example: False
      Using VAT reporting net tax rate option
    • excludeVat boolean example: False
      Using exclude VAT option
  • numberType object
    Inventory Number Type
    Use either NO_NUMBER or SERIAL_NUMBER
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
POST/core/latest/articleskey / tokenCreate a new article
Request body required
The article object with the information that needs to be created

application/json Article

  • id string read-only example: 1
    Id of the article. Does not need to be included when creating article
  • nameDE string required
    Name of the article in German
  • nameEN string
    Name of the article in English
  • nameFR string
    Name of the article in French
  • nameIT string
    Name of the article in Italian
  • descriptionDE string
    Description of the article in German
  • descriptionEN string
    Description of the article in English
  • descriptionFR string
    Description of the article in French
  • descriptionIT string
    Description of the article in Italian
  • extendedDescriptionDE string
    Extended description of the article in German
  • extendedDescriptionEN string
    Extended description of the article in English
  • extendedDescriptionFR string
    Extended description of the article in French
  • extendedDescriptionIT string
    Extended description of the article in Italian
  • unitDE string required
    Unit of the article in German
  • unitEN string
    Unit of the article in English
  • unitFR string
    Unit of the article in French
  • unitIT string
    Unit of the article in Italian
  • barcode string
    Barcode of the article
  • usePos boolean
    Decides if this article is used for POS or not
  • pricePeriods array of PricePeriod
    Price periods for the article.
    If article only has single price period, ignore and don't include validFrom and validTo in the PricePeriod.
    If article have different prices valid for different periods, set value for validFrom for each price period or that price period is ignored.
    show fields

    Array of PricePeriod.

    • validFrom string (date) format: date
      The price period is valid from this time
    • validTo string (date) format: date read-only
      The price period is invalid after this time
    • price number pattern: ^\d{1,19}([.]\d{1,2})?$
      The price used for an article within this price period
    • priceCategories array of PriceCategory
      List of price categories effective for this price period
      show fields

      Array of PriceCategory.

      • name string
        Name of the price category
      • price number pattern: ^\d{1,19}([.]\d{1,2})?$
        Effective price of this price category
  • options array of ArticleOption
    Options for the article. If specify, variants for this article will be generated.
    show fields

    Array of ArticleOption.

    • name string example: color
      Name of the article option
    • values array of string
      Available choices for the article option
  • imageHrefs array of string read-only
    Reference uris for the images of this article if present.
  • isArticleSet boolean
    Decides if this article is an article set
  • articleSetName string
    Name of the article set. Does not need to be included if article is not an article set.
  • defaultQuantity number pattern: ^\d{1,19}([.]\d{1,2})?$
    The default quantity of the article
  • accountingTags array of string required
    Tags used for accounting. Articles with the same tag, same VAT case and same VAT rate are grouped together in the posting
  • articleNumber string required example: ABC123
    Article number
  • hasVariant boolean
    Specify if the article has variants or not
  • includedInArticleSets array of string
    Names of the article sets that the article is included in.
    If the article have some variants, then only the variants will show the article set name they belong to, not the parent article (null value is shown).
  • sellInOnlineShop boolean
    Specify if the article is able to be sold on the Online shop or not
  • isAdultArticle boolean
    Specify if the article is only used for adult or not
  • productType object required
    Type of product used for an article
  • posCategories array of ArticleCategoryRef
    Categories used for Point of Sale of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • posFilters array of ArticleFilterRef
    Filters used for Point of Sale of the article
    Provide only either id or href of each filter when creating Article
    show fields

    Array of ArticleFilterRef.

    • id string read-only example: 1
      Id of the filter. Does not need to be included when creating article.
    • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
      Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
    • nameDE string read-only example: shop
      Name of the filter in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the filter in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the filter in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the filter in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this filter.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the filter is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • onlineShopCategories array of ArticleCategoryRef
    Categories used for Online shop of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • onlineShopFilters array of ArticleFilterRef
    Filters used for Online shop of the article
    Provide only either id or href of each filter when creating Article
    show fields

    Array of ArticleFilterRef.

    • id string read-only example: 1
      Id of the filter. Does not need to be included when creating article.
    • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
      Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
    • nameDE string read-only example: shop
      Name of the filter in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the filter in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the filter in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the filter in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this filter.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the filter is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • bookingCategories array of ArticleCategoryRef
    Categories used for Online Booking of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • searchTags array of string
    Search tags make it easier for your customer to find your product in the online shop
  • shippingInfo object
    shipping information for an article.
    show fields
    • shippingAttributes array of string
      List of attributes used for shipping
    • weightUnit string
      Weight unit used for shipping of the article
      Allowed values: GRAM, KILOGRAM
    • dimensionUnit string
      Dimension unit used for shipping of the article
      Allowed values: CENTIMETER, METER
    • weight number pattern: ^\d{1,19}([.]\d{1,2})?$
      Weight of this article
    • width number pattern: ^\d{1,19}([.]\d{1,2})?$
      Width of this article
    • height number pattern: ^\d{1,19}([.]\d{1,2})?$
      Height of this article
    • depth number pattern: ^\d{1,19}([.]\d{1,2})?$
      Depth of this article
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
  • vats array of ArticleVat
    VAT information for the article
    show fields

    Array of ArticleVat.

    • vatType object example: NORMAL
      Article vat type of the article
    • vatCase string example: TAXABLE_SUPPLY
      VAT case of the article
    • vatCode string example: 1
      VAT code of the article VAT
    • sss1 boolean example: False
      Reporting net tax rate with SSS1 option
    • sss2 boolean example: False
      Reporting net tax rate with SSS2 option
    • reportingNetTaxRate boolean example: False
      Using VAT reporting net tax rate option
    • excludeVat boolean example: False
      Using exclude VAT option
  • numberType object
    Inventory Number Type
    Use either NO_NUMBER or SERIAL_NUMBER
Responses 5
201 Article created show body

application/json Article

  • id string read-only example: 1
    Id of the article. Does not need to be included when creating article
  • nameDE string required
    Name of the article in German
  • nameEN string
    Name of the article in English
  • nameFR string
    Name of the article in French
  • nameIT string
    Name of the article in Italian
  • descriptionDE string
    Description of the article in German
  • descriptionEN string
    Description of the article in English
  • descriptionFR string
    Description of the article in French
  • descriptionIT string
    Description of the article in Italian
  • extendedDescriptionDE string
    Extended description of the article in German
  • extendedDescriptionEN string
    Extended description of the article in English
  • extendedDescriptionFR string
    Extended description of the article in French
  • extendedDescriptionIT string
    Extended description of the article in Italian
  • unitDE string required
    Unit of the article in German
  • unitEN string
    Unit of the article in English
  • unitFR string
    Unit of the article in French
  • unitIT string
    Unit of the article in Italian
  • barcode string
    Barcode of the article
  • usePos boolean
    Decides if this article is used for POS or not
  • pricePeriods array of PricePeriod
    Price periods for the article.
    If article only has single price period, ignore and don't include validFrom and validTo in the PricePeriod.
    If article have different prices valid for different periods, set value for validFrom for each price period or that price period is ignored.
    show fields

    Array of PricePeriod.

    • validFrom string (date) format: date
      The price period is valid from this time
    • validTo string (date) format: date read-only
      The price period is invalid after this time
    • price number pattern: ^\d{1,19}([.]\d{1,2})?$
      The price used for an article within this price period
    • priceCategories array of PriceCategory
      List of price categories effective for this price period
      show fields

      Array of PriceCategory.

      • name string
        Name of the price category
      • price number pattern: ^\d{1,19}([.]\d{1,2})?$
        Effective price of this price category
  • options array of ArticleOption
    Options for the article. If specify, variants for this article will be generated.
    show fields

    Array of ArticleOption.

    • name string example: color
      Name of the article option
    • values array of string
      Available choices for the article option
  • imageHrefs array of string read-only
    Reference uris for the images of this article if present.
  • isArticleSet boolean
    Decides if this article is an article set
  • articleSetName string
    Name of the article set. Does not need to be included if article is not an article set.
  • defaultQuantity number pattern: ^\d{1,19}([.]\d{1,2})?$
    The default quantity of the article
  • accountingTags array of string required
    Tags used for accounting. Articles with the same tag, same VAT case and same VAT rate are grouped together in the posting
  • articleNumber string required example: ABC123
    Article number
  • hasVariant boolean
    Specify if the article has variants or not
  • includedInArticleSets array of string
    Names of the article sets that the article is included in.
    If the article have some variants, then only the variants will show the article set name they belong to, not the parent article (null value is shown).
  • sellInOnlineShop boolean
    Specify if the article is able to be sold on the Online shop or not
  • isAdultArticle boolean
    Specify if the article is only used for adult or not
  • productType object required
    Type of product used for an article
  • posCategories array of ArticleCategoryRef
    Categories used for Point of Sale of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • posFilters array of ArticleFilterRef
    Filters used for Point of Sale of the article
    Provide only either id or href of each filter when creating Article
    show fields

    Array of ArticleFilterRef.

    • id string read-only example: 1
      Id of the filter. Does not need to be included when creating article.
    • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
      Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
    • nameDE string read-only example: shop
      Name of the filter in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the filter in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the filter in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the filter in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this filter.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the filter is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • onlineShopCategories array of ArticleCategoryRef
    Categories used for Online shop of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • onlineShopFilters array of ArticleFilterRef
    Filters used for Online shop of the article
    Provide only either id or href of each filter when creating Article
    show fields

    Array of ArticleFilterRef.

    • id string read-only example: 1
      Id of the filter. Does not need to be included when creating article.
    • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
      Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
    • nameDE string read-only example: shop
      Name of the filter in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the filter in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the filter in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the filter in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this filter.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the filter is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • bookingCategories array of ArticleCategoryRef
    Categories used for Online Booking of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • searchTags array of string
    Search tags make it easier for your customer to find your product in the online shop
  • shippingInfo object
    shipping information for an article.
    show fields
    • shippingAttributes array of string
      List of attributes used for shipping
    • weightUnit string
      Weight unit used for shipping of the article
      Allowed values: GRAM, KILOGRAM
    • dimensionUnit string
      Dimension unit used for shipping of the article
      Allowed values: CENTIMETER, METER
    • weight number pattern: ^\d{1,19}([.]\d{1,2})?$
      Weight of this article
    • width number pattern: ^\d{1,19}([.]\d{1,2})?$
      Width of this article
    • height number pattern: ^\d{1,19}([.]\d{1,2})?$
      Height of this article
    • depth number pattern: ^\d{1,19}([.]\d{1,2})?$
      Depth of this article
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
  • vats array of ArticleVat
    VAT information for the article
    show fields

    Array of ArticleVat.

    • vatType object example: NORMAL
      Article vat type of the article
    • vatCase string example: TAXABLE_SUPPLY
      VAT case of the article
    • vatCode string example: 1
      VAT code of the article VAT
    • sss1 boolean example: False
      Reporting net tax rate with SSS1 option
    • sss2 boolean example: False
      Reporting net tax rate with SSS2 option
    • reportingNetTaxRate boolean example: False
      Using VAT reporting net tax rate option
    • excludeVat boolean example: False
      Using exclude VAT option
  • numberType object
    Inventory Number Type
    Use either NO_NUMBER or SERIAL_NUMBER
400 Data invalid show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
GET/core/latest/articles/article-and-variantskey / tokenReturns list of articles and treat a variant combination same as an article
Parameters 6
NameDescription
include-quantity
query boolean
flag to include quantity in the result.
limit
query integer (int32)
Define the limit of the article list that this API returns.
For example, if a company have 20 articles in total, and this limit parameter is 5, and the offset parameter is 0,
then this API will return article list containing the first 5 articles
If not set, then default value of 48 is used
format: int32 min: 1 max: 1000 default: 48
offset
query integer (int32)
Define which position to start getting article list.
For example, if a company have 20 articles in total, and this offset parameter is 5,
then this API will return article list from the 5th article.
If not set, then default value of 0 is used
format: int32 min: 0 default: 0
sell-in-booking
query boolean
flag to define sellable article for booking.
sell-in-online-shop
query boolean
flag to query articles that are sold in online shop.
use-pos
query boolean
flag to define article that are using in POS.
Responses 4
200 List of article and variant show body

application/json array of ArticleAndVariant

Array of ArticleAndVariant.

  • id string example: 1
    Id of the article
  • name string
    Name of the article
  • description string
    Description for the article
  • extendedDescription string
    This description will be used for example in your online shop
  • unit string
    Define how the article is count by
  • barcode string
    Barcode of the article
  • defaultQuantity number
    The default quantity of the article
  • accountingTags array of string
    Tags used for accounting. Articles with the same tag, same VAT case and same VAT rate are grouped together in the posting
  • articleNumber string example: ABC123
    Number of the article
  • productType object
    Type of product used for an article
  • priceCategories array of ArticlePriceCategory
    Price categories of the article
    show fields

    Array of ArticlePriceCategory.

    • name string
    • priceIncludeVat number
    • priceExcludeVat number
  • vatRate number
    Vat rate of the article
  • articleType object
    Article type
  • priceIncludeVat number
    price include vat
  • priceExcludeVat number
    price exclude vat
  • hasInventory boolean
    This article has inventory or not
  • quantityInStock number
    Quantity in stock
  • optionValues array of string
    Variant option of this article
  • ableToOrderOutOfStock boolean
    Flag define the article is allow to order out of stock
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
GET/core/latest/articles/article-numberskey / tokenFind articles by article numbers
Batch-resolve a list of article numbers to their priced article rows of the caller's company. Returns each row enriched with the price valid on `price-date` and the appropriate VAT rate. Unknown article numbers are silently skipped (returned list contains only matching rows). Requires permission `ARTICLE_READ_ONLY`.
Parameters 4
NameDescription
article-numbers
query array of any
Article numbers to look up. Repeat the parameter for each value (e.g. `?article-numbers=ART-001&article-numbers=ART-002`). At most 100 entries; each entry up to 64 characters.
maxItems: 100 example: ART-001
export-vat
query boolean
If `true`, return ABROAD (export) VAT rate; otherwise NORMAL. Defaults to false.
default: false
price-date
query string (date)
Date on which prices are evaluated. Format: yyyy-MM-dd. Defaults to today when omitted.
format: date example: 2026-06-01
should-validate-vat
query boolean
If `true`, cross-validate each row's VAT code against the company's VAT setup on `price-date`. Defaults to false.
default: false
Responses 6
200 Matching articles show body

application/json array of ArticleAndVariant

Array of ArticleAndVariant.

  • id string example: 1
    Id of the article
  • name string
    Name of the article
  • description string
    Description for the article
  • extendedDescription string
    This description will be used for example in your online shop
  • unit string
    Define how the article is count by
  • barcode string
    Barcode of the article
  • defaultQuantity number
    The default quantity of the article
  • accountingTags array of string
    Tags used for accounting. Articles with the same tag, same VAT case and same VAT rate are grouped together in the posting
  • articleNumber string example: ABC123
    Number of the article
  • productType object
    Type of product used for an article
  • priceCategories array of ArticlePriceCategory
    Price categories of the article
    show fields

    Array of ArticlePriceCategory.

    • name string
    • priceIncludeVat number
    • priceExcludeVat number
  • vatRate number
    Vat rate of the article
  • articleType object
    Article type
  • priceIncludeVat number
    price include vat
  • priceExcludeVat number
    price exclude vat
  • hasInventory boolean
    This article has inventory or not
  • quantityInStock number
    Quantity in stock
  • optionValues array of string
    Variant option of this article
  • ableToOrderOutOfStock boolean
    Flag define the article is allow to order out of stock
400 Data invalid show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. no response body
POST/core/latest/articles/bulkkey / tokenCreate articles
Request body required
The list of articles

application/json array of Article

Array of Article.

  • id string read-only example: 1
    Id of the article. Does not need to be included when creating article
  • nameDE string required
    Name of the article in German
  • nameEN string
    Name of the article in English
  • nameFR string
    Name of the article in French
  • nameIT string
    Name of the article in Italian
  • descriptionDE string
    Description of the article in German
  • descriptionEN string
    Description of the article in English
  • descriptionFR string
    Description of the article in French
  • descriptionIT string
    Description of the article in Italian
  • extendedDescriptionDE string
    Extended description of the article in German
  • extendedDescriptionEN string
    Extended description of the article in English
  • extendedDescriptionFR string
    Extended description of the article in French
  • extendedDescriptionIT string
    Extended description of the article in Italian
  • unitDE string required
    Unit of the article in German
  • unitEN string
    Unit of the article in English
  • unitFR string
    Unit of the article in French
  • unitIT string
    Unit of the article in Italian
  • barcode string
    Barcode of the article
  • usePos boolean
    Decides if this article is used for POS or not
  • pricePeriods array of PricePeriod
    Price periods for the article.
    If article only has single price period, ignore and don't include validFrom and validTo in the PricePeriod.
    If article have different prices valid for different periods, set value for validFrom for each price period or that price period is ignored.
    show fields

    Array of PricePeriod.

    • validFrom string (date) format: date
      The price period is valid from this time
    • validTo string (date) format: date read-only
      The price period is invalid after this time
    • price number pattern: ^\d{1,19}([.]\d{1,2})?$
      The price used for an article within this price period
    • priceCategories array of PriceCategory
      List of price categories effective for this price period
      show fields

      Array of PriceCategory.

      • name string
        Name of the price category
      • price number pattern: ^\d{1,19}([.]\d{1,2})?$
        Effective price of this price category
  • options array of ArticleOption
    Options for the article. If specify, variants for this article will be generated.
    show fields

    Array of ArticleOption.

    • name string example: color
      Name of the article option
    • values array of string
      Available choices for the article option
  • imageHrefs array of string read-only
    Reference uris for the images of this article if present.
  • isArticleSet boolean
    Decides if this article is an article set
  • articleSetName string
    Name of the article set. Does not need to be included if article is not an article set.
  • defaultQuantity number pattern: ^\d{1,19}([.]\d{1,2})?$
    The default quantity of the article
  • accountingTags array of string required
    Tags used for accounting. Articles with the same tag, same VAT case and same VAT rate are grouped together in the posting
  • articleNumber string required example: ABC123
    Article number
  • hasVariant boolean
    Specify if the article has variants or not
  • includedInArticleSets array of string
    Names of the article sets that the article is included in.
    If the article have some variants, then only the variants will show the article set name they belong to, not the parent article (null value is shown).
  • sellInOnlineShop boolean
    Specify if the article is able to be sold on the Online shop or not
  • isAdultArticle boolean
    Specify if the article is only used for adult or not
  • productType object required
    Type of product used for an article
  • posCategories array of ArticleCategoryRef
    Categories used for Point of Sale of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • posFilters array of ArticleFilterRef
    Filters used for Point of Sale of the article
    Provide only either id or href of each filter when creating Article
    show fields

    Array of ArticleFilterRef.

    • id string read-only example: 1
      Id of the filter. Does not need to be included when creating article.
    • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
      Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
    • nameDE string read-only example: shop
      Name of the filter in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the filter in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the filter in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the filter in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this filter.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the filter is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • onlineShopCategories array of ArticleCategoryRef
    Categories used for Online shop of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • onlineShopFilters array of ArticleFilterRef
    Filters used for Online shop of the article
    Provide only either id or href of each filter when creating Article
    show fields

    Array of ArticleFilterRef.

    • id string read-only example: 1
      Id of the filter. Does not need to be included when creating article.
    • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
      Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
    • nameDE string read-only example: shop
      Name of the filter in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the filter in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the filter in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the filter in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this filter.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the filter is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • bookingCategories array of ArticleCategoryRef
    Categories used for Online Booking of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • searchTags array of string
    Search tags make it easier for your customer to find your product in the online shop
  • shippingInfo object
    shipping information for an article.
    show fields
    • shippingAttributes array of string
      List of attributes used for shipping
    • weightUnit string
      Weight unit used for shipping of the article
      Allowed values: GRAM, KILOGRAM
    • dimensionUnit string
      Dimension unit used for shipping of the article
      Allowed values: CENTIMETER, METER
    • weight number pattern: ^\d{1,19}([.]\d{1,2})?$
      Weight of this article
    • width number pattern: ^\d{1,19}([.]\d{1,2})?$
      Width of this article
    • height number pattern: ^\d{1,19}([.]\d{1,2})?$
      Height of this article
    • depth number pattern: ^\d{1,19}([.]\d{1,2})?$
      Depth of this article
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
  • vats array of ArticleVat
    VAT information for the article
    show fields

    Array of ArticleVat.

    • vatType object example: NORMAL
      Article vat type of the article
    • vatCase string example: TAXABLE_SUPPLY
      VAT case of the article
    • vatCode string example: 1
      VAT code of the article VAT
    • sss1 boolean example: False
      Reporting net tax rate with SSS1 option
    • sss2 boolean example: False
      Reporting net tax rate with SSS2 option
    • reportingNetTaxRate boolean example: False
      Using VAT reporting net tax rate option
    • excludeVat boolean example: False
      Using exclude VAT option
  • numberType object
    Inventory Number Type
    Use either NO_NUMBER or SERIAL_NUMBER
Responses 4
200 Article created show body

application/json BulkArticleCreatingResponse

  • numberOfSuccess integer (int32) format: int32 example: 2
    Number of articles saved successfully
  • numberOfFail integer (int32) format: int32 example: 2
    Number of articles saved unsuccessfully
  • success array of Article
    A list of saved articles
    show fields

    Array of Article.

    • id string read-only example: 1
      Id of the article. Does not need to be included when creating article
    • nameDE string required
      Name of the article in German
    • nameEN string
      Name of the article in English
    • nameFR string
      Name of the article in French
    • nameIT string
      Name of the article in Italian
    • descriptionDE string
      Description of the article in German
    • descriptionEN string
      Description of the article in English
    • descriptionFR string
      Description of the article in French
    • descriptionIT string
      Description of the article in Italian
    • extendedDescriptionDE string
      Extended description of the article in German
    • extendedDescriptionEN string
      Extended description of the article in English
    • extendedDescriptionFR string
      Extended description of the article in French
    • extendedDescriptionIT string
      Extended description of the article in Italian
    • unitDE string required
      Unit of the article in German
    • unitEN string
      Unit of the article in English
    • unitFR string
      Unit of the article in French
    • unitIT string
      Unit of the article in Italian
    • barcode string
      Barcode of the article
    • usePos boolean
      Decides if this article is used for POS or not
    • pricePeriods array of PricePeriod
      Price periods for the article.
      If article only has single price period, ignore and don't include validFrom and validTo in the PricePeriod.
      If article have different prices valid for different periods, set value for validFrom for each price period or that price period is ignored.
      show fields

      Array of PricePeriod.

      • validFrom string (date) format: date
        The price period is valid from this time
      • validTo string (date) format: date read-only
        The price period is invalid after this time
      • price number pattern: ^\d{1,19}([.]\d{1,2})?$
        The price used for an article within this price period
      • priceCategories array of PriceCategory
        List of price categories effective for this price period
        show fields

        Array of PriceCategory.

        • name string
          Name of the price category
        • price number pattern: ^\d{1,19}([.]\d{1,2})?$
          Effective price of this price category
    • options array of ArticleOption
      Options for the article. If specify, variants for this article will be generated.
      show fields

      Array of ArticleOption.

      • name string example: color
        Name of the article option
      • values array of string
        Available choices for the article option
    • imageHrefs array of string read-only
      Reference uris for the images of this article if present.
    • isArticleSet boolean
      Decides if this article is an article set
    • articleSetName string
      Name of the article set. Does not need to be included if article is not an article set.
    • defaultQuantity number pattern: ^\d{1,19}([.]\d{1,2})?$
      The default quantity of the article
    • accountingTags array of string required
      Tags used for accounting. Articles with the same tag, same VAT case and same VAT rate are grouped together in the posting
    • articleNumber string required example: ABC123
      Article number
    • hasVariant boolean
      Specify if the article has variants or not
    • includedInArticleSets array of string
      Names of the article sets that the article is included in.
      If the article have some variants, then only the variants will show the article set name they belong to, not the parent article (null value is shown).
    • sellInOnlineShop boolean
      Specify if the article is able to be sold on the Online shop or not
    • isAdultArticle boolean
      Specify if the article is only used for adult or not
    • productType object required
      Type of product used for an article
    • posCategories array of ArticleCategoryRef
      Categories used for Point of Sale of the article
      Provide only either id or href of each category when creating Article
      show fields

      Array of ArticleCategoryRef.

      • id string read-only example: 1
        Id of the category. Does not need to be included when creating article
      • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
        Reference uri for an article category. If specified, this article will be assigned to the entered article category.
      • nameDE string read-only example: shop
        Name of the category in german.
        Does not need to be included when creating article.
      • nameEN string read-only example: shop
        Name of the category in english.
        Does not need to be included when creating article.
      • nameFR string read-only example: shop
        Name of the category in french.
        Does not need to be included when creating article.
      • nameIT string read-only example: shop
        Name of the category in italy.
        Does not need to be included when creating article.
      • order integer (int32) format: int32 read-only
        Order of this category.
        Does not need to be included when creating article.
      • active boolean read-only
        Indicates if the category is active or not
      • _links object
        links metadata
        show fields
        • self Link
          Link metadata
          show fields
          • href string
    • posFilters array of ArticleFilterRef
      Filters used for Point of Sale of the article
      Provide only either id or href of each filter when creating Article
      show fields

      Array of ArticleFilterRef.

      • id string read-only example: 1
        Id of the filter. Does not need to be included when creating article.
      • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
        Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
      • nameDE string read-only example: shop
        Name of the filter in german.
        Does not need to be included when creating article.
      • nameEN string read-only example: shop
        Name of the filter in english.
        Does not need to be included when creating article.
      • nameFR string read-only example: shop
        Name of the filter in french.
        Does not need to be included when creating article.
      • nameIT string read-only example: shop
        Name of the filter in italy.
        Does not need to be included when creating article.
      • order integer (int32) format: int32 read-only
        Order of this filter.
        Does not need to be included when creating article.
      • active boolean read-only
        Indicates if the filter is active or not
      • _links object
        links metadata
        show fields
        • self Link
          Link metadata
          show fields
          • href string
    • onlineShopCategories array of ArticleCategoryRef
      Categories used for Online shop of the article
      Provide only either id or href of each category when creating Article
      show fields

      Array of ArticleCategoryRef.

      • id string read-only example: 1
        Id of the category. Does not need to be included when creating article
      • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
        Reference uri for an article category. If specified, this article will be assigned to the entered article category.
      • nameDE string read-only example: shop
        Name of the category in german.
        Does not need to be included when creating article.
      • nameEN string read-only example: shop
        Name of the category in english.
        Does not need to be included when creating article.
      • nameFR string read-only example: shop
        Name of the category in french.
        Does not need to be included when creating article.
      • nameIT string read-only example: shop
        Name of the category in italy.
        Does not need to be included when creating article.
      • order integer (int32) format: int32 read-only
        Order of this category.
        Does not need to be included when creating article.
      • active boolean read-only
        Indicates if the category is active or not
      • _links object
        links metadata
        show fields
        • self Link
          Link metadata
          show fields
          • href string
    • onlineShopFilters array of ArticleFilterRef
      Filters used for Online shop of the article
      Provide only either id or href of each filter when creating Article
      show fields

      Array of ArticleFilterRef.

      • id string read-only example: 1
        Id of the filter. Does not need to be included when creating article.
      • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
        Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
      • nameDE string read-only example: shop
        Name of the filter in german.
        Does not need to be included when creating article.
      • nameEN string read-only example: shop
        Name of the filter in english.
        Does not need to be included when creating article.
      • nameFR string read-only example: shop
        Name of the filter in french.
        Does not need to be included when creating article.
      • nameIT string read-only example: shop
        Name of the filter in italy.
        Does not need to be included when creating article.
      • order integer (int32) format: int32 read-only
        Order of this filter.
        Does not need to be included when creating article.
      • active boolean read-only
        Indicates if the filter is active or not
      • _links object
        links metadata
        show fields
        • self Link
          Link metadata
          show fields
          • href string
    • bookingCategories array of ArticleCategoryRef
      Categories used for Online Booking of the article
      Provide only either id or href of each category when creating Article
      show fields

      Array of ArticleCategoryRef.

      • id string read-only example: 1
        Id of the category. Does not need to be included when creating article
      • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
        Reference uri for an article category. If specified, this article will be assigned to the entered article category.
      • nameDE string read-only example: shop
        Name of the category in german.
        Does not need to be included when creating article.
      • nameEN string read-only example: shop
        Name of the category in english.
        Does not need to be included when creating article.
      • nameFR string read-only example: shop
        Name of the category in french.
        Does not need to be included when creating article.
      • nameIT string read-only example: shop
        Name of the category in italy.
        Does not need to be included when creating article.
      • order integer (int32) format: int32 read-only
        Order of this category.
        Does not need to be included when creating article.
      • active boolean read-only
        Indicates if the category is active or not
      • _links object
        links metadata
        show fields
        • self Link
          Link metadata
          show fields
          • href string
    • searchTags array of string
      Search tags make it easier for your customer to find your product in the online shop
    • shippingInfo object
      shipping information for an article.
      show fields
      • shippingAttributes array of string
        List of attributes used for shipping
      • weightUnit string
        Weight unit used for shipping of the article
        Allowed values: GRAM, KILOGRAM
      • dimensionUnit string
        Dimension unit used for shipping of the article
        Allowed values: CENTIMETER, METER
      • weight number pattern: ^\d{1,19}([.]\d{1,2})?$
        Weight of this article
      • width number pattern: ^\d{1,19}([.]\d{1,2})?$
        Width of this article
      • height number pattern: ^\d{1,19}([.]\d{1,2})?$
        Height of this article
      • depth number pattern: ^\d{1,19}([.]\d{1,2})?$
        Depth of this article
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
    • vats array of ArticleVat
      VAT information for the article
      show fields

      Array of ArticleVat.

      • vatType object example: NORMAL
        Article vat type of the article
      • vatCase string example: TAXABLE_SUPPLY
        VAT case of the article
      • vatCode string example: 1
        VAT code of the article VAT
      • sss1 boolean example: False
        Reporting net tax rate with SSS1 option
      • sss2 boolean example: False
        Reporting net tax rate with SSS2 option
      • reportingNetTaxRate boolean example: False
        Using VAT reporting net tax rate option
      • excludeVat boolean example: False
        Using exclude VAT option
    • numberType object
      Inventory Number Type
      Use either NO_NUMBER or SERIAL_NUMBER
  • fail array of PublicApiFailArticle
    A list of unsaved articles with error message
    show fields

    Array of PublicApiFailArticle.

    • errorCode string example: article.number.could.not.be.duplicated
      Error code
    • errorMessage string example: Article number could not be duplicated
      Error message
    • unsavedArticle object
      An article.
      show fields
      • id string read-only example: 1
        Id of the article. Does not need to be included when creating article
      • nameDE string required
        Name of the article in German
      • nameEN string
        Name of the article in English
      • nameFR string
        Name of the article in French
      • nameIT string
        Name of the article in Italian
      • descriptionDE string
        Description of the article in German
      • descriptionEN string
        Description of the article in English
      • descriptionFR string
        Description of the article in French
      • descriptionIT string
        Description of the article in Italian
      • extendedDescriptionDE string
        Extended description of the article in German
      • extendedDescriptionEN string
        Extended description of the article in English
      • extendedDescriptionFR string
        Extended description of the article in French
      • extendedDescriptionIT string
        Extended description of the article in Italian
      • unitDE string required
        Unit of the article in German
      • unitEN string
        Unit of the article in English
      • unitFR string
        Unit of the article in French
      • unitIT string
        Unit of the article in Italian
      • barcode string
        Barcode of the article
      • usePos boolean
        Decides if this article is used for POS or not
      • pricePeriods array of PricePeriod
        Price periods for the article.
        If article only has single price period, ignore and don't include validFrom and validTo in the PricePeriod.
        If article have different prices valid for different periods, set value for validFrom for each price period or that price period is ignored.
        show fields

        Array of PricePeriod.

        • validFrom string (date) format: date
          The price period is valid from this time
        • validTo string (date) format: date read-only
          The price period is invalid after this time
        • price number pattern: ^\d{1,19}([.]\d{1,2})?$
          The price used for an article within this price period
        • priceCategories array of PriceCategory
          List of price categories effective for this price period
          show fields

          Array of PriceCategory.

          • name string
            Name of the price category
          • price number pattern: ^\d{1,19}([.]\d{1,2})?$
            Effective price of this price category
      • options array of ArticleOption
        Options for the article. If specify, variants for this article will be generated.
        show fields

        Array of ArticleOption.

        • name string example: color
          Name of the article option
        • values array of string
          Available choices for the article option
      • imageHrefs array of string read-only
        Reference uris for the images of this article if present.
      • isArticleSet boolean
        Decides if this article is an article set
      • articleSetName string
        Name of the article set. Does not need to be included if article is not an article set.
      • defaultQuantity number pattern: ^\d{1,19}([.]\d{1,2})?$
        The default quantity of the article
      • accountingTags array of string required
        Tags used for accounting. Articles with the same tag, same VAT case and same VAT rate are grouped together in the posting
      • articleNumber string required example: ABC123
        Article number
      • hasVariant boolean
        Specify if the article has variants or not
      • includedInArticleSets array of string
        Names of the article sets that the article is included in.
        If the article have some variants, then only the variants will show the article set name they belong to, not the parent article (null value is shown).
      • sellInOnlineShop boolean
        Specify if the article is able to be sold on the Online shop or not
      • isAdultArticle boolean
        Specify if the article is only used for adult or not
      • productType object required
        Type of product used for an article
      • posCategories array of ArticleCategoryRef
        Categories used for Point of Sale of the article
        Provide only either id or href of each category when creating Article
        show fields

        Array of ArticleCategoryRef.

        • id string read-only example: 1
          Id of the category. Does not need to be included when creating article
        • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
          Reference uri for an article category. If specified, this article will be assigned to the entered article category.
        • nameDE string read-only example: shop
          Name of the category in german.
          Does not need to be included when creating article.
        • nameEN string read-only example: shop
          Name of the category in english.
          Does not need to be included when creating article.
        • nameFR string read-only example: shop
          Name of the category in french.
          Does not need to be included when creating article.
        • nameIT string read-only example: shop
          Name of the category in italy.
          Does not need to be included when creating article.
        • order integer (int32) format: int32 read-only
          Order of this category.
          Does not need to be included when creating article.
        • active boolean read-only
          Indicates if the category is active or not
        • _links object
          links metadata
          show fields
          • self Link
            Link metadata
            show fields
            • href string
      • posFilters array of ArticleFilterRef
        Filters used for Point of Sale of the article
        Provide only either id or href of each filter when creating Article
        show fields

        Array of ArticleFilterRef.

        • id string read-only example: 1
          Id of the filter. Does not need to be included when creating article.
        • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
          Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
        • nameDE string read-only example: shop
          Name of the filter in german.
          Does not need to be included when creating article.
        • nameEN string read-only example: shop
          Name of the filter in english.
          Does not need to be included when creating article.
        • nameFR string read-only example: shop
          Name of the filter in french.
          Does not need to be included when creating article.
        • nameIT string read-only example: shop
          Name of the filter in italy.
          Does not need to be included when creating article.
        • order integer (int32) format: int32 read-only
          Order of this filter.
          Does not need to be included when creating article.
        • active boolean read-only
          Indicates if the filter is active or not
        • _links object
          links metadata
          show fields
          • self Link
            Link metadata
            show fields
            • href string
      • onlineShopCategories array of ArticleCategoryRef
        Categories used for Online shop of the article
        Provide only either id or href of each category when creating Article
        show fields

        Array of ArticleCategoryRef.

        • id string read-only example: 1
          Id of the category. Does not need to be included when creating article
        • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
          Reference uri for an article category. If specified, this article will be assigned to the entered article category.
        • nameDE string read-only example: shop
          Name of the category in german.
          Does not need to be included when creating article.
        • nameEN string read-only example: shop
          Name of the category in english.
          Does not need to be included when creating article.
        • nameFR string read-only example: shop
          Name of the category in french.
          Does not need to be included when creating article.
        • nameIT string read-only example: shop
          Name of the category in italy.
          Does not need to be included when creating article.
        • order integer (int32) format: int32 read-only
          Order of this category.
          Does not need to be included when creating article.
        • active boolean read-only
          Indicates if the category is active or not
        • _links object
          links metadata
          show fields
          • self Link
            Link metadata
            show fields
            • href string
      • onlineShopFilters array of ArticleFilterRef
        Filters used for Online shop of the article
        Provide only either id or href of each filter when creating Article
        show fields

        Array of ArticleFilterRef.

        • id string read-only example: 1
          Id of the filter. Does not need to be included when creating article.
        • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
          Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
        • nameDE string read-only example: shop
          Name of the filter in german.
          Does not need to be included when creating article.
        • nameEN string read-only example: shop
          Name of the filter in english.
          Does not need to be included when creating article.
        • nameFR string read-only example: shop
          Name of the filter in french.
          Does not need to be included when creating article.
        • nameIT string read-only example: shop
          Name of the filter in italy.
          Does not need to be included when creating article.
        • order integer (int32) format: int32 read-only
          Order of this filter.
          Does not need to be included when creating article.
        • active boolean read-only
          Indicates if the filter is active or not
        • _links object
          links metadata
          show fields
          • self Link
            Link metadata
            show fields
            • href string
      • bookingCategories array of ArticleCategoryRef
        Categories used for Online Booking of the article
        Provide only either id or href of each category when creating Article
        show fields

        Array of ArticleCategoryRef.

        • id string read-only example: 1
          Id of the category. Does not need to be included when creating article
        • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
          Reference uri for an article category. If specified, this article will be assigned to the entered article category.
        • nameDE string read-only example: shop
          Name of the category in german.
          Does not need to be included when creating article.
        • nameEN string read-only example: shop
          Name of the category in english.
          Does not need to be included when creating article.
        • nameFR string read-only example: shop
          Name of the category in french.
          Does not need to be included when creating article.
        • nameIT string read-only example: shop
          Name of the category in italy.
          Does not need to be included when creating article.
        • order integer (int32) format: int32 read-only
          Order of this category.
          Does not need to be included when creating article.
        • active boolean read-only
          Indicates if the category is active or not
        • _links object
          links metadata
          show fields
          • self Link
            Link metadata
            show fields
            • href string
      • searchTags array of string
        Search tags make it easier for your customer to find your product in the online shop
      • shippingInfo object
        shipping information for an article.
        show fields
        • shippingAttributes array of string
          List of attributes used for shipping
        • weightUnit string
          Weight unit used for shipping of the article
          Allowed values: GRAM, KILOGRAM
        • dimensionUnit string
          Dimension unit used for shipping of the article
          Allowed values: CENTIMETER, METER
        • weight number pattern: ^\d{1,19}([.]\d{1,2})?$
          Weight of this article
        • width number pattern: ^\d{1,19}([.]\d{1,2})?$
          Width of this article
        • height number pattern: ^\d{1,19}([.]\d{1,2})?$
          Height of this article
        • depth number pattern: ^\d{1,19}([.]\d{1,2})?$
          Depth of this article
      • _links object
        links metadata
        show fields
        • self Link
          Link metadata
          show fields
          • href string
      • vats array of ArticleVat
        VAT information for the article
        show fields

        Array of ArticleVat.

        • vatType object example: NORMAL
          Article vat type of the article
        • vatCase string example: TAXABLE_SUPPLY
          VAT case of the article
        • vatCode string example: 1
          VAT code of the article VAT
        • sss1 boolean example: False
          Reporting net tax rate with SSS1 option
        • sss2 boolean example: False
          Reporting net tax rate with SSS2 option
        • reportingNetTaxRate boolean example: False
          Using VAT reporting net tax rate option
        • excludeVat boolean example: False
          Using exclude VAT option
      • numberType object
        Inventory Number Type
        Use either NO_NUMBER or SERIAL_NUMBER
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
GET/core/latest/articles/searchkey / tokenSearch articles by keyword
Free-text search across sellable articles (and their variants) of the caller's company. Matches by name, article number, barcode, variant number and set-header name. Returns each row enriched with the price valid on `price-date` and the appropriate VAT rate. Requires permission `ARTICLE_READ_ONLY`.
Parameters 6
NameDescription
export-vat
query boolean
If `true`, return ABROAD (export) VAT rate; otherwise NORMAL.
default: false
keyword
query string
Free-text search keyword. Trimmed; empty/missing returns the first page unfiltered.
maxLength: 256 example: paper
limit
query integer
Page size (1–100).
min: 1 max: 100 default: 50 example: 50
offset
query integer
0-based pagination offset.
min: 0 default: 0 example: 0
price-date
query string (date)
Date on which prices are evaluated. Format: yyyy-MM-dd. Defaults to today when omitted.
format: date example: 2026-06-01
should-validate-vat
query boolean
If `true`, cross-validate each row's VAT code against the company's VAT setup on `price-date`.
default: false
Responses 6
200 Matching articles show body

application/json array of ArticleAndVariant

Array of ArticleAndVariant.

  • id string example: 1
    Id of the article
  • name string
    Name of the article
  • description string
    Description for the article
  • extendedDescription string
    This description will be used for example in your online shop
  • unit string
    Define how the article is count by
  • barcode string
    Barcode of the article
  • defaultQuantity number
    The default quantity of the article
  • accountingTags array of string
    Tags used for accounting. Articles with the same tag, same VAT case and same VAT rate are grouped together in the posting
  • articleNumber string example: ABC123
    Number of the article
  • productType object
    Type of product used for an article
  • priceCategories array of ArticlePriceCategory
    Price categories of the article
    show fields

    Array of ArticlePriceCategory.

    • name string
    • priceIncludeVat number
    • priceExcludeVat number
  • vatRate number
    Vat rate of the article
  • articleType object
    Article type
  • priceIncludeVat number
    price include vat
  • priceExcludeVat number
    price exclude vat
  • hasInventory boolean
    This article has inventory or not
  • quantityInStock number
    Quantity in stock
  • optionValues array of string
    Variant option of this article
  • ableToOrderOutOfStock boolean
    Flag define the article is allow to order out of stock
400 Data invalid show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. no response body
DELETE/core/latest/articles/{article-id}key / tokenDelete an article
Parameters 1
NameDescription
article-id required
path string
Id of the article to be deleted
example: 1
Responses 7
204 Article deleted by given article id no response body
400 Data invalid show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. no response body
GET/core/latest/articles/{article-id}key / tokenGet article by article id
Parameters 1
NameDescription
article-id required
path string
Responses 5
200 Found article show body

application/json Article

  • id string read-only example: 1
    Id of the article. Does not need to be included when creating article
  • nameDE string required
    Name of the article in German
  • nameEN string
    Name of the article in English
  • nameFR string
    Name of the article in French
  • nameIT string
    Name of the article in Italian
  • descriptionDE string
    Description of the article in German
  • descriptionEN string
    Description of the article in English
  • descriptionFR string
    Description of the article in French
  • descriptionIT string
    Description of the article in Italian
  • extendedDescriptionDE string
    Extended description of the article in German
  • extendedDescriptionEN string
    Extended description of the article in English
  • extendedDescriptionFR string
    Extended description of the article in French
  • extendedDescriptionIT string
    Extended description of the article in Italian
  • unitDE string required
    Unit of the article in German
  • unitEN string
    Unit of the article in English
  • unitFR string
    Unit of the article in French
  • unitIT string
    Unit of the article in Italian
  • barcode string
    Barcode of the article
  • usePos boolean
    Decides if this article is used for POS or not
  • pricePeriods array of PricePeriod
    Price periods for the article.
    If article only has single price period, ignore and don't include validFrom and validTo in the PricePeriod.
    If article have different prices valid for different periods, set value for validFrom for each price period or that price period is ignored.
    show fields

    Array of PricePeriod.

    • validFrom string (date) format: date
      The price period is valid from this time
    • validTo string (date) format: date read-only
      The price period is invalid after this time
    • price number pattern: ^\d{1,19}([.]\d{1,2})?$
      The price used for an article within this price period
    • priceCategories array of PriceCategory
      List of price categories effective for this price period
      show fields

      Array of PriceCategory.

      • name string
        Name of the price category
      • price number pattern: ^\d{1,19}([.]\d{1,2})?$
        Effective price of this price category
  • options array of ArticleOption
    Options for the article. If specify, variants for this article will be generated.
    show fields

    Array of ArticleOption.

    • name string example: color
      Name of the article option
    • values array of string
      Available choices for the article option
  • imageHrefs array of string read-only
    Reference uris for the images of this article if present.
  • isArticleSet boolean
    Decides if this article is an article set
  • articleSetName string
    Name of the article set. Does not need to be included if article is not an article set.
  • defaultQuantity number pattern: ^\d{1,19}([.]\d{1,2})?$
    The default quantity of the article
  • accountingTags array of string required
    Tags used for accounting. Articles with the same tag, same VAT case and same VAT rate are grouped together in the posting
  • articleNumber string required example: ABC123
    Article number
  • hasVariant boolean
    Specify if the article has variants or not
  • includedInArticleSets array of string
    Names of the article sets that the article is included in.
    If the article have some variants, then only the variants will show the article set name they belong to, not the parent article (null value is shown).
  • sellInOnlineShop boolean
    Specify if the article is able to be sold on the Online shop or not
  • isAdultArticle boolean
    Specify if the article is only used for adult or not
  • productType object required
    Type of product used for an article
  • posCategories array of ArticleCategoryRef
    Categories used for Point of Sale of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • posFilters array of ArticleFilterRef
    Filters used for Point of Sale of the article
    Provide only either id or href of each filter when creating Article
    show fields

    Array of ArticleFilterRef.

    • id string read-only example: 1
      Id of the filter. Does not need to be included when creating article.
    • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
      Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
    • nameDE string read-only example: shop
      Name of the filter in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the filter in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the filter in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the filter in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this filter.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the filter is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • onlineShopCategories array of ArticleCategoryRef
    Categories used for Online shop of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • onlineShopFilters array of ArticleFilterRef
    Filters used for Online shop of the article
    Provide only either id or href of each filter when creating Article
    show fields

    Array of ArticleFilterRef.

    • id string read-only example: 1
      Id of the filter. Does not need to be included when creating article.
    • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
      Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
    • nameDE string read-only example: shop
      Name of the filter in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the filter in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the filter in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the filter in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this filter.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the filter is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • bookingCategories array of ArticleCategoryRef
    Categories used for Online Booking of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • searchTags array of string
    Search tags make it easier for your customer to find your product in the online shop
  • shippingInfo object
    shipping information for an article.
    show fields
    • shippingAttributes array of string
      List of attributes used for shipping
    • weightUnit string
      Weight unit used for shipping of the article
      Allowed values: GRAM, KILOGRAM
    • dimensionUnit string
      Dimension unit used for shipping of the article
      Allowed values: CENTIMETER, METER
    • weight number pattern: ^\d{1,19}([.]\d{1,2})?$
      Weight of this article
    • width number pattern: ^\d{1,19}([.]\d{1,2})?$
      Width of this article
    • height number pattern: ^\d{1,19}([.]\d{1,2})?$
      Height of this article
    • depth number pattern: ^\d{1,19}([.]\d{1,2})?$
      Depth of this article
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
  • vats array of ArticleVat
    VAT information for the article
    show fields

    Array of ArticleVat.

    • vatType object example: NORMAL
      Article vat type of the article
    • vatCase string example: TAXABLE_SUPPLY
      VAT case of the article
    • vatCode string example: 1
      VAT code of the article VAT
    • sss1 boolean example: False
      Reporting net tax rate with SSS1 option
    • sss2 boolean example: False
      Reporting net tax rate with SSS2 option
    • reportingNetTaxRate boolean example: False
      Using VAT reporting net tax rate option
    • excludeVat boolean example: False
      Using exclude VAT option
  • numberType object
    Inventory Number Type
    Use either NO_NUMBER or SERIAL_NUMBER
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
PUT/core/latest/articles/{article-id}key / tokenUpdate an existing article
Parameters 1
NameDescription
article-id required
path string
Request body required
The article object with the information that needs to be updated

application/json Article

  • id string read-only example: 1
    Id of the article. Does not need to be included when creating article
  • nameDE string required
    Name of the article in German
  • nameEN string
    Name of the article in English
  • nameFR string
    Name of the article in French
  • nameIT string
    Name of the article in Italian
  • descriptionDE string
    Description of the article in German
  • descriptionEN string
    Description of the article in English
  • descriptionFR string
    Description of the article in French
  • descriptionIT string
    Description of the article in Italian
  • extendedDescriptionDE string
    Extended description of the article in German
  • extendedDescriptionEN string
    Extended description of the article in English
  • extendedDescriptionFR string
    Extended description of the article in French
  • extendedDescriptionIT string
    Extended description of the article in Italian
  • unitDE string required
    Unit of the article in German
  • unitEN string
    Unit of the article in English
  • unitFR string
    Unit of the article in French
  • unitIT string
    Unit of the article in Italian
  • barcode string
    Barcode of the article
  • usePos boolean
    Decides if this article is used for POS or not
  • pricePeriods array of PricePeriod
    Price periods for the article.
    If article only has single price period, ignore and don't include validFrom and validTo in the PricePeriod.
    If article have different prices valid for different periods, set value for validFrom for each price period or that price period is ignored.
    show fields

    Array of PricePeriod.

    • validFrom string (date) format: date
      The price period is valid from this time
    • validTo string (date) format: date read-only
      The price period is invalid after this time
    • price number pattern: ^\d{1,19}([.]\d{1,2})?$
      The price used for an article within this price period
    • priceCategories array of PriceCategory
      List of price categories effective for this price period
      show fields

      Array of PriceCategory.

      • name string
        Name of the price category
      • price number pattern: ^\d{1,19}([.]\d{1,2})?$
        Effective price of this price category
  • options array of ArticleOption
    Options for the article. If specify, variants for this article will be generated.
    show fields

    Array of ArticleOption.

    • name string example: color
      Name of the article option
    • values array of string
      Available choices for the article option
  • imageHrefs array of string read-only
    Reference uris for the images of this article if present.
  • isArticleSet boolean
    Decides if this article is an article set
  • articleSetName string
    Name of the article set. Does not need to be included if article is not an article set.
  • defaultQuantity number pattern: ^\d{1,19}([.]\d{1,2})?$
    The default quantity of the article
  • accountingTags array of string required
    Tags used for accounting. Articles with the same tag, same VAT case and same VAT rate are grouped together in the posting
  • articleNumber string required example: ABC123
    Article number
  • hasVariant boolean
    Specify if the article has variants or not
  • includedInArticleSets array of string
    Names of the article sets that the article is included in.
    If the article have some variants, then only the variants will show the article set name they belong to, not the parent article (null value is shown).
  • sellInOnlineShop boolean
    Specify if the article is able to be sold on the Online shop or not
  • isAdultArticle boolean
    Specify if the article is only used for adult or not
  • productType object required
    Type of product used for an article
  • posCategories array of ArticleCategoryRef
    Categories used for Point of Sale of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • posFilters array of ArticleFilterRef
    Filters used for Point of Sale of the article
    Provide only either id or href of each filter when creating Article
    show fields

    Array of ArticleFilterRef.

    • id string read-only example: 1
      Id of the filter. Does not need to be included when creating article.
    • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
      Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
    • nameDE string read-only example: shop
      Name of the filter in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the filter in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the filter in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the filter in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this filter.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the filter is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • onlineShopCategories array of ArticleCategoryRef
    Categories used for Online shop of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • onlineShopFilters array of ArticleFilterRef
    Filters used for Online shop of the article
    Provide only either id or href of each filter when creating Article
    show fields

    Array of ArticleFilterRef.

    • id string read-only example: 1
      Id of the filter. Does not need to be included when creating article.
    • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
      Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
    • nameDE string read-only example: shop
      Name of the filter in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the filter in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the filter in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the filter in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this filter.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the filter is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • bookingCategories array of ArticleCategoryRef
    Categories used for Online Booking of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • searchTags array of string
    Search tags make it easier for your customer to find your product in the online shop
  • shippingInfo object
    shipping information for an article.
    show fields
    • shippingAttributes array of string
      List of attributes used for shipping
    • weightUnit string
      Weight unit used for shipping of the article
      Allowed values: GRAM, KILOGRAM
    • dimensionUnit string
      Dimension unit used for shipping of the article
      Allowed values: CENTIMETER, METER
    • weight number pattern: ^\d{1,19}([.]\d{1,2})?$
      Weight of this article
    • width number pattern: ^\d{1,19}([.]\d{1,2})?$
      Width of this article
    • height number pattern: ^\d{1,19}([.]\d{1,2})?$
      Height of this article
    • depth number pattern: ^\d{1,19}([.]\d{1,2})?$
      Depth of this article
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
  • vats array of ArticleVat
    VAT information for the article
    show fields

    Array of ArticleVat.

    • vatType object example: NORMAL
      Article vat type of the article
    • vatCase string example: TAXABLE_SUPPLY
      VAT case of the article
    • vatCode string example: 1
      VAT code of the article VAT
    • sss1 boolean example: False
      Reporting net tax rate with SSS1 option
    • sss2 boolean example: False
      Reporting net tax rate with SSS2 option
    • reportingNetTaxRate boolean example: False
      Using VAT reporting net tax rate option
    • excludeVat boolean example: False
      Using exclude VAT option
  • numberType object
    Inventory Number Type
    Use either NO_NUMBER or SERIAL_NUMBER
Responses 5
200 Article updated show body

application/json Article

  • id string read-only example: 1
    Id of the article. Does not need to be included when creating article
  • nameDE string required
    Name of the article in German
  • nameEN string
    Name of the article in English
  • nameFR string
    Name of the article in French
  • nameIT string
    Name of the article in Italian
  • descriptionDE string
    Description of the article in German
  • descriptionEN string
    Description of the article in English
  • descriptionFR string
    Description of the article in French
  • descriptionIT string
    Description of the article in Italian
  • extendedDescriptionDE string
    Extended description of the article in German
  • extendedDescriptionEN string
    Extended description of the article in English
  • extendedDescriptionFR string
    Extended description of the article in French
  • extendedDescriptionIT string
    Extended description of the article in Italian
  • unitDE string required
    Unit of the article in German
  • unitEN string
    Unit of the article in English
  • unitFR string
    Unit of the article in French
  • unitIT string
    Unit of the article in Italian
  • barcode string
    Barcode of the article
  • usePos boolean
    Decides if this article is used for POS or not
  • pricePeriods array of PricePeriod
    Price periods for the article.
    If article only has single price period, ignore and don't include validFrom and validTo in the PricePeriod.
    If article have different prices valid for different periods, set value for validFrom for each price period or that price period is ignored.
    show fields

    Array of PricePeriod.

    • validFrom string (date) format: date
      The price period is valid from this time
    • validTo string (date) format: date read-only
      The price period is invalid after this time
    • price number pattern: ^\d{1,19}([.]\d{1,2})?$
      The price used for an article within this price period
    • priceCategories array of PriceCategory
      List of price categories effective for this price period
      show fields

      Array of PriceCategory.

      • name string
        Name of the price category
      • price number pattern: ^\d{1,19}([.]\d{1,2})?$
        Effective price of this price category
  • options array of ArticleOption
    Options for the article. If specify, variants for this article will be generated.
    show fields

    Array of ArticleOption.

    • name string example: color
      Name of the article option
    • values array of string
      Available choices for the article option
  • imageHrefs array of string read-only
    Reference uris for the images of this article if present.
  • isArticleSet boolean
    Decides if this article is an article set
  • articleSetName string
    Name of the article set. Does not need to be included if article is not an article set.
  • defaultQuantity number pattern: ^\d{1,19}([.]\d{1,2})?$
    The default quantity of the article
  • accountingTags array of string required
    Tags used for accounting. Articles with the same tag, same VAT case and same VAT rate are grouped together in the posting
  • articleNumber string required example: ABC123
    Article number
  • hasVariant boolean
    Specify if the article has variants or not
  • includedInArticleSets array of string
    Names of the article sets that the article is included in.
    If the article have some variants, then only the variants will show the article set name they belong to, not the parent article (null value is shown).
  • sellInOnlineShop boolean
    Specify if the article is able to be sold on the Online shop or not
  • isAdultArticle boolean
    Specify if the article is only used for adult or not
  • productType object required
    Type of product used for an article
  • posCategories array of ArticleCategoryRef
    Categories used for Point of Sale of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • posFilters array of ArticleFilterRef
    Filters used for Point of Sale of the article
    Provide only either id or href of each filter when creating Article
    show fields

    Array of ArticleFilterRef.

    • id string read-only example: 1
      Id of the filter. Does not need to be included when creating article.
    • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
      Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
    • nameDE string read-only example: shop
      Name of the filter in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the filter in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the filter in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the filter in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this filter.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the filter is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • onlineShopCategories array of ArticleCategoryRef
    Categories used for Online shop of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • onlineShopFilters array of ArticleFilterRef
    Filters used for Online shop of the article
    Provide only either id or href of each filter when creating Article
    show fields

    Array of ArticleFilterRef.

    • id string read-only example: 1
      Id of the filter. Does not need to be included when creating article.
    • filter_href string required write-only example: https://api.klara.ch/core/latest/article-filters/1
      Reference uri for an article filter. If specified, this article will be assigned to the entered article filter.
    • nameDE string read-only example: shop
      Name of the filter in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the filter in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the filter in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the filter in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this filter.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the filter is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • bookingCategories array of ArticleCategoryRef
    Categories used for Online Booking of the article
    Provide only either id or href of each category when creating Article
    show fields

    Array of ArticleCategoryRef.

    • id string read-only example: 1
      Id of the category. Does not need to be included when creating article
    • category_href string required write-only example: https://api.klara.ch/core/latest/article-categories/1
      Reference uri for an article category. If specified, this article will be assigned to the entered article category.
    • nameDE string read-only example: shop
      Name of the category in german.
      Does not need to be included when creating article.
    • nameEN string read-only example: shop
      Name of the category in english.
      Does not need to be included when creating article.
    • nameFR string read-only example: shop
      Name of the category in french.
      Does not need to be included when creating article.
    • nameIT string read-only example: shop
      Name of the category in italy.
      Does not need to be included when creating article.
    • order integer (int32) format: int32 read-only
      Order of this category.
      Does not need to be included when creating article.
    • active boolean read-only
      Indicates if the category is active or not
    • _links object
      links metadata
      show fields
      • self Link
        Link metadata
        show fields
        • href string
  • searchTags array of string
    Search tags make it easier for your customer to find your product in the online shop
  • shippingInfo object
    shipping information for an article.
    show fields
    • shippingAttributes array of string
      List of attributes used for shipping
    • weightUnit string
      Weight unit used for shipping of the article
      Allowed values: GRAM, KILOGRAM
    • dimensionUnit string
      Dimension unit used for shipping of the article
      Allowed values: CENTIMETER, METER
    • weight number pattern: ^\d{1,19}([.]\d{1,2})?$
      Weight of this article
    • width number pattern: ^\d{1,19}([.]\d{1,2})?$
      Width of this article
    • height number pattern: ^\d{1,19}([.]\d{1,2})?$
      Height of this article
    • depth number pattern: ^\d{1,19}([.]\d{1,2})?$
      Depth of this article
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
  • vats array of ArticleVat
    VAT information for the article
    show fields

    Array of ArticleVat.

    • vatType object example: NORMAL
      Article vat type of the article
    • vatCase string example: TAXABLE_SUPPLY
      VAT case of the article
    • vatCode string example: 1
      VAT code of the article VAT
    • sss1 boolean example: False
      Reporting net tax rate with SSS1 option
    • sss2 boolean example: False
      Reporting net tax rate with SSS2 option
    • reportingNetTaxRate boolean example: False
      Using VAT reporting net tax rate option
    • excludeVat boolean example: False
      Using exclude VAT option
  • numberType object
    Inventory Number Type
    Use either NO_NUMBER or SERIAL_NUMBER
400 Data invalid show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
GET/core/latest/articles/{article-id}/article-set-itemskey / tokenGet list of items from article set
Parameters 1
NameDescription
article-id required
path string
Responses 5
200 Return successfully show body

application/json array of PublicApiArticleSetItem

Array of PublicApiArticleSetItem.

  • id string example: 1
    Id of the article set
  • articleName string example: Mobile phone
    Article name of the article
  • number string example: 1
    The number of the article
  • productType object example: PRODUCTION
    Type of product used for an article
  • price number
    Price of the article
  • vat object
    Vat of the article
    show fields
    • vatType object example: NORMAL
      Article vat type of the article
    • vatCase string example: TAXABLE_SUPPLY
      VAT case of the article
    • vatCode string example: 1
      VAT code of the article VAT
    • sss1 boolean example: False
      Reporting net tax rate with SSS1 option
    • sss2 boolean example: False
      Reporting net tax rate with SSS2 option
    • reportingNetTaxRate boolean example: False
      Using VAT reporting net tax rate option
    • excludeVat boolean example: False
      Using exclude VAT option
  • optionValues array of string
    Options for the set item if it is a variant
  • href string example: https://api.klara.ch/core/latest/articles/1
    Reference resource link
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
POST/core/latest/articles/{article-id}/imageskey / tokenAdd an image to an article
Image size limit: 5MB
Supported image type: PNG, JPG, JPEG
Parameters 1
NameDescription
article-id required
path string
Id of the article to add an image to
example: 1
Request body required

multipart/form-data BinaryFile

  • file string (binary) format: binary
Responses 7
201 Image added for article show body

application/json ArticleImage

  • imageId string
400 Data invalid show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
415 Unsupported Media Type no response body
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. no response body
DELETE/core/latest/articles/{article-id}/images/{image-id}key / tokenDelete an article image
Parameters 2
NameDescription
article-id required
path string
Id of the article to delete an image from
example: 1
image-id required
path string
Id of the image to delete
example: 1
Responses 7
204 Image deleted for given article no response body
400 Data invalid show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 The image of the article or the article itself could not be found. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. no response body
GET/core/latest/articles/{article-id}/images/{image-id}key / tokenGet the content of an article image
Parameters 2
NameDescription
article-id required
path string
Id of the article to get an image from
example: 1
image-id required
path string
Id of the image to get the content from
example: 1
Responses 6
200 Content of an article image show body

application/octet-stream any

401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 The image of the article or the article itself could not be found. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. no response body
PUT/core/latest/articles/{article-id}/images/{image-id}key / tokenUpdate an article image
Image size limit: 5MB
Supported image type: PNG, JPG, JPEG
Parameters 2
NameDescription
article-id required
path string
Id of the article to update an image
example: 1
image-id required
path string
Id of the image to update
example: 1
Request body required

multipart/form-data BinaryFile

  • file string (binary) format: binary
Responses 8
200 Image updated for article show body

application/json ArticleImage

  • imageId string
400 Data invalid show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 The image of the article or the article itself could not be found. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
415 Unsupported Media Type no response body
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. no response body
GET/core/latest/articles/{article-id}/variantskey / tokenGet variants of an article
Parameters 1
NameDescription
article-id required
path string
Responses 5
200 Found variants show body

application/json array of Variant

Array of Variant.

  • id string example: 1
    Id of the variant
  • number string required example: ABC123
    Article number
  • barcode string default:
    Barcode for the variant
  • accountingTags array of string required
    Tags used for accounting. Articles with the same tag, same VAT case and same VAT rate are grouped together in the posting
  • articleSets array of string
    Name of the article sets that the variant is included in
  • defaultQuantity number
    The default quantity of the article
  • active boolean default: false
    Decide if this variant is active or not
  • pricePeriods array of PricePeriod
    Price periods for the article variant.
    If variant only has 1 price, don't include validFrom and validTo in the PricePeriod.
    If variant have many prices, set value for validFrom for the date that the price is active for each PricePeriod.
    show fields

    Array of PricePeriod.

    • validFrom string (date) format: date
      The price period is valid from this time
    • validTo string (date) format: date read-only
      The price period is invalid after this time
    • price number pattern: ^\d{1,19}([.]\d{1,2})?$
      The price used for an article within this price period
    • priceCategories array of PriceCategory
      List of price categories effective for this price period
      show fields

      Array of PriceCategory.

      • name string
        Name of the price category
      • price number pattern: ^\d{1,19}([.]\d{1,2})?$
        Effective price of this price category
  • variantOptionValues array of string
    Values for the options that this article variant represent
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
GET/core/latest/articles/{article-id}/variants/{variant-id}key / tokenGet variants of an article with id
Parameters 2
NameDescription
article-id required
path string
variant-id required
path string
Responses 5
200 Found article variant show body

application/json Variant

  • id string example: 1
    Id of the variant
  • number string required example: ABC123
    Article number
  • barcode string default:
    Barcode for the variant
  • accountingTags array of string required
    Tags used for accounting. Articles with the same tag, same VAT case and same VAT rate are grouped together in the posting
  • articleSets array of string
    Name of the article sets that the variant is included in
  • defaultQuantity number
    The default quantity of the article
  • active boolean default: false
    Decide if this variant is active or not
  • pricePeriods array of PricePeriod
    Price periods for the article variant.
    If variant only has 1 price, don't include validFrom and validTo in the PricePeriod.
    If variant have many prices, set value for validFrom for the date that the price is active for each PricePeriod.
    show fields

    Array of PricePeriod.

    • validFrom string (date) format: date
      The price period is valid from this time
    • validTo string (date) format: date read-only
      The price period is invalid after this time
    • price number pattern: ^\d{1,19}([.]\d{1,2})?$
      The price used for an article within this price period
    • priceCategories array of PriceCategory
      List of price categories effective for this price period
      show fields

      Array of PriceCategory.

      • name string
        Name of the price category
      • price number pattern: ^\d{1,19}([.]\d{1,2})?$
        Effective price of this price category
  • variantOptionValues array of string
    Values for the options that this article variant represent
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body

Customer14

GET/core/latest/customerskey / tokenReturns all customers of a company
Responses 4
200 Customers show body

application/json array of Customer

Array of Customer.

  • id string read-only example: 1
    Id of this Customer. Does not need to be included when creating customer
  • person object
    A partner person.
    show fields
    • website string example: www.my-company.com
      The website address of this customer
    • categories array of string
      Add one or more categories to this customer that you can use as filter criteria for selecting partners
    • onlinePlatforms array of OnlinePlatform
      The list of online platforms that this customer uses
      show fields

      Array of OnlinePlatform.

      • id string read-only example: 1
        Id of this Online platform. Does not need to be included when creating Customer.
      • platformName object example: FACEBOOK
        Name of the platform that this customer uses
      • platformValue string example: www.linkedin.com/abc
        Url of customer's online platform/webpage
    • language string example: en
      The main language that this partner uses, valid values is [en, de, fr, it]
    • responsibleCounterpart string example: Mr. Marc
      The name of a contact person for this customer
    • correspondence object required example: MAIL
      The preferred method of correspondence, how this customer wants to receive the pay slips by default
    • id string example: 1
      Id of this person. Does not need to be included when creating customer
    • salutation object required example: MALE
      Salutation for this person, valid values is: [MALE, FEMALE, MALE_FEMALE, FAMILY]
    • firstName string required pattern: \S example: John
      First name of this person
    • lastName string required pattern: \S example: Henry
      Last name of this person
    • birthday string (date) format: date example: 2020-01-20
      Birth date of this person in ISO 8601 format (yyyy-MM-dd)
    • addresses array of Address
      Address list of this person
      show fields

      Array of Address.

      • id string example: 1
        Id of this Address. Does not need to be included when creating customer
      • validFrom string (date) format: date
        The timestamp from which this address is valid
      • validTo string (date) format: date
        The timestamp to which this address is valid
      • addressLines string required example: Chemin de la Caquerette 12
        The address lines for this Address
      • addressType string required pattern: \S example: WORK
        The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
      • cityName string required pattern: \S example: Bern
        Name of this City
      • cityZipCode string example: 3003
        The postal code of a city for this address
      • countryIso2Code string required pattern: \S example: CH
        2 letter country code. For company, only accept Switzerland
      • countryIso3Code string example: CHE
        3 letter country code. For company, only accept Switzerland
      • countryNumericCode string example: 756
        ISO-numeric code. For company, only accept Switzerland
      • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
        The path to get City object by city's id, /cities/{}
      • definitionName string example: 2nd address
        definition name of this address; in case main address, value is null; else value is not blank
      • additionalAddress string example: No. 13, street 123
        Additional address for more specific
    • phones array of Phone
      Phone number list of this person
      show fields

      Array of Phone.

      • id string example: 1
        Id of this Phone. Does not need to be included when creating customer.
      • phoneNumber string required example: 41783334444
      • type object required example: PRIVATE
        Type of this phone number. For company, only OFFICE type is supported
    • emails array of Email
      Email list of this person
      show fields

      Array of Email.

      • id string example: 1
        Id of this Email. Does not need to be included when creating customer
      • emailAddress string example: example@gmail.com
        Email address
      • type object required example: PRIVATE
        Type of this email
    • personNumber string
      This is a number the KLARA user can give to this customer/partner/supplier
  • company object
    A company.
    show fields
    • website string example: www.my-company.com
      The website address of this customer
    • categories array of string
      Add one or more categories to this customer that you can use as filter criteria for selecting partners
    • onlinePlatforms array of OnlinePlatform
      The list of online platforms that this customer uses
      show fields

      Array of OnlinePlatform.

      • id string read-only example: 1
        Id of this Online platform. Does not need to be included when creating Customer.
      • platformName object example: FACEBOOK
        Name of the platform that this customer uses
      • platformValue string example: www.linkedin.com/abc
        Url of customer's online platform/webpage
    • language string example: en
      The main language that this partner uses, valid values is [en, de, fr, it]
    • responsibleCounterpart string example: Mr. Marc
      The name of a contact person for this customer
    • correspondence object required example: MAIL
      The preferred method of correspondence, how this customer wants to receive the pay slips by default
    • id string read-only example: 1
      Id of this company. Does not need to be included when creating customer
    • name string required pattern: \S example: ABC-Corp
      Name of the company
    • phones array of Phone
      Phone numbers of the company
      show fields

      Array of Phone.

      • id string example: 1
        Id of this Phone. Does not need to be included when creating customer.
      • phoneNumber string required example: 41783334444
      • type object required example: PRIVATE
        Type of this phone number. For company, only OFFICE type is supported
    • emails array of Email
      Emails of this company
      show fields

      Array of Email.

      • id string example: 1
        Id of this Email. Does not need to be included when creating customer
      • emailAddress string example: example@gmail.com
        Email address
      • type object required example: PRIVATE
        Type of this email
    • addresses array of Address
      Address list of this company, atleast one should be add
      show fields

      Array of Address.

      • id string example: 1
        Id of this Address. Does not need to be included when creating customer
      • validFrom string (date) format: date
        The timestamp from which this address is valid
      • validTo string (date) format: date
        The timestamp to which this address is valid
      • addressLines string required example: Chemin de la Caquerette 12
        The address lines for this Address
      • addressType string required pattern: \S example: WORK
        The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
      • cityName string required pattern: \S example: Bern
        Name of this City
      • cityZipCode string example: 3003
        The postal code of a city for this address
      • countryIso2Code string required pattern: \S example: CH
        2 letter country code. For company, only accept Switzerland
      • countryIso3Code string example: CHE
        3 letter country code. For company, only accept Switzerland
      • countryNumericCode string example: 756
        ISO-numeric code. For company, only accept Switzerland
      • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
        The path to get City object by city's id, /cities/{}
      • definitionName string example: 2nd address
        definition name of this address; in case main address, value is null; else value is not blank
      • additionalAddress string example: No. 13, street 123
        Additional address for more specific
    • corporateIdentificationNumber string example: CHE-123.456.789
      Every business active in Switzerland is given a unique enterprise identification number (UID). To ensure that numbers are correctly allocated and managed, the UID register is run by the Federal Statistical Office
    • vatNumber string example: CHE-123.456.789
      This is the official CH VAT number of the company
    • hrNumber string example: CHE-123.456.789
      This is the official CH number for this company in the CH trade register
    • nogaCode string example: 1234
      The NOGA code of this company
    • foundingDate string (date) format: date example: 2019-12-20
      Founding date of this comany in ISO 8601 format (yyyy-mm-dd)
    • companyNumber string
      This is a number the KLARA user can give to this customer/partner/supplier
  • priceCategory string example: Sale price
    You can select / enter a price category. On the articles you can define a special price for this price category. When such an article is sold / invoiced, the price of this category will apply if it is identical for the article and the customer.
  • customerType object required example: PERSON
    The type of this partner. Could be either Person or Company.
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
POST/core/latest/customerskey / tokenCreate a new customer
Request body required
The customer object with the information that needs to be created

application/json Customer

  • id string read-only example: 1
    Id of this Customer. Does not need to be included when creating customer
  • person object
    A partner person.
    show fields
    • website string example: www.my-company.com
      The website address of this customer
    • categories array of string
      Add one or more categories to this customer that you can use as filter criteria for selecting partners
    • onlinePlatforms array of OnlinePlatform
      The list of online platforms that this customer uses
      show fields

      Array of OnlinePlatform.

      • id string read-only example: 1
        Id of this Online platform. Does not need to be included when creating Customer.
      • platformName object example: FACEBOOK
        Name of the platform that this customer uses
      • platformValue string example: www.linkedin.com/abc
        Url of customer's online platform/webpage
    • language string example: en
      The main language that this partner uses, valid values is [en, de, fr, it]
    • responsibleCounterpart string example: Mr. Marc
      The name of a contact person for this customer
    • correspondence object required example: MAIL
      The preferred method of correspondence, how this customer wants to receive the pay slips by default
    • id string example: 1
      Id of this person. Does not need to be included when creating customer
    • salutation object required example: MALE
      Salutation for this person, valid values is: [MALE, FEMALE, MALE_FEMALE, FAMILY]
    • firstName string required pattern: \S example: John
      First name of this person
    • lastName string required pattern: \S example: Henry
      Last name of this person
    • birthday string (date) format: date example: 2020-01-20
      Birth date of this person in ISO 8601 format (yyyy-MM-dd)
    • addresses array of Address
      Address list of this person
      show fields

      Array of Address.

      • id string example: 1
        Id of this Address. Does not need to be included when creating customer
      • validFrom string (date) format: date
        The timestamp from which this address is valid
      • validTo string (date) format: date
        The timestamp to which this address is valid
      • addressLines string required example: Chemin de la Caquerette 12
        The address lines for this Address
      • addressType string required pattern: \S example: WORK
        The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
      • cityName string required pattern: \S example: Bern
        Name of this City
      • cityZipCode string example: 3003
        The postal code of a city for this address
      • countryIso2Code string required pattern: \S example: CH
        2 letter country code. For company, only accept Switzerland
      • countryIso3Code string example: CHE
        3 letter country code. For company, only accept Switzerland
      • countryNumericCode string example: 756
        ISO-numeric code. For company, only accept Switzerland
      • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
        The path to get City object by city's id, /cities/{}
      • definitionName string example: 2nd address
        definition name of this address; in case main address, value is null; else value is not blank
      • additionalAddress string example: No. 13, street 123
        Additional address for more specific
    • phones array of Phone
      Phone number list of this person
      show fields

      Array of Phone.

      • id string example: 1
        Id of this Phone. Does not need to be included when creating customer.
      • phoneNumber string required example: 41783334444
      • type object required example: PRIVATE
        Type of this phone number. For company, only OFFICE type is supported
    • emails array of Email
      Email list of this person
      show fields

      Array of Email.

      • id string example: 1
        Id of this Email. Does not need to be included when creating customer
      • emailAddress string example: example@gmail.com
        Email address
      • type object required example: PRIVATE
        Type of this email
    • personNumber string
      This is a number the KLARA user can give to this customer/partner/supplier
  • company object
    A company.
    show fields
    • website string example: www.my-company.com
      The website address of this customer
    • categories array of string
      Add one or more categories to this customer that you can use as filter criteria for selecting partners
    • onlinePlatforms array of OnlinePlatform
      The list of online platforms that this customer uses
      show fields

      Array of OnlinePlatform.

      • id string read-only example: 1
        Id of this Online platform. Does not need to be included when creating Customer.
      • platformName object example: FACEBOOK
        Name of the platform that this customer uses
      • platformValue string example: www.linkedin.com/abc
        Url of customer's online platform/webpage
    • language string example: en
      The main language that this partner uses, valid values is [en, de, fr, it]
    • responsibleCounterpart string example: Mr. Marc
      The name of a contact person for this customer
    • correspondence object required example: MAIL
      The preferred method of correspondence, how this customer wants to receive the pay slips by default
    • id string read-only example: 1
      Id of this company. Does not need to be included when creating customer
    • name string required pattern: \S example: ABC-Corp
      Name of the company
    • phones array of Phone
      Phone numbers of the company
      show fields

      Array of Phone.

      • id string example: 1
        Id of this Phone. Does not need to be included when creating customer.
      • phoneNumber string required example: 41783334444
      • type object required example: PRIVATE
        Type of this phone number. For company, only OFFICE type is supported
    • emails array of Email
      Emails of this company
      show fields

      Array of Email.

      • id string example: 1
        Id of this Email. Does not need to be included when creating customer
      • emailAddress string example: example@gmail.com
        Email address
      • type object required example: PRIVATE
        Type of this email
    • addresses array of Address
      Address list of this company, atleast one should be add
      show fields

      Array of Address.

      • id string example: 1
        Id of this Address. Does not need to be included when creating customer
      • validFrom string (date) format: date
        The timestamp from which this address is valid
      • validTo string (date) format: date
        The timestamp to which this address is valid
      • addressLines string required example: Chemin de la Caquerette 12
        The address lines for this Address
      • addressType string required pattern: \S example: WORK
        The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
      • cityName string required pattern: \S example: Bern
        Name of this City
      • cityZipCode string example: 3003
        The postal code of a city for this address
      • countryIso2Code string required pattern: \S example: CH
        2 letter country code. For company, only accept Switzerland
      • countryIso3Code string example: CHE
        3 letter country code. For company, only accept Switzerland
      • countryNumericCode string example: 756
        ISO-numeric code. For company, only accept Switzerland
      • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
        The path to get City object by city's id, /cities/{}
      • definitionName string example: 2nd address
        definition name of this address; in case main address, value is null; else value is not blank
      • additionalAddress string example: No. 13, street 123
        Additional address for more specific
    • corporateIdentificationNumber string example: CHE-123.456.789
      Every business active in Switzerland is given a unique enterprise identification number (UID). To ensure that numbers are correctly allocated and managed, the UID register is run by the Federal Statistical Office
    • vatNumber string example: CHE-123.456.789
      This is the official CH VAT number of the company
    • hrNumber string example: CHE-123.456.789
      This is the official CH number for this company in the CH trade register
    • nogaCode string example: 1234
      The NOGA code of this company
    • foundingDate string (date) format: date example: 2019-12-20
      Founding date of this comany in ISO 8601 format (yyyy-mm-dd)
    • companyNumber string
      This is a number the KLARA user can give to this customer/partner/supplier
  • priceCategory string example: Sale price
    You can select / enter a price category. On the articles you can define a special price for this price category. When such an article is sold / invoiced, the price of this category will apply if it is identical for the article and the customer.
  • customerType object required example: PERSON
    The type of this partner. Could be either Person or Company.
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
Responses 5
201 Customer created show body

application/json Customer

  • id string read-only example: 1
    Id of this Customer. Does not need to be included when creating customer
  • person object
    A partner person.
    show fields
    • website string example: www.my-company.com
      The website address of this customer
    • categories array of string
      Add one or more categories to this customer that you can use as filter criteria for selecting partners
    • onlinePlatforms array of OnlinePlatform
      The list of online platforms that this customer uses
      show fields

      Array of OnlinePlatform.

      • id string read-only example: 1
        Id of this Online platform. Does not need to be included when creating Customer.
      • platformName object example: FACEBOOK
        Name of the platform that this customer uses
      • platformValue string example: www.linkedin.com/abc
        Url of customer's online platform/webpage
    • language string example: en
      The main language that this partner uses, valid values is [en, de, fr, it]
    • responsibleCounterpart string example: Mr. Marc
      The name of a contact person for this customer
    • correspondence object required example: MAIL
      The preferred method of correspondence, how this customer wants to receive the pay slips by default
    • id string example: 1
      Id of this person. Does not need to be included when creating customer
    • salutation object required example: MALE
      Salutation for this person, valid values is: [MALE, FEMALE, MALE_FEMALE, FAMILY]
    • firstName string required pattern: \S example: John
      First name of this person
    • lastName string required pattern: \S example: Henry
      Last name of this person
    • birthday string (date) format: date example: 2020-01-20
      Birth date of this person in ISO 8601 format (yyyy-MM-dd)
    • addresses array of Address
      Address list of this person
      show fields

      Array of Address.

      • id string example: 1
        Id of this Address. Does not need to be included when creating customer
      • validFrom string (date) format: date
        The timestamp from which this address is valid
      • validTo string (date) format: date
        The timestamp to which this address is valid
      • addressLines string required example: Chemin de la Caquerette 12
        The address lines for this Address
      • addressType string required pattern: \S example: WORK
        The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
      • cityName string required pattern: \S example: Bern
        Name of this City
      • cityZipCode string example: 3003
        The postal code of a city for this address
      • countryIso2Code string required pattern: \S example: CH
        2 letter country code. For company, only accept Switzerland
      • countryIso3Code string example: CHE
        3 letter country code. For company, only accept Switzerland
      • countryNumericCode string example: 756
        ISO-numeric code. For company, only accept Switzerland
      • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
        The path to get City object by city's id, /cities/{}
      • definitionName string example: 2nd address
        definition name of this address; in case main address, value is null; else value is not blank
      • additionalAddress string example: No. 13, street 123
        Additional address for more specific
    • phones array of Phone
      Phone number list of this person
      show fields

      Array of Phone.

      • id string example: 1
        Id of this Phone. Does not need to be included when creating customer.
      • phoneNumber string required example: 41783334444
      • type object required example: PRIVATE
        Type of this phone number. For company, only OFFICE type is supported
    • emails array of Email
      Email list of this person
      show fields

      Array of Email.

      • id string example: 1
        Id of this Email. Does not need to be included when creating customer
      • emailAddress string example: example@gmail.com
        Email address
      • type object required example: PRIVATE
        Type of this email
    • personNumber string
      This is a number the KLARA user can give to this customer/partner/supplier
  • company object
    A company.
    show fields
    • website string example: www.my-company.com
      The website address of this customer
    • categories array of string
      Add one or more categories to this customer that you can use as filter criteria for selecting partners
    • onlinePlatforms array of OnlinePlatform
      The list of online platforms that this customer uses
      show fields

      Array of OnlinePlatform.

      • id string read-only example: 1
        Id of this Online platform. Does not need to be included when creating Customer.
      • platformName object example: FACEBOOK
        Name of the platform that this customer uses
      • platformValue string example: www.linkedin.com/abc
        Url of customer's online platform/webpage
    • language string example: en
      The main language that this partner uses, valid values is [en, de, fr, it]
    • responsibleCounterpart string example: Mr. Marc
      The name of a contact person for this customer
    • correspondence object required example: MAIL
      The preferred method of correspondence, how this customer wants to receive the pay slips by default
    • id string read-only example: 1
      Id of this company. Does not need to be included when creating customer
    • name string required pattern: \S example: ABC-Corp
      Name of the company
    • phones array of Phone
      Phone numbers of the company
      show fields

      Array of Phone.

      • id string example: 1
        Id of this Phone. Does not need to be included when creating customer.
      • phoneNumber string required example: 41783334444
      • type object required example: PRIVATE
        Type of this phone number. For company, only OFFICE type is supported
    • emails array of Email
      Emails of this company
      show fields

      Array of Email.

      • id string example: 1
        Id of this Email. Does not need to be included when creating customer
      • emailAddress string example: example@gmail.com
        Email address
      • type object required example: PRIVATE
        Type of this email
    • addresses array of Address
      Address list of this company, atleast one should be add
      show fields

      Array of Address.

      • id string example: 1
        Id of this Address. Does not need to be included when creating customer
      • validFrom string (date) format: date
        The timestamp from which this address is valid
      • validTo string (date) format: date
        The timestamp to which this address is valid
      • addressLines string required example: Chemin de la Caquerette 12
        The address lines for this Address
      • addressType string required pattern: \S example: WORK
        The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
      • cityName string required pattern: \S example: Bern
        Name of this City
      • cityZipCode string example: 3003
        The postal code of a city for this address
      • countryIso2Code string required pattern: \S example: CH
        2 letter country code. For company, only accept Switzerland
      • countryIso3Code string example: CHE
        3 letter country code. For company, only accept Switzerland
      • countryNumericCode string example: 756
        ISO-numeric code. For company, only accept Switzerland
      • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
        The path to get City object by city's id, /cities/{}
      • definitionName string example: 2nd address
        definition name of this address; in case main address, value is null; else value is not blank
      • additionalAddress string example: No. 13, street 123
        Additional address for more specific
    • corporateIdentificationNumber string example: CHE-123.456.789
      Every business active in Switzerland is given a unique enterprise identification number (UID). To ensure that numbers are correctly allocated and managed, the UID register is run by the Federal Statistical Office
    • vatNumber string example: CHE-123.456.789
      This is the official CH VAT number of the company
    • hrNumber string example: CHE-123.456.789
      This is the official CH number for this company in the CH trade register
    • nogaCode string example: 1234
      The NOGA code of this company
    • foundingDate string (date) format: date example: 2019-12-20
      Founding date of this comany in ISO 8601 format (yyyy-mm-dd)
    • companyNumber string
      This is a number the KLARA user can give to this customer/partner/supplier
  • priceCategory string example: Sale price
    You can select / enter a price category. On the articles you can define a special price for this price category. When such an article is sold / invoiced, the price of this category will apply if it is identical for the article and the customer.
  • customerType object required example: PERSON
    The type of this partner. Could be either Person or Company.
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
400 Data invalid show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
DELETE/core/latest/customers/{customer-id}key / tokenDelete a customer
Parameters 1
NameDescription
customer-id required
path string
Id of the customer to be deleted
example: 1
Responses 6
204 Customer deleted no response body
400 Could not delete Customer that contain orders show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found no response body
429 API rate limit exceeded no response body
GET/core/latest/customers/{customer-id}key / tokenReturns a customer of a company based on given id
Parameters 1
NameDescription
customer-id required
path string
Id of the customer
example: 1
Responses 5
200 Found Customer show body

application/json Customer

  • id string read-only example: 1
    Id of this Customer. Does not need to be included when creating customer
  • person object
    A partner person.
    show fields
    • website string example: www.my-company.com
      The website address of this customer
    • categories array of string
      Add one or more categories to this customer that you can use as filter criteria for selecting partners
    • onlinePlatforms array of OnlinePlatform
      The list of online platforms that this customer uses
      show fields

      Array of OnlinePlatform.

      • id string read-only example: 1
        Id of this Online platform. Does not need to be included when creating Customer.
      • platformName object example: FACEBOOK
        Name of the platform that this customer uses
      • platformValue string example: www.linkedin.com/abc
        Url of customer's online platform/webpage
    • language string example: en
      The main language that this partner uses, valid values is [en, de, fr, it]
    • responsibleCounterpart string example: Mr. Marc
      The name of a contact person for this customer
    • correspondence object required example: MAIL
      The preferred method of correspondence, how this customer wants to receive the pay slips by default
    • id string example: 1
      Id of this person. Does not need to be included when creating customer
    • salutation object required example: MALE
      Salutation for this person, valid values is: [MALE, FEMALE, MALE_FEMALE, FAMILY]
    • firstName string required pattern: \S example: John
      First name of this person
    • lastName string required pattern: \S example: Henry
      Last name of this person
    • birthday string (date) format: date example: 2020-01-20
      Birth date of this person in ISO 8601 format (yyyy-MM-dd)
    • addresses array of Address
      Address list of this person
      show fields

      Array of Address.

      • id string example: 1
        Id of this Address. Does not need to be included when creating customer
      • validFrom string (date) format: date
        The timestamp from which this address is valid
      • validTo string (date) format: date
        The timestamp to which this address is valid
      • addressLines string required example: Chemin de la Caquerette 12
        The address lines for this Address
      • addressType string required pattern: \S example: WORK
        The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
      • cityName string required pattern: \S example: Bern
        Name of this City
      • cityZipCode string example: 3003
        The postal code of a city for this address
      • countryIso2Code string required pattern: \S example: CH
        2 letter country code. For company, only accept Switzerland
      • countryIso3Code string example: CHE
        3 letter country code. For company, only accept Switzerland
      • countryNumericCode string example: 756
        ISO-numeric code. For company, only accept Switzerland
      • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
        The path to get City object by city's id, /cities/{}
      • definitionName string example: 2nd address
        definition name of this address; in case main address, value is null; else value is not blank
      • additionalAddress string example: No. 13, street 123
        Additional address for more specific
    • phones array of Phone
      Phone number list of this person
      show fields

      Array of Phone.

      • id string example: 1
        Id of this Phone. Does not need to be included when creating customer.
      • phoneNumber string required example: 41783334444
      • type object required example: PRIVATE
        Type of this phone number. For company, only OFFICE type is supported
    • emails array of Email
      Email list of this person
      show fields

      Array of Email.

      • id string example: 1
        Id of this Email. Does not need to be included when creating customer
      • emailAddress string example: example@gmail.com
        Email address
      • type object required example: PRIVATE
        Type of this email
    • personNumber string
      This is a number the KLARA user can give to this customer/partner/supplier
  • company object
    A company.
    show fields
    • website string example: www.my-company.com
      The website address of this customer
    • categories array of string
      Add one or more categories to this customer that you can use as filter criteria for selecting partners
    • onlinePlatforms array of OnlinePlatform
      The list of online platforms that this customer uses
      show fields

      Array of OnlinePlatform.

      • id string read-only example: 1
        Id of this Online platform. Does not need to be included when creating Customer.
      • platformName object example: FACEBOOK
        Name of the platform that this customer uses
      • platformValue string example: www.linkedin.com/abc
        Url of customer's online platform/webpage
    • language string example: en
      The main language that this partner uses, valid values is [en, de, fr, it]
    • responsibleCounterpart string example: Mr. Marc
      The name of a contact person for this customer
    • correspondence object required example: MAIL
      The preferred method of correspondence, how this customer wants to receive the pay slips by default
    • id string read-only example: 1
      Id of this company. Does not need to be included when creating customer
    • name string required pattern: \S example: ABC-Corp
      Name of the company
    • phones array of Phone
      Phone numbers of the company
      show fields

      Array of Phone.

      • id string example: 1
        Id of this Phone. Does not need to be included when creating customer.
      • phoneNumber string required example: 41783334444
      • type object required example: PRIVATE
        Type of this phone number. For company, only OFFICE type is supported
    • emails array of Email
      Emails of this company
      show fields

      Array of Email.

      • id string example: 1
        Id of this Email. Does not need to be included when creating customer
      • emailAddress string example: example@gmail.com
        Email address
      • type object required example: PRIVATE
        Type of this email
    • addresses array of Address
      Address list of this company, atleast one should be add
      show fields

      Array of Address.

      • id string example: 1
        Id of this Address. Does not need to be included when creating customer
      • validFrom string (date) format: date
        The timestamp from which this address is valid
      • validTo string (date) format: date
        The timestamp to which this address is valid
      • addressLines string required example: Chemin de la Caquerette 12
        The address lines for this Address
      • addressType string required pattern: \S example: WORK
        The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
      • cityName string required pattern: \S example: Bern
        Name of this City
      • cityZipCode string example: 3003
        The postal code of a city for this address
      • countryIso2Code string required pattern: \S example: CH
        2 letter country code. For company, only accept Switzerland
      • countryIso3Code string example: CHE
        3 letter country code. For company, only accept Switzerland
      • countryNumericCode string example: 756
        ISO-numeric code. For company, only accept Switzerland
      • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
        The path to get City object by city's id, /cities/{}
      • definitionName string example: 2nd address
        definition name of this address; in case main address, value is null; else value is not blank
      • additionalAddress string example: No. 13, street 123
        Additional address for more specific
    • corporateIdentificationNumber string example: CHE-123.456.789
      Every business active in Switzerland is given a unique enterprise identification number (UID). To ensure that numbers are correctly allocated and managed, the UID register is run by the Federal Statistical Office
    • vatNumber string example: CHE-123.456.789
      This is the official CH VAT number of the company
    • hrNumber string example: CHE-123.456.789
      This is the official CH number for this company in the CH trade register
    • nogaCode string example: 1234
      The NOGA code of this company
    • foundingDate string (date) format: date example: 2019-12-20
      Founding date of this comany in ISO 8601 format (yyyy-mm-dd)
    • companyNumber string
      This is a number the KLARA user can give to this customer/partner/supplier
  • priceCategory string example: Sale price
    You can select / enter a price category. On the articles you can define a special price for this price category. When such an article is sold / invoiced, the price of this category will apply if it is identical for the article and the customer.
  • customerType object required example: PERSON
    The type of this partner. Could be either Person or Company.
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found no response body
429 API rate limit exceeded no response body
PUT/core/latest/customers/{customer-id}key / tokenUpdate an existing customer
Parameters 1
NameDescription
customer-id required
path string
Id of the customer to be updated
example: 1
Request body required
The customer object with the information that needs to be updated

application/json Customer

  • id string read-only example: 1
    Id of this Customer. Does not need to be included when creating customer
  • person object
    A partner person.
    show fields
    • website string example: www.my-company.com
      The website address of this customer
    • categories array of string
      Add one or more categories to this customer that you can use as filter criteria for selecting partners
    • onlinePlatforms array of OnlinePlatform
      The list of online platforms that this customer uses
      show fields

      Array of OnlinePlatform.

      • id string read-only example: 1
        Id of this Online platform. Does not need to be included when creating Customer.
      • platformName object example: FACEBOOK
        Name of the platform that this customer uses
      • platformValue string example: www.linkedin.com/abc
        Url of customer's online platform/webpage
    • language string example: en
      The main language that this partner uses, valid values is [en, de, fr, it]
    • responsibleCounterpart string example: Mr. Marc
      The name of a contact person for this customer
    • correspondence object required example: MAIL
      The preferred method of correspondence, how this customer wants to receive the pay slips by default
    • id string example: 1
      Id of this person. Does not need to be included when creating customer
    • salutation object required example: MALE
      Salutation for this person, valid values is: [MALE, FEMALE, MALE_FEMALE, FAMILY]
    • firstName string required pattern: \S example: John
      First name of this person
    • lastName string required pattern: \S example: Henry
      Last name of this person
    • birthday string (date) format: date example: 2020-01-20
      Birth date of this person in ISO 8601 format (yyyy-MM-dd)
    • addresses array of Address
      Address list of this person
      show fields

      Array of Address.

      • id string example: 1
        Id of this Address. Does not need to be included when creating customer
      • validFrom string (date) format: date
        The timestamp from which this address is valid
      • validTo string (date) format: date
        The timestamp to which this address is valid
      • addressLines string required example: Chemin de la Caquerette 12
        The address lines for this Address
      • addressType string required pattern: \S example: WORK
        The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
      • cityName string required pattern: \S example: Bern
        Name of this City
      • cityZipCode string example: 3003
        The postal code of a city for this address
      • countryIso2Code string required pattern: \S example: CH
        2 letter country code. For company, only accept Switzerland
      • countryIso3Code string example: CHE
        3 letter country code. For company, only accept Switzerland
      • countryNumericCode string example: 756
        ISO-numeric code. For company, only accept Switzerland
      • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
        The path to get City object by city's id, /cities/{}
      • definitionName string example: 2nd address
        definition name of this address; in case main address, value is null; else value is not blank
      • additionalAddress string example: No. 13, street 123
        Additional address for more specific
    • phones array of Phone
      Phone number list of this person
      show fields

      Array of Phone.

      • id string example: 1
        Id of this Phone. Does not need to be included when creating customer.
      • phoneNumber string required example: 41783334444
      • type object required example: PRIVATE
        Type of this phone number. For company, only OFFICE type is supported
    • emails array of Email
      Email list of this person
      show fields

      Array of Email.

      • id string example: 1
        Id of this Email. Does not need to be included when creating customer
      • emailAddress string example: example@gmail.com
        Email address
      • type object required example: PRIVATE
        Type of this email
    • personNumber string
      This is a number the KLARA user can give to this customer/partner/supplier
  • company object
    A company.
    show fields
    • website string example: www.my-company.com
      The website address of this customer
    • categories array of string
      Add one or more categories to this customer that you can use as filter criteria for selecting partners
    • onlinePlatforms array of OnlinePlatform
      The list of online platforms that this customer uses
      show fields

      Array of OnlinePlatform.

      • id string read-only example: 1
        Id of this Online platform. Does not need to be included when creating Customer.
      • platformName object example: FACEBOOK
        Name of the platform that this customer uses
      • platformValue string example: www.linkedin.com/abc
        Url of customer's online platform/webpage
    • language string example: en
      The main language that this partner uses, valid values is [en, de, fr, it]
    • responsibleCounterpart string example: Mr. Marc
      The name of a contact person for this customer
    • correspondence object required example: MAIL
      The preferred method of correspondence, how this customer wants to receive the pay slips by default
    • id string read-only example: 1
      Id of this company. Does not need to be included when creating customer
    • name string required pattern: \S example: ABC-Corp
      Name of the company
    • phones array of Phone
      Phone numbers of the company
      show fields

      Array of Phone.

      • id string example: 1
        Id of this Phone. Does not need to be included when creating customer.
      • phoneNumber string required example: 41783334444
      • type object required example: PRIVATE
        Type of this phone number. For company, only OFFICE type is supported
    • emails array of Email
      Emails of this company
      show fields

      Array of Email.

      • id string example: 1
        Id of this Email. Does not need to be included when creating customer
      • emailAddress string example: example@gmail.com
        Email address
      • type object required example: PRIVATE
        Type of this email
    • addresses array of Address
      Address list of this company, atleast one should be add
      show fields

      Array of Address.

      • id string example: 1
        Id of this Address. Does not need to be included when creating customer
      • validFrom string (date) format: date
        The timestamp from which this address is valid
      • validTo string (date) format: date
        The timestamp to which this address is valid
      • addressLines string required example: Chemin de la Caquerette 12
        The address lines for this Address
      • addressType string required pattern: \S example: WORK
        The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
      • cityName string required pattern: \S example: Bern
        Name of this City
      • cityZipCode string example: 3003
        The postal code of a city for this address
      • countryIso2Code string required pattern: \S example: CH
        2 letter country code. For company, only accept Switzerland
      • countryIso3Code string example: CHE
        3 letter country code. For company, only accept Switzerland
      • countryNumericCode string example: 756
        ISO-numeric code. For company, only accept Switzerland
      • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
        The path to get City object by city's id, /cities/{}
      • definitionName string example: 2nd address
        definition name of this address; in case main address, value is null; else value is not blank
      • additionalAddress string example: No. 13, street 123
        Additional address for more specific
    • corporateIdentificationNumber string example: CHE-123.456.789
      Every business active in Switzerland is given a unique enterprise identification number (UID). To ensure that numbers are correctly allocated and managed, the UID register is run by the Federal Statistical Office
    • vatNumber string example: CHE-123.456.789
      This is the official CH VAT number of the company
    • hrNumber string example: CHE-123.456.789
      This is the official CH number for this company in the CH trade register
    • nogaCode string example: 1234
      The NOGA code of this company
    • foundingDate string (date) format: date example: 2019-12-20
      Founding date of this comany in ISO 8601 format (yyyy-mm-dd)
    • companyNumber string
      This is a number the KLARA user can give to this customer/partner/supplier
  • priceCategory string example: Sale price
    You can select / enter a price category. On the articles you can define a special price for this price category. When such an article is sold / invoiced, the price of this category will apply if it is identical for the article and the customer.
  • customerType object required example: PERSON
    The type of this partner. Could be either Person or Company.
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
Responses 6
200 Customer updated show body

application/json Customer

  • id string read-only example: 1
    Id of this Customer. Does not need to be included when creating customer
  • person object
    A partner person.
    show fields
    • website string example: www.my-company.com
      The website address of this customer
    • categories array of string
      Add one or more categories to this customer that you can use as filter criteria for selecting partners
    • onlinePlatforms array of OnlinePlatform
      The list of online platforms that this customer uses
      show fields

      Array of OnlinePlatform.

      • id string read-only example: 1
        Id of this Online platform. Does not need to be included when creating Customer.
      • platformName object example: FACEBOOK
        Name of the platform that this customer uses
      • platformValue string example: www.linkedin.com/abc
        Url of customer's online platform/webpage
    • language string example: en
      The main language that this partner uses, valid values is [en, de, fr, it]
    • responsibleCounterpart string example: Mr. Marc
      The name of a contact person for this customer
    • correspondence object required example: MAIL
      The preferred method of correspondence, how this customer wants to receive the pay slips by default
    • id string example: 1
      Id of this person. Does not need to be included when creating customer
    • salutation object required example: MALE
      Salutation for this person, valid values is: [MALE, FEMALE, MALE_FEMALE, FAMILY]
    • firstName string required pattern: \S example: John
      First name of this person
    • lastName string required pattern: \S example: Henry
      Last name of this person
    • birthday string (date) format: date example: 2020-01-20
      Birth date of this person in ISO 8601 format (yyyy-MM-dd)
    • addresses array of Address
      Address list of this person
      show fields

      Array of Address.

      • id string example: 1
        Id of this Address. Does not need to be included when creating customer
      • validFrom string (date) format: date
        The timestamp from which this address is valid
      • validTo string (date) format: date
        The timestamp to which this address is valid
      • addressLines string required example: Chemin de la Caquerette 12
        The address lines for this Address
      • addressType string required pattern: \S example: WORK
        The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
      • cityName string required pattern: \S example: Bern
        Name of this City
      • cityZipCode string example: 3003
        The postal code of a city for this address
      • countryIso2Code string required pattern: \S example: CH
        2 letter country code. For company, only accept Switzerland
      • countryIso3Code string example: CHE
        3 letter country code. For company, only accept Switzerland
      • countryNumericCode string example: 756
        ISO-numeric code. For company, only accept Switzerland
      • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
        The path to get City object by city's id, /cities/{}
      • definitionName string example: 2nd address
        definition name of this address; in case main address, value is null; else value is not blank
      • additionalAddress string example: No. 13, street 123
        Additional address for more specific
    • phones array of Phone
      Phone number list of this person
      show fields

      Array of Phone.

      • id string example: 1
        Id of this Phone. Does not need to be included when creating customer.
      • phoneNumber string required example: 41783334444
      • type object required example: PRIVATE
        Type of this phone number. For company, only OFFICE type is supported
    • emails array of Email
      Email list of this person
      show fields

      Array of Email.

      • id string example: 1
        Id of this Email. Does not need to be included when creating customer
      • emailAddress string example: example@gmail.com
        Email address
      • type object required example: PRIVATE
        Type of this email
    • personNumber string
      This is a number the KLARA user can give to this customer/partner/supplier
  • company object
    A company.
    show fields
    • website string example: www.my-company.com
      The website address of this customer
    • categories array of string
      Add one or more categories to this customer that you can use as filter criteria for selecting partners
    • onlinePlatforms array of OnlinePlatform
      The list of online platforms that this customer uses
      show fields

      Array of OnlinePlatform.

      • id string read-only example: 1
        Id of this Online platform. Does not need to be included when creating Customer.
      • platformName object example: FACEBOOK
        Name of the platform that this customer uses
      • platformValue string example: www.linkedin.com/abc
        Url of customer's online platform/webpage
    • language string example: en
      The main language that this partner uses, valid values is [en, de, fr, it]
    • responsibleCounterpart string example: Mr. Marc
      The name of a contact person for this customer
    • correspondence object required example: MAIL
      The preferred method of correspondence, how this customer wants to receive the pay slips by default
    • id string read-only example: 1
      Id of this company. Does not need to be included when creating customer
    • name string required pattern: \S example: ABC-Corp
      Name of the company
    • phones array of Phone
      Phone numbers of the company
      show fields

      Array of Phone.

      • id string example: 1
        Id of this Phone. Does not need to be included when creating customer.
      • phoneNumber string required example: 41783334444
      • type object required example: PRIVATE
        Type of this phone number. For company, only OFFICE type is supported
    • emails array of Email
      Emails of this company
      show fields

      Array of Email.

      • id string example: 1
        Id of this Email. Does not need to be included when creating customer
      • emailAddress string example: example@gmail.com
        Email address
      • type object required example: PRIVATE
        Type of this email
    • addresses array of Address
      Address list of this company, atleast one should be add
      show fields

      Array of Address.

      • id string example: 1
        Id of this Address. Does not need to be included when creating customer
      • validFrom string (date) format: date
        The timestamp from which this address is valid
      • validTo string (date) format: date
        The timestamp to which this address is valid
      • addressLines string required example: Chemin de la Caquerette 12
        The address lines for this Address
      • addressType string required pattern: \S example: WORK
        The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
      • cityName string required pattern: \S example: Bern
        Name of this City
      • cityZipCode string example: 3003
        The postal code of a city for this address
      • countryIso2Code string required pattern: \S example: CH
        2 letter country code. For company, only accept Switzerland
      • countryIso3Code string example: CHE
        3 letter country code. For company, only accept Switzerland
      • countryNumericCode string example: 756
        ISO-numeric code. For company, only accept Switzerland
      • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
        The path to get City object by city's id, /cities/{}
      • definitionName string example: 2nd address
        definition name of this address; in case main address, value is null; else value is not blank
      • additionalAddress string example: No. 13, street 123
        Additional address for more specific
    • corporateIdentificationNumber string example: CHE-123.456.789
      Every business active in Switzerland is given a unique enterprise identification number (UID). To ensure that numbers are correctly allocated and managed, the UID register is run by the Federal Statistical Office
    • vatNumber string example: CHE-123.456.789
      This is the official CH VAT number of the company
    • hrNumber string example: CHE-123.456.789
      This is the official CH number for this company in the CH trade register
    • nogaCode string example: 1234
      The NOGA code of this company
    • foundingDate string (date) format: date example: 2019-12-20
      Founding date of this comany in ISO 8601 format (yyyy-mm-dd)
    • companyNumber string
      This is a number the KLARA user can give to this customer/partner/supplier
  • priceCategory string example: Sale price
    You can select / enter a price category. On the articles you can define a special price for this price category. When such an article is sold / invoiced, the price of this category will apply if it is identical for the article and the customer.
  • customerType object required example: PERSON
    The type of this partner. Could be either Person or Company.
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
400 Data invalid show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found no response body
429 API rate limit exceeded no response body
GET/core/latest/customers/{customer-id}/additional-addresseskey / tokenGets all additional addresses of a customer
Parameters 1
NameDescription
customer-id required
path string
Id of the customer to get additional addresses
example: 1
Responses 4
200 List of all additional addresses show body

application/json array of Address

Array of Address.

  • id string example: 1
    Id of this Address. Does not need to be included when creating customer
  • validFrom string (date) format: date
    The timestamp from which this address is valid
  • validTo string (date) format: date
    The timestamp to which this address is valid
  • addressLines string required example: Chemin de la Caquerette 12
    The address lines for this Address
  • addressType string required pattern: \S example: WORK
    The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
  • cityName string required pattern: \S example: Bern
    Name of this City
  • cityZipCode string example: 3003
    The postal code of a city for this address
  • countryIso2Code string required pattern: \S example: CH
    2 letter country code. For company, only accept Switzerland
  • countryIso3Code string example: CHE
    3 letter country code. For company, only accept Switzerland
  • countryNumericCode string example: 756
    ISO-numeric code. For company, only accept Switzerland
  • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
    The path to get City object by city's id, /cities/{}
  • definitionName string example: 2nd address
    definition name of this address; in case main address, value is null; else value is not blank
  • additionalAddress string example: No. 13, street 123
    Additional address for more specific
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
POST/core/latest/customers/{customer-id}/additional-addresseskey / tokenCreates a new customer's additional address
Parameters 1
NameDescription
customer-id required
path string
Id of the customer to add additional addresses to
example: 1
Request body required
The additional address object with the information that needs to be created

application/json Address

  • id string example: 1
    Id of this Address. Does not need to be included when creating customer
  • validFrom string (date) format: date
    The timestamp from which this address is valid
  • validTo string (date) format: date
    The timestamp to which this address is valid
  • addressLines string required example: Chemin de la Caquerette 12
    The address lines for this Address
  • addressType string required pattern: \S example: WORK
    The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
  • cityName string required pattern: \S example: Bern
    Name of this City
  • cityZipCode string example: 3003
    The postal code of a city for this address
  • countryIso2Code string required pattern: \S example: CH
    2 letter country code. For company, only accept Switzerland
  • countryIso3Code string example: CHE
    3 letter country code. For company, only accept Switzerland
  • countryNumericCode string example: 756
    ISO-numeric code. For company, only accept Switzerland
  • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
    The path to get City object by city's id, /cities/{}
  • definitionName string example: 2nd address
    definition name of this address; in case main address, value is null; else value is not blank
  • additionalAddress string example: No. 13, street 123
    Additional address for more specific
Responses 5
200 Customer's new additional address created show body

application/json Address

  • id string example: 1
    Id of this Address. Does not need to be included when creating customer
  • validFrom string (date) format: date
    The timestamp from which this address is valid
  • validTo string (date) format: date
    The timestamp to which this address is valid
  • addressLines string required example: Chemin de la Caquerette 12
    The address lines for this Address
  • addressType string required pattern: \S example: WORK
    The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
  • cityName string required pattern: \S example: Bern
    Name of this City
  • cityZipCode string example: 3003
    The postal code of a city for this address
  • countryIso2Code string required pattern: \S example: CH
    2 letter country code. For company, only accept Switzerland
  • countryIso3Code string example: CHE
    3 letter country code. For company, only accept Switzerland
  • countryNumericCode string example: 756
    ISO-numeric code. For company, only accept Switzerland
  • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
    The path to get City object by city's id, /cities/{}
  • definitionName string example: 2nd address
    definition name of this address; in case main address, value is null; else value is not blank
  • additionalAddress string example: No. 13, street 123
    Additional address for more specific
400 Data invalid show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
DELETE/core/latest/customers/{customer-id}/additional-addresses/{address-id}key / tokenDelete an additional-address data by customer's id and customer's contact-id
Parameters 2
NameDescription
address-id required
path string
Id of the additional address needed to be updated
example: 1
customer-id required
path string
Id of the customer to update an additional address deleted
example: 1
Responses 5
204 Additional-address deleted no response body
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found no response body
429 API rate limit exceeded no response body
PUT/core/latest/customers/{customer-id}/additional-addresses/{address-id}key / tokenUpdates a Address
Parameters 2
NameDescription
address-id required
path string
The id of the requested Address
example: 1
customer-id required
path string
Id of the customer needed to update an additional address
example: 1
Request body required
The Address object with the information that needs to be updated

application/json Address

  • id string example: 1
    Id of this Address. Does not need to be included when creating customer
  • validFrom string (date) format: date
    The timestamp from which this address is valid
  • validTo string (date) format: date
    The timestamp to which this address is valid
  • addressLines string required example: Chemin de la Caquerette 12
    The address lines for this Address
  • addressType string required pattern: \S example: WORK
    The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
  • cityName string required pattern: \S example: Bern
    Name of this City
  • cityZipCode string example: 3003
    The postal code of a city for this address
  • countryIso2Code string required pattern: \S example: CH
    2 letter country code. For company, only accept Switzerland
  • countryIso3Code string example: CHE
    3 letter country code. For company, only accept Switzerland
  • countryNumericCode string example: 756
    ISO-numeric code. For company, only accept Switzerland
  • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
    The path to get City object by city's id, /cities/{}
  • definitionName string example: 2nd address
    definition name of this address; in case main address, value is null; else value is not blank
  • additionalAddress string example: No. 13, street 123
    Additional address for more specific
Responses 6
200 Updated additional-addresses show body

application/json Address

  • id string example: 1
    Id of this Address. Does not need to be included when creating customer
  • validFrom string (date) format: date
    The timestamp from which this address is valid
  • validTo string (date) format: date
    The timestamp to which this address is valid
  • addressLines string required example: Chemin de la Caquerette 12
    The address lines for this Address
  • addressType string required pattern: \S example: WORK
    The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
  • cityName string required pattern: \S example: Bern
    Name of this City
  • cityZipCode string example: 3003
    The postal code of a city for this address
  • countryIso2Code string required pattern: \S example: CH
    2 letter country code. For company, only accept Switzerland
  • countryIso3Code string example: CHE
    3 letter country code. For company, only accept Switzerland
  • countryNumericCode string example: 756
    ISO-numeric code. For company, only accept Switzerland
  • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
    The path to get City object by city's id, /cities/{}
  • definitionName string example: 2nd address
    definition name of this address; in case main address, value is null; else value is not blank
  • additionalAddress string example: No. 13, street 123
    Additional address for more specific
400 Data invalid show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found no response body
429 API rate limit exceeded no response body
GET/core/latest/customers/{customer-id}/contactskey / tokenGets all contacts of a customer
Parameters 1
NameDescription
customer-id required
path string
Id of the customer to get all contacts from
example: 1
Responses 4
200 List of contacts show body

application/json array of CustomerContact

Array of CustomerContact.

  • id string read-only example: 1
    Id of this contact. Does not need to be included when creating CustomerContact
  • imageId string read-only example: 1
    Id of this contact's image. Does not need to be included when creating CustomerContact
  • salutation object example: MALE
    Salutation for this contact
  • firstName string required example: John
    First name of this contact
  • lastName string required example: Henry
    Last name of this contact
  • email string example: john.henry@gmail.com
    Email of this contact
  • website string example: www.youtube.com
    Website of this contact
  • additionalAddressDefinition string
    Additional address definition of this contact
  • phones array of Phone
    Phone number list of this contact
    show fields

    Array of Phone.

    • id string example: 1
      Id of this Phone. Does not need to be included when creating customer.
    • phoneNumber string required example: 41783334444
    • type object required example: PRIVATE
      Type of this phone number. For company, only OFFICE type is supported
  • categories array of string
    Category list of this contact
  • onlinePlatforms array of OnlinePlatform
    The list of online platforms that this contact uses
    show fields

    Array of OnlinePlatform.

    • id string read-only example: 1
      Id of this Online platform. Does not need to be included when creating Customer.
    • platformName object example: FACEBOOK
      Name of the platform that this customer uses
    • platformValue string example: www.linkedin.com/abc
      Url of customer's online platform/webpage
  • customFields array of CustomField
    The list of custom information of this contact
    show fields

    Array of CustomField.

    • id string read-only example: 1
      Id of this custom field. Does not need to be included when creating CustomerContact
    • customName string example: name at home
      name of this custom field
    • customValue string example: John Henry
      value of this custom field
  • function string
    Function of this contact
  • birthday string (date) format: date example: 2020-12-20
    Birth date of this person in ISO 8601 format (yyyy-mm-dd)
  • note string example: this is a important contact.
    Note of this contact
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
POST/core/latest/customers/{customer-id}/contactskey / tokenCreates a new customer's contact
Parameters 1
NameDescription
customer-id required
path string
The id of the requested customer to add new contact to
example: 1
Request body required
The CustomerContact object with the information that needs to be created

application/json CustomerContact

  • id string read-only example: 1
    Id of this contact. Does not need to be included when creating CustomerContact
  • imageId string read-only example: 1
    Id of this contact's image. Does not need to be included when creating CustomerContact
  • salutation object example: MALE
    Salutation for this contact
  • firstName string required example: John
    First name of this contact
  • lastName string required example: Henry
    Last name of this contact
  • email string example: john.henry@gmail.com
    Email of this contact
  • website string example: www.youtube.com
    Website of this contact
  • additionalAddressDefinition string
    Additional address definition of this contact
  • phones array of Phone
    Phone number list of this contact
    show fields

    Array of Phone.

    • id string example: 1
      Id of this Phone. Does not need to be included when creating customer.
    • phoneNumber string required example: 41783334444
    • type object required example: PRIVATE
      Type of this phone number. For company, only OFFICE type is supported
  • categories array of string
    Category list of this contact
  • onlinePlatforms array of OnlinePlatform
    The list of online platforms that this contact uses
    show fields

    Array of OnlinePlatform.

    • id string read-only example: 1
      Id of this Online platform. Does not need to be included when creating Customer.
    • platformName object example: FACEBOOK
      Name of the platform that this customer uses
    • platformValue string example: www.linkedin.com/abc
      Url of customer's online platform/webpage
  • customFields array of CustomField
    The list of custom information of this contact
    show fields

    Array of CustomField.

    • id string read-only example: 1
      Id of this custom field. Does not need to be included when creating CustomerContact
    • customName string example: name at home
      name of this custom field
    • customValue string example: John Henry
      value of this custom field
  • function string
    Function of this contact
  • birthday string (date) format: date example: 2020-12-20
    Birth date of this person in ISO 8601 format (yyyy-mm-dd)
  • note string example: this is a important contact.
    Note of this contact
Responses 5
200 Customer's new contact created show body

application/json CustomerContact

  • id string read-only example: 1
    Id of this contact. Does not need to be included when creating CustomerContact
  • imageId string read-only example: 1
    Id of this contact's image. Does not need to be included when creating CustomerContact
  • salutation object example: MALE
    Salutation for this contact
  • firstName string required example: John
    First name of this contact
  • lastName string required example: Henry
    Last name of this contact
  • email string example: john.henry@gmail.com
    Email of this contact
  • website string example: www.youtube.com
    Website of this contact
  • additionalAddressDefinition string
    Additional address definition of this contact
  • phones array of Phone
    Phone number list of this contact
    show fields

    Array of Phone.

    • id string example: 1
      Id of this Phone. Does not need to be included when creating customer.
    • phoneNumber string required example: 41783334444
    • type object required example: PRIVATE
      Type of this phone number. For company, only OFFICE type is supported
  • categories array of string
    Category list of this contact
  • onlinePlatforms array of OnlinePlatform
    The list of online platforms that this contact uses
    show fields

    Array of OnlinePlatform.

    • id string read-only example: 1
      Id of this Online platform. Does not need to be included when creating Customer.
    • platformName object example: FACEBOOK
      Name of the platform that this customer uses
    • platformValue string example: www.linkedin.com/abc
      Url of customer's online platform/webpage
  • customFields array of CustomField
    The list of custom information of this contact
    show fields

    Array of CustomField.

    • id string read-only example: 1
      Id of this custom field. Does not need to be included when creating CustomerContact
    • customName string example: name at home
      name of this custom field
    • customValue string example: John Henry
      value of this custom field
  • function string
    Function of this contact
  • birthday string (date) format: date example: 2020-12-20
    Birth date of this person in ISO 8601 format (yyyy-mm-dd)
  • note string example: this is a important contact.
    Note of this contact
400 Data invalid show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
DELETE/core/latest/customers/{customer-id}/contacts/{contact-id}key / tokenDelete a CustomerContact data by customer's id and customer's contact-id
Parameters 2
NameDescription
contact-id required
path string
Id of a customer's contact to be deleted
example: 1
customer-id required
path string
Id of the requested customer to have a contact deleted
example: 1
Responses 5
204 Customer's contact deleted no response body
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found no response body
429 API rate limit exceeded no response body
PUT/core/latest/customers/{customer-id}/contacts/{contact-id}key / tokenUpdates a CustomerContact
Parameters 2
NameDescription
contact-id required
path string
The id of the requested customer's contact to be updated
example: 1
customer-id required
path string
Id of the customer to have a contact updated
example: 1
Request body required
The customer's contact object with the information that needs to be updated

application/json CustomerContact

  • id string read-only example: 1
    Id of this contact. Does not need to be included when creating CustomerContact
  • imageId string read-only example: 1
    Id of this contact's image. Does not need to be included when creating CustomerContact
  • salutation object example: MALE
    Salutation for this contact
  • firstName string required example: John
    First name of this contact
  • lastName string required example: Henry
    Last name of this contact
  • email string example: john.henry@gmail.com
    Email of this contact
  • website string example: www.youtube.com
    Website of this contact
  • additionalAddressDefinition string
    Additional address definition of this contact
  • phones array of Phone
    Phone number list of this contact
    show fields

    Array of Phone.

    • id string example: 1
      Id of this Phone. Does not need to be included when creating customer.
    • phoneNumber string required example: 41783334444
    • type object required example: PRIVATE
      Type of this phone number. For company, only OFFICE type is supported
  • categories array of string
    Category list of this contact
  • onlinePlatforms array of OnlinePlatform
    The list of online platforms that this contact uses
    show fields

    Array of OnlinePlatform.

    • id string read-only example: 1
      Id of this Online platform. Does not need to be included when creating Customer.
    • platformName object example: FACEBOOK
      Name of the platform that this customer uses
    • platformValue string example: www.linkedin.com/abc
      Url of customer's online platform/webpage
  • customFields array of CustomField
    The list of custom information of this contact
    show fields

    Array of CustomField.

    • id string read-only example: 1
      Id of this custom field. Does not need to be included when creating CustomerContact
    • customName string example: name at home
      name of this custom field
    • customValue string example: John Henry
      value of this custom field
  • function string
    Function of this contact
  • birthday string (date) format: date example: 2020-12-20
    Birth date of this person in ISO 8601 format (yyyy-mm-dd)
  • note string example: this is a important contact.
    Note of this contact
Responses 6
200 Updated contact show body

application/json CustomerContact

  • id string read-only example: 1
    Id of this contact. Does not need to be included when creating CustomerContact
  • imageId string read-only example: 1
    Id of this contact's image. Does not need to be included when creating CustomerContact
  • salutation object example: MALE
    Salutation for this contact
  • firstName string required example: John
    First name of this contact
  • lastName string required example: Henry
    Last name of this contact
  • email string example: john.henry@gmail.com
    Email of this contact
  • website string example: www.youtube.com
    Website of this contact
  • additionalAddressDefinition string
    Additional address definition of this contact
  • phones array of Phone
    Phone number list of this contact
    show fields

    Array of Phone.

    • id string example: 1
      Id of this Phone. Does not need to be included when creating customer.
    • phoneNumber string required example: 41783334444
    • type object required example: PRIVATE
      Type of this phone number. For company, only OFFICE type is supported
  • categories array of string
    Category list of this contact
  • onlinePlatforms array of OnlinePlatform
    The list of online platforms that this contact uses
    show fields

    Array of OnlinePlatform.

    • id string read-only example: 1
      Id of this Online platform. Does not need to be included when creating Customer.
    • platformName object example: FACEBOOK
      Name of the platform that this customer uses
    • platformValue string example: www.linkedin.com/abc
      Url of customer's online platform/webpage
  • customFields array of CustomField
    The list of custom information of this contact
    show fields

    Array of CustomField.

    • id string read-only example: 1
      Id of this custom field. Does not need to be included when creating CustomerContact
    • customName string example: name at home
      name of this custom field
    • customValue string example: John Henry
      value of this custom field
  • function string
    Function of this contact
  • birthday string (date) format: date example: 2020-12-20
    Birth date of this person in ISO 8601 format (yyyy-mm-dd)
  • note string example: this is a important contact.
    Note of this contact
400 Data invalid show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
404 Resource not found no response body
429 API rate limit exceeded no response body
GET/core/v1/customerskey / tokenSearch and page the customers of the caller's company.
Returns a page of customers (Persons + Companies) of the caller's company, with optional free-text search (search-key) and status filter (status). Results are paged with offset and limit: to retrieve every customer, iterate offset=0, limit, 2×limit, … until a response returns fewer than limit rows. All query parameters are optional; without any, the endpoint returns the first 50 active customers (downstream default ordering). This is a read-only, idempotent operation.

The tenant and company are derived from the JWT (@CurrentSession Token) and are never accepted as parameters. The caller must be authenticated (apiKeyAuth + bearerAuth) and must hold the FINANCE_GET_CUSTOMER permission on that company; otherwise the endpoint returns 403.
Required permission

FINANCE_GET_CUSTOMER

Parameters 4
NameDescription
limit
query integer
Page size. Defaults to 50; hard cap 100. Requests above the cap are rejected with 400.
min: 1 max: 100 default: 50 example: 50
offset
query integer
0-based pagination offset — the number of customers to skip before the returned page. Defaults to 0. Combine with limit to walk the full list.
min: 0 default: 0 example: 0
search-key
query string
Free-text search across customer name, email, phone and customer number. Tokenised on whitespace; matches are case-insensitive substring matches. Maximum length 256 characters.
maxLength: 256 example: müller
status
query string
Filter by customer state. Allowed values: ACTIVE, ALL, ARCHIVED. When omitted, the downstream service applies its default (active customers only).
Allowed values: ACTIVE, ALL, ARCHIVED
maxLength: 16 example: ACTIVE
Responses 5
200 Customers show body

application/json array of Customer

Array of Customer.

  • id string read-only example: 1
    Id of this Customer. Does not need to be included when creating customer
  • person object
    A partner person.
    show fields
    • website string example: www.my-company.com
      The website address of this customer
    • categories array of string
      Add one or more categories to this customer that you can use as filter criteria for selecting partners
    • onlinePlatforms array of OnlinePlatform
      The list of online platforms that this customer uses
      show fields

      Array of OnlinePlatform.

      • id string read-only example: 1
        Id of this Online platform. Does not need to be included when creating Customer.
      • platformName object example: FACEBOOK
        Name of the platform that this customer uses
      • platformValue string example: www.linkedin.com/abc
        Url of customer's online platform/webpage
    • language string example: en
      The main language that this partner uses, valid values is [en, de, fr, it]
    • responsibleCounterpart string example: Mr. Marc
      The name of a contact person for this customer
    • correspondence object required example: MAIL
      The preferred method of correspondence, how this customer wants to receive the pay slips by default
    • id string example: 1
      Id of this person. Does not need to be included when creating customer
    • salutation object required example: MALE
      Salutation for this person, valid values is: [MALE, FEMALE, MALE_FEMALE, FAMILY]
    • firstName string required pattern: \S example: John
      First name of this person
    • lastName string required pattern: \S example: Henry
      Last name of this person
    • birthday string (date) format: date example: 2020-01-20
      Birth date of this person in ISO 8601 format (yyyy-MM-dd)
    • addresses array of Address
      Address list of this person
      show fields

      Array of Address.

      • id string example: 1
        Id of this Address. Does not need to be included when creating customer
      • validFrom string (date) format: date
        The timestamp from which this address is valid
      • validTo string (date) format: date
        The timestamp to which this address is valid
      • addressLines string required example: Chemin de la Caquerette 12
        The address lines for this Address
      • addressType string required pattern: \S example: WORK
        The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
      • cityName string required pattern: \S example: Bern
        Name of this City
      • cityZipCode string example: 3003
        The postal code of a city for this address
      • countryIso2Code string required pattern: \S example: CH
        2 letter country code. For company, only accept Switzerland
      • countryIso3Code string example: CHE
        3 letter country code. For company, only accept Switzerland
      • countryNumericCode string example: 756
        ISO-numeric code. For company, only accept Switzerland
      • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
        The path to get City object by city's id, /cities/{}
      • definitionName string example: 2nd address
        definition name of this address; in case main address, value is null; else value is not blank
      • additionalAddress string example: No. 13, street 123
        Additional address for more specific
    • phones array of Phone
      Phone number list of this person
      show fields

      Array of Phone.

      • id string example: 1
        Id of this Phone. Does not need to be included when creating customer.
      • phoneNumber string required example: 41783334444
      • type object required example: PRIVATE
        Type of this phone number. For company, only OFFICE type is supported
    • emails array of Email
      Email list of this person
      show fields

      Array of Email.

      • id string example: 1
        Id of this Email. Does not need to be included when creating customer
      • emailAddress string example: example@gmail.com
        Email address
      • type object required example: PRIVATE
        Type of this email
    • personNumber string
      This is a number the KLARA user can give to this customer/partner/supplier
  • company object
    A company.
    show fields
    • website string example: www.my-company.com
      The website address of this customer
    • categories array of string
      Add one or more categories to this customer that you can use as filter criteria for selecting partners
    • onlinePlatforms array of OnlinePlatform
      The list of online platforms that this customer uses
      show fields

      Array of OnlinePlatform.

      • id string read-only example: 1
        Id of this Online platform. Does not need to be included when creating Customer.
      • platformName object example: FACEBOOK
        Name of the platform that this customer uses
      • platformValue string example: www.linkedin.com/abc
        Url of customer's online platform/webpage
    • language string example: en
      The main language that this partner uses, valid values is [en, de, fr, it]
    • responsibleCounterpart string example: Mr. Marc
      The name of a contact person for this customer
    • correspondence object required example: MAIL
      The preferred method of correspondence, how this customer wants to receive the pay slips by default
    • id string read-only example: 1
      Id of this company. Does not need to be included when creating customer
    • name string required pattern: \S example: ABC-Corp
      Name of the company
    • phones array of Phone
      Phone numbers of the company
      show fields

      Array of Phone.

      • id string example: 1
        Id of this Phone. Does not need to be included when creating customer.
      • phoneNumber string required example: 41783334444
      • type object required example: PRIVATE
        Type of this phone number. For company, only OFFICE type is supported
    • emails array of Email
      Emails of this company
      show fields

      Array of Email.

      • id string example: 1
        Id of this Email. Does not need to be included when creating customer
      • emailAddress string example: example@gmail.com
        Email address
      • type object required example: PRIVATE
        Type of this email
    • addresses array of Address
      Address list of this company, atleast one should be add
      show fields

      Array of Address.

      • id string example: 1
        Id of this Address. Does not need to be included when creating customer
      • validFrom string (date) format: date
        The timestamp from which this address is valid
      • validTo string (date) format: date
        The timestamp to which this address is valid
      • addressLines string required example: Chemin de la Caquerette 12
        The address lines for this Address
      • addressType string required pattern: \S example: WORK
        The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
      • cityName string required pattern: \S example: Bern
        Name of this City
      • cityZipCode string example: 3003
        The postal code of a city for this address
      • countryIso2Code string required pattern: \S example: CH
        2 letter country code. For company, only accept Switzerland
      • countryIso3Code string example: CHE
        3 letter country code. For company, only accept Switzerland
      • countryNumericCode string example: 756
        ISO-numeric code. For company, only accept Switzerland
      • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
        The path to get City object by city's id, /cities/{}
      • definitionName string example: 2nd address
        definition name of this address; in case main address, value is null; else value is not blank
      • additionalAddress string example: No. 13, street 123
        Additional address for more specific
    • corporateIdentificationNumber string example: CHE-123.456.789
      Every business active in Switzerland is given a unique enterprise identification number (UID). To ensure that numbers are correctly allocated and managed, the UID register is run by the Federal Statistical Office
    • vatNumber string example: CHE-123.456.789
      This is the official CH VAT number of the company
    • hrNumber string example: CHE-123.456.789
      This is the official CH number for this company in the CH trade register
    • nogaCode string example: 1234
      The NOGA code of this company
    • foundingDate string (date) format: date example: 2019-12-20
      Founding date of this comany in ISO 8601 format (yyyy-mm-dd)
    • companyNumber string
      This is a number the KLARA user can give to this customer/partner/supplier
  • priceCategory string example: Sale price
    You can select / enter a price category. On the articles you can define a special price for this price category. When such an article is sold / invoiced, the price of this category will apply if it is identical for the article and the customer.
  • customerType object required example: PERSON
    The type of this partner. Could be either Person or Company.
  • _links object
    links metadata
    show fields
    • self Link
      Link metadata
      show fields
      • href string
400 Data invalid show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body

Individual2

GET/core/v2/tenants/individuals/profilekey / token[PREVIEW_API] Get profile from tenant's ID
Responses 5
200 Retrieved profile successfully show body

application/json object

  • participantId string read-only example: 969b2b24-5ffe-4b7c-b1e2-a2a59fb1acb5
  • firstName string example: Nikola
  • lastName string example: Tesla
  • email string example: email@klara.ch
    Main email address
  • tenantEntryType string example: INDIVIDUAL
    Tenant entry type of the profile
400 Data invalid show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
404 Profile not found show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
POST/core/v2/tenants/individuals/profilekey / token[PREVIEW_API] Create profile
Responses 5
200 Created profile successfully show body

application/json object

  • participantId string read-only example: 969b2b24-5ffe-4b7c-b1e2-a2a59fb1acb5
  • firstName string example: Nikola
  • lastName string example: Tesla
  • email string example: email@klara.ch
    Main email address
  • tenantEntryType string example: INDIVIDUAL
    Tenant entry type of the profile
400 Data invalid show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
401 No Authorization header found or invalid token no response body
404 Resource not found show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
500 Something went wrong on our side while processing the request. Please kindly contact our support. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated

Payroll

Payroll3

GET/core/v1/employees/short-infokey / tokenList the company's employees as short-info entries, filtered and sorted.
Returns a lightweight directory of the authenticated company's employees (id, name, email, employee number, workplace, status), resolved from the compensation and person records. Each entry's id is the employeeId consumed by other employee-scoped endpoints (e.g. GET /payroll/employees/{employeeId}/addable-salary-items) — call this endpoint first to resolve an employee's id. Results can be narrowed with a free-text search-key (matched against name, employee number and email), restricted to specific workplaces via workplace-ids, and filtered by contract filter-by-status; ordering is controlled by sort-field and sort-direction. The tenant and company are derived from the authenticated token; the caller must hold the COMPENSATION_TIME_TRACKING permission on that company.
Required permission

COMPENSATION_TIME_TRACKING

Parameters 5
NameDescription
filter-by-status
query string
Contract-status filter. Allowed values: ALL, ACTIVE, INACTIVE, DRAFT. Defaults to ALL.
Allowed values: ALL, ACTIVE, INACTIVE, DRAFT
default: ALL example: ALL
search-key
query string
Case-insensitive substring matched against the employee's full name, employee number and email. When omitted, no text filter is applied.
maxLength: 256
sort-direction
query string
Sort direction. Allowed values: ASC, DESC.
Allowed values: ASC, DESC
sort-field
query string
Field to sort by. Allowed values: NAME, EMAIL, EMPLOYEE_NUMBER. Defaults to NAME.
Allowed values: NAME, EMAIL, EMPLOYEE_NUMBER
default: NAME example: NAME
workplace-ids
query array of integer (int64)
Restrict results to employees whose current contract workplace is in this set. Repeat the parameter for multiple ids (e.g. workplace-ids=12&workplace-ids=13). When omitted, employees of all workplaces are returned.
Responses 7
200 Successful operation show body

application/json array of PublicApiEmployeeShortInfo

Array of PublicApiEmployeeShortInfo.

  • id integer (int64) format: int64 example: 3487
    Employee id. Use this as employeeId in employee-scoped endpoints.
  • firstName string example: Anna
    Employee's first name (resolved from the person record).
  • lastName string example: Müller
    Employee's last name (resolved from the person record).
  • employeeNumber string example: E-00123
    Company-assigned employee number.
  • email string example: anna.mueller@example.com
    Employee's primary email (resolved from the person record).
  • workplaceId integer (int64) format: int64 example: 12
    Id of the workplace of the employee's current contract.
  • personnelNumber string example: P-4711
    Personnel number of the employee.
  • numberOfChildren integer (int64) format: int64 example: 2
    Number of children registered for the employee.
  • cashPayment boolean example: False
    Whether the employee is paid in cash.
  • status string example: ACTIVE
    Contract status of the employee. Allowed values: ACTIVE, INACTIVE, DRAFT.
400 Data invalid show body

application/json ErrorMessage1

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage1

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string
404 Resource not found show body

application/json ErrorMessage1

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. no response body
POST/core/v1/payroll/contracts/{contractId}/payslips/{payslipId}/salary-itemskey / tokenAdd a salary item to an employee's payslip.
Adds a single salary item (Base / Percent / Quantity / Amount / Comments) to the employee's editable (non-sealed) payslip identified by payslipId, then recalculates that month unless recalculate=false. Returns the added salary item with its server-assigned id. This operation is not idempotent: repeated calls append duplicate items or throw an error when the item is not duplicatable (subject to the item's duplicatable flag). Prerequisite: call GET /payroll/employees/{employeeId}/addable-salary-items first — its response provides the contractId and payslipId to target and the addable codes; resolve employeeId beforehand via GET /employees/short-info. The tenant and company are derived from the authenticated token; the caller must hold the COMPENSATION permission on that company.
Required permission

COMPENSATION

Parameters 3
NameDescription
contractId required
path integer
Id of the employee's contract to add the salary item to. Obtained from the contractId field of the GET /payroll/employees/{employeeId}/addable-salary-items response — call that endpoint first to select the employee and obtain this id.
example: 1
payslipId required
path integer
Id of the target (editable, non-sealed) payslip. Obtained from the payslipId field of the GET /payroll/employees/{employeeId}/addable-salary-items response — call that endpoint first to select the employee and obtain this id.
example: 26
recalculate
query boolean
Whether to recalculate the payslip after adding the item. Defaults to true.
default: true example: True
Request body required
Purpose: add one salary item to the target payslip. The code must be one of the addable salary items for this payslip, and only the value fields the item allows may be sent.
Prerequisite APIs / value sources:
  • GET /employees/short-info → provides employeeId
  • GET /payroll/employees/{employeeId}/addable-salary-items → provides the contractId and payslipId path parameters, plus salaryItems[].code (→ code) and each item's editableFields (which of baseValue/rate/quantity/value may be sent)
Top-level fields:
  • code (string, required) — salary-type code from the addable-salary-items response.
  • salaryItemValues (object, optional) — the numeric values; see below.
  • remark (string, optional, max 1024) — free-text comment (GUI "Comments").
Nested salaryItemValues:
  • baseValue — GUI "Base".
  • rate — GUI "Percent (%)", but expressed as a decimal multiplier, not a percentage number: 1 = 100%, 0.5 = 50%, 2 = 200%. If GUI implementation wants to keep a normal percentage input for the user (e.g. typing 50 for 50%), it must divide that value by 100 before sending it here (50 / 100 = 0.5).
  • quantity — GUI "Quantity".
  • value — GUI "Amount".
Rules: the payslip must be editable (non-sealed); the code must be addable to this payslip (returned by the addable-salary-items endpoint); only fields listed in the item's editableFields should be provided and the GUI implementation should also only show input boxes for those fields; with salary items that are not duplicatable (duplicatable=false), the GUI implementation should have a mechanism to recall the GET /payroll/employees/{employeeId}/addable-salary-items endpoint after each add to refresh the list of addable items and prevent adding duplicates, or automatically remove the added item from the list of addable items in the GUI; salaryItemValues.rate is a decimal multiplier (1 = 100%, 0.5 = 50%, 2 = 200%), not a percentage number — do not send a raw percentage like 50 for 50%, send 0.5.

application/json PayslipSalaryItemRequest

  • code string required maxLength: 64 pattern: \S example: 1005
    Salary-type code identifying the item to add. Must be one of the codes returned by GET /payroll/employees/{employeeId}/addable-salary-items (salaryItems[].code).
  • salaryItemValues object
    Numeric value fields of a salary item (GUI Base / Percent / Quantity / Amount). Only fields listed in the salary item's editableFields may be provided.
    show fields
    • baseValue number example: 5000
      GUI "Base" value.
    • rate number example: 0.5
      GUI "Percent (%)" value, expressed as a decimal multiplier — NOT a percentage number. 1 = 100%, 0.5 = 50%, 2 = 200%. If GUI implementation wants to keep a normal percentage input for the user (typing 50 for 50%) instead of a multiplier (0.5), it must divide that input by 100 before sending it here (50 / 100 = 0.5).
    • quantity number example: 1
      GUI "Quantity" value.
    • value number example: 425
      GUI "Amount" value.
  • remark string maxLength: 1024 example: Adjustment for March
    Optional free-text comment (GUI "Comments").
Responses 7
200 Successful operation show body

application/json PayslipSalaryItem

  • id integer (int64) format: int64 example: 778812
    Server-assigned id of the added salary item (present in the response only).
  • code string example: 1005
    Salary-type code of the added salary item.
  • salaryItemValues object
    Numeric value fields of a salary item (GUI Base / Percent / Quantity / Amount). Only fields listed in the salary item's editableFields may be provided.
    show fields
    • baseValue number example: 5000
      GUI "Base" value.
    • rate number example: 0.5
      GUI "Percent (%)" value, expressed as a decimal multiplier — NOT a percentage number. 1 = 100%, 0.5 = 50%, 2 = 200%. If GUI implementation wants to keep a normal percentage input for the user (typing 50 for 50%) instead of a multiplier (0.5), it must divide that input by 100 before sending it here (50 / 100 = 0.5).
    • quantity number example: 1
      GUI "Quantity" value.
    • value number example: 425
      GUI "Amount" value.
  • remark string example: Adjustment for March
    Free-text comment attached to the salary item (GUI "Comments").
400 Data invalid show body

application/json ErrorMessage1

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage1

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string
404 Resource not found show body

application/json ErrorMessage1

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. no response body
GET/core/v1/payroll/employees/{employeeId}/addable-salary-itemskey / tokenGet the salary items that can be added to an employee's payslip.
Resolves the employee's main (latest) contract and its editable payslip, then returns the salary-item types that can be added to that payslip as blank templates (numeric value fields cleared, distinct by code), together with the resolved contractId and payslipId so the response can be chained into the add-salary-item call. Prerequisite: call GET /employees/short-info first to resolve the employeeId path parameter from the returned entries' id field. When month is provided the specified month's payslip is used (read-only); when it is omitted the employee's current editable payslip is used, which may be computed on first access. The tenant and company are derived from the authenticated token; the caller must hold the COMPENSATION permission on that company.
Required permission

COMPENSATION

Parameters 3
NameDescription
employeeId required
path integer
Id of the employee whose addable salary items are resolved. Obtained from the id field of an entry returned by GET /employees/short-info.
example: 1
month
query string
Payslip month in the format MM.yyyy (e.g. 06.2025). If omitted, the employee's current editable payslip is used.
example: 06.2025
Accept-Language
header string
Preferred language for localised salary-item descriptions, as an IETF language tag. Examples: de-CH, fr-CH, it-CH, en. Defaults to the tenant's language when omitted.
example: de-CH
Responses 7
200 Successful operation show body

application/json AddablePayslipSalaryItems

  • employeeId integer (int64) format: int64 example: 3487
    Id of the employee the addable salary items were resolved for.
  • contractId integer (int64) format: int64 example: 9021
    Id of the employee's resolved main (latest) contract. Pass this to the add-salary-item call.
  • payslipId integer (int64) format: int64 example: 9542
    Id of the resolved editable payslip. Pass this to the add-salary-item call.
  • periodFrom string (date-time) format: date-time example: 2018-03-01T00:00:00Z
    Month (first day) of the resolved payslip (yyyy-MM-ddT00:00:00Z).
  • salaryItems array of AddableSalaryItem
    Addable salary items as blank templates (value fields cleared), distinct by code.
    show fields

    Array of AddableSalaryItem.

    • code string example: 1005
      Salary-type code. Send this as the salary item code when adding it to the payslip.
    • name string example: Hourly Salary
      Canonical (non-localized) name of the salary item.
    • description string example: Stundenlohn
      Localised description/label of the salary item (localised via the Accept-Language header).
    • editableFields string example: baseValue,quantity
      Comma-separated list of the value fields that can be provided when adding this salary item (baseValue, rate, quantity, value). The GUI implementation must base on this list to only show input box for fields that exist in this list.
    • duplicatable boolean example: True
      Whether more than one instance of this salary item can be added to the same payslip. When false, only one instance of this salary item can be added, try to add another one will result in an error.
    • showOnPayslip boolean example: True
      Whether the salary item is shown on the payslip.
    • employerRelated boolean example: False
      Whether the salary item is employer-related (as opposed to employee-related).
    • paymentTypeSit object example: BANK
      How the salary item is paid out. Allowed values: BANK, PAYINSLIP, CASH.
    • salaryItemTypeId integer (int64) format: int64 example: 42
      Id of the underlying salary-item type definition.
    • accountingGroup string example: SALARY
      Accounting group the salary item belongs to.
    • printSequence integer (int32) format: int32 example: 100
      Print/order sequence of the salary item on the payslip.
400 Data invalid show body

application/json ErrorMessage1

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage1

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string
404 Resource not found show body

application/json ErrorMessage1

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. no response body

Company & Locations

Company3

GET/core/v2/tenants/companieskey / tokenFind KLARA business company of tenant
Retrieve the business company of a tenant. Use your KLARA token from your username & password & tenant-id.
Responses 5
201 Company found show body

application/json BusinessCompany

  • name string required pattern: \S example: ABC-Corp
    Name of the company
  • legalForm object required example: LIMITED_LIABILITY
    Legal form of a company. Can be one of the following:
    • Limited liability company(GmbH)
    • Public limited company (AG)
    • Individually owned company (EU)
    • Association (V)
    • Simple partnership (EG)
    • General partnership (KG)
    • Limited partnership (KDG)
    • Cooperative company (G)
    • Foundation (S)
    • OR
  • phones array of Phone required
    Phone numbers of the company
    show fields

    Array of Phone.

    • id string example: 1
      Id of this Phone. Does not need to be included when creating customer.
    • phoneNumber string required example: 41783334444
    • type object required example: PRIVATE
      Type of this phone number. For company, only OFFICE type is supported
  • emails array of Email required
    Emails of this company
    show fields

    Array of Email.

    • id string example: 1
      Id of this Email. Does not need to be included when creating customer
    • emailAddress string example: example@gmail.com
      Email address
    • type object required example: PRIVATE
      Type of this email
  • addresses array of Address required
    Address list of this company, at least one should be add. For company, address type MUST be PRIVATE
    show fields

    Array of Address.

    • id string example: 1
      Id of this Address. Does not need to be included when creating customer
    • validFrom string (date) format: date
      The timestamp from which this address is valid
    • validTo string (date) format: date
      The timestamp to which this address is valid
    • addressLines string required example: Chemin de la Caquerette 12
      The address lines for this Address
    • addressType string required pattern: \S example: WORK
      The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
    • cityName string required pattern: \S example: Bern
      Name of this City
    • cityZipCode string example: 3003
      The postal code of a city for this address
    • countryIso2Code string required pattern: \S example: CH
      2 letter country code. For company, only accept Switzerland
    • countryIso3Code string example: CHE
      3 letter country code. For company, only accept Switzerland
    • countryNumericCode string example: 756
      ISO-numeric code. For company, only accept Switzerland
    • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
      The path to get City object by city's id, /cities/{}
    • definitionName string example: 2nd address
      definition name of this address; in case main address, value is null; else value is not blank
    • additionalAddress string example: No. 13, street 123
      Additional address for more specific
  • language string required pattern: \S example: de
    Preferred language of the company. Supported: English, German, French, Italian
    Allowed values: de, en, fr, it
  • corporateIdentificationNumber string example: CHE-123.456.789
    Every business active in Switzerland is given a unique enterprise identification number (UID). To ensure that numbers are correctly allocated and managed, the UID register is run by the Federal Statistical Office
  • foundingDate string (date) format: date example: 2019-12-20
    Founding date of this company in ISO 8601 format (yyyy-mm-dd)
401 Invalid credentials show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response
403 The user has been disabled show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response
429 API rate limit exceeded no response body
500 Something went wrong when find company show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response
POST/core/v2/tenants/companieskey / tokenCreate a KLARA business company
A Klara user might have multiple company tenants. Use this endpoint to create a business company and its correspondence tenant. Use your KLARA token from your username & password & tenant-id.
Request body
The company information

application/json BusinessCompany

  • name string required pattern: \S example: ABC-Corp
    Name of the company
  • legalForm object required example: LIMITED_LIABILITY
    Legal form of a company. Can be one of the following:
    • Limited liability company(GmbH)
    • Public limited company (AG)
    • Individually owned company (EU)
    • Association (V)
    • Simple partnership (EG)
    • General partnership (KG)
    • Limited partnership (KDG)
    • Cooperative company (G)
    • Foundation (S)
    • OR
  • phones array of Phone required
    Phone numbers of the company
    show fields

    Array of Phone.

    • id string example: 1
      Id of this Phone. Does not need to be included when creating customer.
    • phoneNumber string required example: 41783334444
    • type object required example: PRIVATE
      Type of this phone number. For company, only OFFICE type is supported
  • emails array of Email required
    Emails of this company
    show fields

    Array of Email.

    • id string example: 1
      Id of this Email. Does not need to be included when creating customer
    • emailAddress string example: example@gmail.com
      Email address
    • type object required example: PRIVATE
      Type of this email
  • addresses array of Address required
    Address list of this company, at least one should be add. For company, address type MUST be PRIVATE
    show fields

    Array of Address.

    • id string example: 1
      Id of this Address. Does not need to be included when creating customer
    • validFrom string (date) format: date
      The timestamp from which this address is valid
    • validTo string (date) format: date
      The timestamp to which this address is valid
    • addressLines string required example: Chemin de la Caquerette 12
      The address lines for this Address
    • addressType string required pattern: \S example: WORK
      The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
    • cityName string required pattern: \S example: Bern
      Name of this City
    • cityZipCode string example: 3003
      The postal code of a city for this address
    • countryIso2Code string required pattern: \S example: CH
      2 letter country code. For company, only accept Switzerland
    • countryIso3Code string example: CHE
      3 letter country code. For company, only accept Switzerland
    • countryNumericCode string example: 756
      ISO-numeric code. For company, only accept Switzerland
    • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
      The path to get City object by city's id, /cities/{}
    • definitionName string example: 2nd address
      definition name of this address; in case main address, value is null; else value is not blank
    • additionalAddress string example: No. 13, street 123
      Additional address for more specific
  • language string required pattern: \S example: de
    Preferred language of the company. Supported: English, German, French, Italian
    Allowed values: de, en, fr, it
  • corporateIdentificationNumber string example: CHE-123.456.789
    Every business active in Switzerland is given a unique enterprise identification number (UID). To ensure that numbers are correctly allocated and managed, the UID register is run by the Federal Statistical Office
  • foundingDate string (date) format: date example: 2019-12-20
    Founding date of this company in ISO 8601 format (yyyy-mm-dd)
Responses 6
201 Tenant and company created show body

application/json array of Tenant

Array of Tenant.

  • tenant_id string example: aaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
  • company_id integer (int64) format: int64 example: 1
  • company_name string example: ABC Company
400 Invalid company data show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response
401 Invalid credentials show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response
403 The user has been disabled show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response
429 API rate limit exceeded no response body
500 Something went wrong when creating tenant and business company show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response
PUT/core/v2/tenants/companieskey / tokenUpdate a KLARA business company
A Klara user might have multiple tenants. Use this endpoint to update a KLARA business company. Use your KLARA token from your username & password & tenant-id.
Request body
The updated company information

application/json BusinessCompany

  • name string required pattern: \S example: ABC-Corp
    Name of the company
  • legalForm object required example: LIMITED_LIABILITY
    Legal form of a company. Can be one of the following:
    • Limited liability company(GmbH)
    • Public limited company (AG)
    • Individually owned company (EU)
    • Association (V)
    • Simple partnership (EG)
    • General partnership (KG)
    • Limited partnership (KDG)
    • Cooperative company (G)
    • Foundation (S)
    • OR
  • phones array of Phone required
    Phone numbers of the company
    show fields

    Array of Phone.

    • id string example: 1
      Id of this Phone. Does not need to be included when creating customer.
    • phoneNumber string required example: 41783334444
    • type object required example: PRIVATE
      Type of this phone number. For company, only OFFICE type is supported
  • emails array of Email required
    Emails of this company
    show fields

    Array of Email.

    • id string example: 1
      Id of this Email. Does not need to be included when creating customer
    • emailAddress string example: example@gmail.com
      Email address
    • type object required example: PRIVATE
      Type of this email
  • addresses array of Address required
    Address list of this company, at least one should be add. For company, address type MUST be PRIVATE
    show fields

    Array of Address.

    • id string example: 1
      Id of this Address. Does not need to be included when creating customer
    • validFrom string (date) format: date
      The timestamp from which this address is valid
    • validTo string (date) format: date
      The timestamp to which this address is valid
    • addressLines string required example: Chemin de la Caquerette 12
      The address lines for this Address
    • addressType string required pattern: \S example: WORK
      The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
    • cityName string required pattern: \S example: Bern
      Name of this City
    • cityZipCode string example: 3003
      The postal code of a city for this address
    • countryIso2Code string required pattern: \S example: CH
      2 letter country code. For company, only accept Switzerland
    • countryIso3Code string example: CHE
      3 letter country code. For company, only accept Switzerland
    • countryNumericCode string example: 756
      ISO-numeric code. For company, only accept Switzerland
    • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
      The path to get City object by city's id, /cities/{}
    • definitionName string example: 2nd address
      definition name of this address; in case main address, value is null; else value is not blank
    • additionalAddress string example: No. 13, street 123
      Additional address for more specific
  • language string required pattern: \S example: de
    Preferred language of the company. Supported: English, German, French, Italian
    Allowed values: de, en, fr, it
  • corporateIdentificationNumber string example: CHE-123.456.789
    Every business active in Switzerland is given a unique enterprise identification number (UID). To ensure that numbers are correctly allocated and managed, the UID register is run by the Federal Statistical Office
  • foundingDate string (date) format: date example: 2019-12-20
    Founding date of this company in ISO 8601 format (yyyy-mm-dd)
Responses 6
201 Company updated show body

application/json BusinessCompany

  • name string required pattern: \S example: ABC-Corp
    Name of the company
  • legalForm object required example: LIMITED_LIABILITY
    Legal form of a company. Can be one of the following:
    • Limited liability company(GmbH)
    • Public limited company (AG)
    • Individually owned company (EU)
    • Association (V)
    • Simple partnership (EG)
    • General partnership (KG)
    • Limited partnership (KDG)
    • Cooperative company (G)
    • Foundation (S)
    • OR
  • phones array of Phone required
    Phone numbers of the company
    show fields

    Array of Phone.

    • id string example: 1
      Id of this Phone. Does not need to be included when creating customer.
    • phoneNumber string required example: 41783334444
    • type object required example: PRIVATE
      Type of this phone number. For company, only OFFICE type is supported
  • emails array of Email required
    Emails of this company
    show fields

    Array of Email.

    • id string example: 1
      Id of this Email. Does not need to be included when creating customer
    • emailAddress string example: example@gmail.com
      Email address
    • type object required example: PRIVATE
      Type of this email
  • addresses array of Address required
    Address list of this company, at least one should be add. For company, address type MUST be PRIVATE
    show fields

    Array of Address.

    • id string example: 1
      Id of this Address. Does not need to be included when creating customer
    • validFrom string (date) format: date
      The timestamp from which this address is valid
    • validTo string (date) format: date
      The timestamp to which this address is valid
    • addressLines string required example: Chemin de la Caquerette 12
      The address lines for this Address
    • addressType string required pattern: \S example: WORK
      The type of address, could be [PRIVATE, WORK, SHIPPING]. For company, address type MUST be PRIVATE.
    • cityName string required pattern: \S example: Bern
      Name of this City
    • cityZipCode string example: 3003
      The postal code of a city for this address
    • countryIso2Code string required pattern: \S example: CH
      2 letter country code. For company, only accept Switzerland
    • countryIso3Code string example: CHE
      3 letter country code. For company, only accept Switzerland
    • countryNumericCode string example: 756
      ISO-numeric code. For company, only accept Switzerland
    • city_href string read-only example: https://api.klara.ch/core/latest/cities/1
      The path to get City object by city's id, /cities/{}
    • definitionName string example: 2nd address
      definition name of this address; in case main address, value is null; else value is not blank
    • additionalAddress string example: No. 13, street 123
      Additional address for more specific
  • language string required pattern: \S example: de
    Preferred language of the company. Supported: English, German, French, Italian
    Allowed values: de, en, fr, it
  • corporateIdentificationNumber string example: CHE-123.456.789
    Every business active in Switzerland is given a unique enterprise identification number (UID). To ensure that numbers are correctly allocated and managed, the UID register is run by the Federal Statistical Office
  • foundingDate string (date) format: date example: 2019-12-20
    Founding date of this company in ISO 8601 format (yyyy-mm-dd)
400 Invalid company data show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response
401 Invalid credentials show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response
403 The user has been disabled show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response
429 API rate limit exceeded no response body
500 Something went wrong when updating tenant show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response

Company general4

GET/core/latest/company-configuration/including-vatkey / tokenGet the VAT inclusion setting for the authenticated company.
Returns whether invoice amounts for the company resolved from the bearer JWT are displayed and calculated including VAT (includingVat: true) or excluding VAT (includingVat: false). Use this value before creating or displaying invoices to apply the correct pricing model. When no configuration record exists for the company, the endpoint returns false (excluding VAT) as the default. The caller must hold the FINANCE permission on the target company.
Required permission

FINANCE

Responses 5
200 VAT inclusion setting for the authenticated company. show body

application/json CompanyConfigurationIncludingVatResult

  • includingVat boolean example: False
    Whether invoice amounts for the authenticated company are displayed and calculated including VAT. When true, VAT is baked into the displayed prices. When false, VAT is shown as a separate line item. Returns false when no configuration record has been set for the company.
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/latest/company-vatskey / tokenReturns vat list of a company
Parameters 1
NameDescription
Accept-Language
header string
Responses 3
200 Company vats show body

application/json array of CompanyVAT

Array of CompanyVAT.

  • id string example: 123
    Id of the company VAT.
  • hasVat boolean
    Flag mark the company have VAT or not.
  • vatNumber string example: ABC-123
    The VAT number.
  • validFrom string (date) format: date
    The company VAT is valid from this time.
  • validTo string (date) format: date
    The company VAT is invalid after this time.
  • companyId integer (int64) format: int64 example: 1
    Id of the company
  • vats array of VAT
    This is list VAT value of the company.
    show fields

    Array of VAT.

    • id string example: 1
      Id of the VAT.
    • vatCode string example: ABC
      Code of the VAT.
    • rate number example: 5
      Rate of the VAT. Rate unit is percentage (%)
    • description string example: VAT's description
      The additional infomation for VAT.
    • validFrom string (date) format: date
      The VAT is valid from this time.
    • validTo string (date) format: date
      The VAT is invalid after this time.
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/latest/vat-caseskey / tokenReturns VAT case list.
Parameters 2
NameDescription
applicability
query string
Allowed values: REVENUE, COST
Accept-Language
header string
Responses 3
200 VAT cases show body

application/json array of VatCase

Array of VatCase.

  • id string example: 1
    Id of the VAT Case.
  • vatCaseCode string example: ABC
    Code of the VAT Case.
  • description string example: VAT Case's description
    The additional infomation for VAT.
  • referenceMasterVat string
    The reference master for VAT.
  • vatCaseNames object
    The map contain VAT case names in many languages.
    show fields

    Open map with values of type string.

  • applicability object example: REVENUE
    The VAT case type.
  • orderNumber integer (int32) format: int32 example: 2
    This value present how this VAT case order in the list as sequence.
  • createDate string (date-time) format: date-time
    The date that VAT Case created.
  • updateDate string (date-time) format: date-time
    The date that VAT Case updated.
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated
GET/core/latest/vat-cases/{vat-case-id}key / tokenGet the VAT case by Id.
Parameters 2
NameDescription
vat-case-id required
path string
Accept-Language
header string
Responses 3
200 VAT case show body

application/json VatCase

  • id string example: 1
    Id of the VAT Case.
  • vatCaseCode string example: ABC
    Code of the VAT Case.
  • description string example: VAT Case's description
    The additional infomation for VAT.
  • referenceMasterVat string
    The reference master for VAT.
  • vatCaseNames object
    The map contain VAT case names in many languages.
    show fields

    Open map with values of type string.

  • applicability object example: REVENUE
    The VAT case type.
  • orderNumber integer (int32) format: int32 example: 2
    This value present how this VAT case order in the list as sequence.
  • createDate string (date-time) format: date-time
    The date that VAT Case created.
  • updateDate string (date-time) format: date-time
    The date that VAT Case updated.
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string deprecated

Company documents1

POST/core/latest/companies/{company-id}/documentskey / tokenUpload a document for a company
Uploads a single file under one of a fixed set of document categories. The tenant is derived from the bearer token; only the authenticated company's id may be used in the path. Maximum file size: 25 MB. For category LIABILITY_UPLOAD the downstream service additionally triggers asynchronous AI analysis (the upload response is returned regardless of the AI outcome). Required caller roles (enforced by the API gateway): COMPANY_ADMINISTRATOR, TRUSTED_USER or CUSTOMER_RELATIONSHIP_MANAGER.

Important: When uploading documents as part of the create booking functionality only the LIABILITY_UPLOAD category is allowed (the documents are automatically moved to LIABILITIES when the booking is created successfully via POST /core/v1/bookings). The GUI implementation of booking creation must therefore always pass LIABILITY_UPLOAD as the category value in the request body.
Parameters 1
NameDescription
company-id required
path integer (int64)
Identifier of the company that owns the document. Must match the company id carried by the bearer token, otherwise the request is rejected with 403.
format: int64
Request body required
Multipart body with two parts: 'category' (text) and 'file' (binary, ≤ 25 MB).

multipart/form-data CompanyDocumentUploadForm

  • category string required
    Document category. Determines where the file is stored and which downstream post-processing is triggered (e.g. LIABILITY_UPLOAD triggers asynchronous AI analysis). Important: For the create booking functionality, only LIABILITY_UPLOAD is allowed — the booking creation GUI must always use LIABILITY_UPLOAD when uploading documents in this context.
    Allowed values: SALARY_STATEMENTS, YEARLY_REPORTS, PAYMENT_FILES, INSURANCE_CERTIFICATES, SALARY_TRANSMISSIONS, OWN_DOCUMENTS, LIABILITY_UPLOAD, EXPENSES, LIABILITIES
  • file string (binary) required format: binary
    The document file to upload. Maximum size 25 MB. Allowed file types are enforced by the downstream service.
Responses 8
200 Document successfully uploaded. show body

application/json object

  • documentId string example: 550e8400-e29b-41d4-a716-446655440000
    Identifier of the stored document, assigned by the document service.
400 Data invalid show body

application/json ErrorMessage1

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string
401 No Authorization header found or invalid token no response body
403 The current user is not allowed to access this company data show body

application/json ErrorMessage1

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string
413 Uploaded file exceeds the 25 MB limit. show body

application/json ErrorMessage1

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string
415 Unsupported Media Type no response body
429 API rate limit exceeded no response body
500 Something went wrong on our side while processing the request. Please kindly contact our support. show body

application/json ErrorMessage1

  • uuid string
  • createdTime string
  • code string
  • message string
  • detail string

Location1

GET/core/latest/cities/{city-id}key / tokenReturns city details
Returns a City details with given id.
Parameters 1
NameDescription
city-id required
path string
City id
example: 1
Responses 4
200 Found city show body

application/json City

  • id integer (int64) format: int64 read-only example: 1
    The id of this City object
  • zipCode string example: 8034
    The postal code for this city
  • basicPostcode string
  • name string example: Gerlafingen
    Name of this City
  • cityName27 string
  • state object
    A partner State.
    show fields
    • id string read-only
    • code string example: VD
      Code of this State
    • description string example: Vaud
      Extended description of this State
  • community object
    A Community that this partner locates.
    show fields
    • id string read-only
    • bfsNumber integer (int32) format: int32 example: 5480
      BFS number of this Community
    • communityName string example: Daillens
      Name of this Community
    • conurbationNumber string example: 5586
      Conurbation number of this Community
    • state object
      A partner State.
      show fields
      • id string read-only
      • code string example: VD
        Code of this State
      • description string example: Vaud
        Extended description of this State
  • country object
    A Country that this partner locates.
    show fields
    • id string read-only
    • countryName string example: Schweiz
      Name of this Country
    • iso2Code string example: CH
      2 letter country code
    • iso3Code string example: CHE
      3 letter country code
    • phoneCode string example: 41
      Country calling code
    • numericCode string example: 756
      ISO-numeric code
401 No Authorization header found or invalid token no response body
404 Resource not found no response body
429 API rate limit exceeded no response body

Subscription1

POST/core/latest/subscriptionskey / tokenCreate subscriptions for KLARA tenants.
A KLARA user might have multiple subscriptions. Each subscription will enable a set of feature inside KLARA platform. This endpoint allows to create subscriptions for a KLARA tenant.

Each subscription is subjective to its own terms and conditions. Please ask your KLARA contacts or see more details using the KLARA webclient.

Parameters 1
NameDescription
marketing-code
query array of string
Marketing code to identify which product will be subscribed. The marketing codes to create subscriptions for.
example: K-01-0002-00-M
Responses 6
201 Subscription created successfully show body

application/json array of Subscription

Array of Subscription.

  • product object required
    A product in KLARA widget store. Enable different features for users.
    show fields
    • code string required pattern: \S example: PRINTANDSENT
      Identifier code for each product-should be unique across all products
    • name string required example: Print and sent
      The name of the product
  • marketingCodes array of string required example: K-01-0002-00-M, K-02-0005-00-Y
    Marketing code to identify which product will be subscribed.
  • pricePlan object example: MONTHLY
    Specify how the subscription is paid.
    • SINGLE: Pay once for the whole subscription period.
    • VOLUME: Pay once for the whole subscription period and pay for each volume.
    • MONTHLY: Pay monthly for the subscription period.
    • QUARTERLY: Pay quarterly for the subscription period.
    • YEARLY: Pay yearly for the subscription period.
    • FREE: Free subscription.
    • PAY_PER_USE: Pay for each usage.
  • price number read-only example: 10
    The price of this subscription at this moment
  • subscriptionFrom string (date-time) format: date-time example: 2023-11-20 T10:15:30
    Specify when the subscription will start effectively. By default, the start date is today
  • subscriptionUntil string (date-time) format: date-time read-only example: 2024-11-20 T10:15:30
    Specify when the subscription will end effectively after unsubscribe. This value will be calculated by service itself.
  • renewalDate string (date) format: date example: 2024-20-11
    Indicates the date that subscription will automatically renewed for another period if no cancellation is made before this date.
400 Invalid subscription data show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response
401 Invalid credentials show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response
403 The user has been disabled show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response
429 API rate limit exceeded no response body
500 Something went wrong when creating subscriptions for the company show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response

Authentication

Authentication3

POST/core/latest/tenantspublicReturns all tenants of a user
A Klara user might have multiple tenants. Use this endpoint to get the list of tenants containing tenant id, company id.
The tenant and company id returned by this endpoint can be used to generate tokens to access other endpoints. Use your KLARA username and password OR access-token to get the list of tenants.
Request body

application/x-www-form-urlencoded object

  • username string
  • password string
  • access_token string
Responses 6
200 Found tenants show body

application/json array of Tenant

Array of Tenant.

  • tenant_id string example: aaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
  • company_id integer (int64) format: int64 example: 1
  • company_name string example: ABC Company
400 Missing parameters show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response
401 Invalid credentials show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response
403 The user has been disabled show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response
429 API rate limit exceeded no response body
500 Something went wrong when getting list of tenants show body

application/json ErrorResponse

  • error string
    Summary of the error response
  • error_description string
    Description of the error response
POST/core/latest/tokenpublicGenerate tokens to access other KLARA core endpoints
After obtaining tenant id and company id for the desired tenant, use this endpoint to get the access token for a specific tenant, and refresh token.
A grant_type of password is used for a Password grant, which requires username, password, tenant and company id to produce access token, refresh token from scratch.
A grant_type of refresh_token is used for a Refresh token grant, which is used for acquiring the access token using refresh token.
A grant_type of token_exchange performs an OAuth 2.0 Token Exchange (RFC 8693). Provide subject_token (the raw upstream Bearer token, without the 'Bearer ' prefix) and audience to identify the target token type.
Supported audience values:
  • cossa — exchanges a COSSA bearer token for a ePost access token.
Note: subject_token must be the raw token value without the 'Bearer ' prefix.
Request body

application/x-www-form-urlencoded object

  • username string default:
  • password string default:
  • grant_type string default:
  • tenant_id string default:
  • company_id string default:
  • refresh_token string default:
  • subject_token string default:
  • audience string default:
Responses 5
200 Token created show body

application/json PublicAPIToken

  • access_token string
    Token used to access KLARA Public API endpoints, should be place at Authorization header of request. Access token is valid only for one company tenant
  • expires_in integer (int64) format: int64
    Amount of time in seconds left that the access token is valid for
  • refresh_expires_in integer (int64) format: int64
    Amount of time in seconds left that the refresh token is valid for
  • refreshToken string
    Token used to renew the access token
  • token_type string
    Type of access token that should be included in the Authorziation header of each request
400 Could not get token no response body
401 Invalid credentials no response body
429 API rate limit exceeded no response body
500 Internal server error no response body
POST/core/latest/token/by-microsoftpublicExchange Microsoft access token for system token
Provide a Microsoft access token and tenant id to exchange for a system token.
Request body

application/x-www-form-urlencoded object

  • microsoft_access_token string
  • tenant_id string
Responses 5
200 Token created show body

application/json AccessTokenResponse

  • access_token string
  • expires_in integer (int64) format: int64
  • refresh_expires_in integer (int64) format: int64
  • refresh_token string
  • token_type string
  • id_token string
  • not-before-policy integer (int32) format: int32
  • session_state string
  • otherClaims object
    show fields

    Open map with values of type object.

400 Could not get token no response body
401 Invalid credentials no response body
429 API rate limit exceeded no response body
500 Internal server error no response body

Klara authentication generic1

POST/core/latest/generic-tokenpublicGenerate tokens to use Klara specific endpoint
Use this endpoint to get the access token for a specific user, and refresh token.
A grant_type of password is used for a Password grant, which requires username, password, access token, refresh token from scratch.
A grant_type of refresh_token is used for a Refresh token grant, which is used for acquiring the access token using refresh token.
Request body

application/x-www-form-urlencoded object

  • username string default:
  • password string default:
  • grant_type string default:
  • refresh_token string default:
Responses 5
200 Token created show body

application/json PublicAPIToken

  • access_token string
    Token used to access KLARA Public API endpoints, should be place at Authorization header of request. Access token is valid only for one company tenant
  • expires_in integer (int64) format: int64
    Amount of time in seconds left that the access token is valid for
  • refresh_expires_in integer (int64) format: int64
    Amount of time in seconds left that the refresh token is valid for
  • refreshToken string
    Token used to renew the access token
  • token_type string
    Type of access token that should be included in the Authorziation header of each request
400 Could not get token no response body
401 Invalid credentials no response body
429 API rate limit exceeded no response body
500 Internal server error no response body

Changelog

Entries are produced by comparing the new specification against the previous one, so nothing is missed when we publish a release. Breaking changes are marked as such.

7 August 2026

Initial publication

First release of this documentation: 97 endpoints. Accounting, finance and payroll are served under /core/v1, articles, customers and authentication under /core/latest.

Highlights

  • POST /core/v1/payroll/contracts/{contractId}/payslips/{payslipId}/salary-items adds variable salary items to a payslip.
  • GET /core/v1/employees/short-info returns an employee directory with search, filtering and sorting.
  • POST /core/v1/invoices/{id}/send sends through email, ePost, eBill or print.

This page is updated when a new API version is released. Subscribing to changes by feed is on our list.

Known limitations

We open KLARA step by step rather than all at once. These are the gaps we know about, listed here so you find out before you build rather than halfway through.

Separately, KLARA operates file-based interfaces for certified payroll partner systems. They are not part of this documentation. If you are a payroll partner, contact support.

Are you blocked by one of these? Tell us via support and describe what you are building. That is what shapes what we open next.

FAQ

Straight answers, including where the API cannot help you yet. Better to find out here than halfway through an integration.

Is an OpenAPI specification available?

Yes. Download it here. Use it to generate clients, mock servers or contract tests.

Can I list all invoices, or filter them by status?

Not yet. GET /core/v1/invoices/{id} returns a single invoice including status, bookingStatus, paymentDate and bookingDueDate, but there is no collection endpoint, so you need to keep the ids in your own system. See Known limitations.

Can I write variable payroll data?

Yes. Add salary items such as hours, allowances and bonuses to an employee's editable payslip. See Submitting variable payroll data. Master data such as contracts and base salaries is still not writable through the API.

Is there a general order API?

No. Order endpoints exist only as a two-step partner protocol and are not part of this documentation. For webshop integrations, create a customer and an invoice instead. See Getting started.

Are there webhooks?

No. You need to poll, and poll gently. See rate limiting. If this blocks your use case, let us know and describe what you are building.

Can I book appointments through the API?

No. Despite the role name, KLARA Online Terminbuchung has no public endpoints. The tag SHRM Booking refers to salary-run bookings, not calendar appointments.

Why do I get a 401 even though my API key is correct?

Every endpoint that requires authentication accepts either an API key or a bearer token, so the method is not the problem. Check three things instead: the key belongs to the company whose data you are requesting, the header is spelled X-API-KEY, and the user behind the key holds the permission the endpoint needs. See Roles & permissions. Note that the token endpoints themselves take no authentication at all, listed under Authentication.

Why do ePost and eBill appear in a KLARA API?

They are delivery channels for KLARA invoices, not separate products you need to integrate. See Sending documents. If you are building on the ePost Communication Platform itself, you want developer.epost.ch.

Why is my use case not supported?

We open KLARA step by step rather than all at once. The gaps we already know about are listed under Known limitations. If yours is not there, tell us via support and describe what you are building. That is what shapes what we open next.

Support

Questions and problem reports: support.klara.ch. When reporting an error, include the uuid from the error response and the steps to reproduce it, but never your API key or any credentials.

What this documentation is, and what it is not The KLARA API is provided as is, on the basis of this documentation. We do not offer guided implementation or code support for individual integrations. If you would rather not build it yourself, a KLARA integration partner can do it for you.

Every release is recorded in the changelog, including breaking changes.