> For the complete documentation index, see [llms.txt](https://docs.younium.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.younium.com/erp-and-accounting-integrations/kleer.md).

# Kleer

## Synchronisation scope

| Synchronisation           | Direction       | When it runs                                                        |
| ------------------------- | --------------- | ------------------------------------------------------------------- |
| Invoices and credit notes | Younium → Kleer | When an invoice is posted in Younium, if invoice posting is enabled |
| Accounts                  | Younium → Kleer | On demand from the integration settings, or as a scheduled job      |
| Accounts                  | Kleer → Younium | On demand from the integration settings, or as a scheduled job      |
| Products                  | Kleer → Younium | On demand from the integration settings, or as a scheduled job      |
| Exchange rates            | Kleer → Younium | On demand from the integration settings, or as a scheduled job      |
| Users and categories      | Kleer → Younium | On demand from the integration settings                             |

Not in scope: payments, journals, invoice cancellations.

***

## Overview

The Kleer integration connects a Younium legal entity to one company in Kleer. Younium keeps customers in step between the two systems, imports products and exchange rates from Kleer, and creates a customer invoice in Kleer each time an invoice is posted in Younium.

Customers can be synchronised in either direction. Exporting sends Younium accounts to Kleer as clients, creating new clients and updating those already linked. Importing reads every client in Kleer and creates or updates the matching Younium account. The two are linked through the Kleer client id that Younium stores on the account, and an invoice can only be sent to Kleer for an account that carries one.

Posted invoices are sent with their lines, addresses and references. Younium can optionally certify each invoice in Kleer straight away, attach the Younium invoice PDF, and write the Kleer invoice number back to the Younium invoice.

***

## Authentication

You connect one Younium legal entity to one Kleer company. To connect, you need a Kleer user with access to the company Younium should work in. A dedicated integration user is a better choice than a person's own login.

You sign in with that user's email address and password in the Kleer integration settings. Younium then lists every company the user can reach; companies that are not active in Kleer are shown with **(Test)** after their name. You choose the company and activate.

When the connection works, the integration shows as active with the company name, and the synchronisation and invoice settings become available. If Kleer refuses the sign-in, the integration is not activated and the reason Kleer gave is shown.

Younium uses the password only to establish the connection; it does not keep it. All later exchanges use the access Kleer granted for the chosen company. If Kleer later stops accepting that access, every exchange fails with *Couldn't authorize to Kleer* until the integration is activated again.

***

## Activation and deactivation

Activating connects the legal entity to the chosen Kleer company, as described above. It does not start any exchange: invoices are sent only once invoice posting is turned on and the settings are saved, and synchronisation runs only when it is started or scheduled.

Deactivating removes the Kleer settings and the connection, and stops invoice posting immediately. The custom fields the integration created stay in Younium with their values, so accounts and products keep their Kleer ids. Nothing is removed in Kleer.

***

## Save and setup

Saving the settings creates the **Pe-Accounting Invoice Number** custom field on invoices if it is missing, and starts or stops invoice posting to match the invoice posting setting. Turning posting off stops it at once; turning it back on resumes it for invoices posted from then on.

***

## Custom fields created by the integration

Younium creates these custom fields itself, the first time the exchange that needs them runs. They are created with the labels below, which still carry the integration's former name. The integration finds each field by its internal name, not by its label.

| Entity                                | Custom field                            | Type | Created when                            | Purpose                                                              |
| ------------------------------------- | --------------------------------------- | ---- | --------------------------------------- | -------------------------------------------------------------------- |
| Account                               | **Pe-Accounting Client Id**             | Text | Accounts are first exported or imported | Links the account to a Kleer client. Required for invoice posting    |
| Account                               | **Pe-Accounting Customer No**           | Text | Accounts are first imported             | The Kleer customer number. Sent back to Kleer on export              |
| Account                               | **Pe-Accounting User**                  | List | Users are synchronised                  | The Kleer user responsible for the customer                          |
| Account                               | **Pe-Accounting Category**              | List | Categories are synchronised             | A Kleer category (dimension entry) for the customer                  |
| Account                               | **Pe-Accounting Invoice Delivery Type** | List | Accounts are first exported or imported | The Kleer invoice delivery type for the customer                     |
| Product, Charge, Order product charge | **Pe-Accounting Product Id**            | Text | Products are first imported             | Links the product to a Kleer product. Required on every invoice line |
| Invoice                               | **Pe-Accounting Invoice Id**            | Text | The first invoice is posted             | The Kleer id of the invoice created                                  |
| Invoice                               | **Pe-Accounting Invoice Number**        | Text | Settings are saved                      | The Kleer invoice number, once the invoice is certified              |

The three list fields take their values from Kleer. Synchronising users fills **Pe-Accounting User** with every Kleer user in the company; synchronising categories fills **Pe-Accounting Category** with every active entry of every active Kleer dimension; and the first account export or import fills **Pe-Accounting Invoice Delivery Type** with the delivery types Kleer offers. Each list item keeps the Kleer id alongside the name shown in Younium.

***

## Account synchronisation

Accounts and Kleer clients are linked by **Pe-Accounting Client Id**. Export and import can be started from the integration settings, and each is also available as a scheduled job; the export job can be scheduled no more often than every 30 minutes. Each run is recorded in the integration log with the number of accounts synchronised, and each account that fails is logged with its account number and the reason.

> **Note on the shared sync time:** Export and import record a single *last account sync* time between them. An import moves that time forward too, so an account changed in Younium before an import but not exported since is not picked up by the next export until it is changed again.

### Export (Younium → Kleer)

**Which accounts are sent.** Every account whose **Account type** is not *Prospect* or *Other*. The first export sends all of them. After that, an export sends only accounts that have changed, or whose addresses have changed, since the last account sync.

**Create or update.** An account with a **Pe-Accounting Client Id** updates that client in Kleer. An account without one creates a new client, and Younium writes the new Kleer client id back to **Pe-Accounting Client Id**.

**Failures.** An account Kleer rejects is logged and skipped; the export continues with the next account. The last account sync time still moves forward, so a skipped account is sent again only once it changes. A Kleer *Method not allowed* response usually means the client id on the account no longer matches a client in Kleer.

#### Client

| Younium field                                                        | Kleer field    |
| -------------------------------------------------------------------- | -------------- |
| **Name**                                                             | `name`         |
| **Pe-Accounting Customer No** (empty if not set)                     | `foreign-id`   |
| **Payment term** — number of days (30 when the account has none)     | `payment-days` |
| **Org number**                                                       | `orgno`        |
| **Tax reg. nr**                                                      | `vat-nr`       |
| **Your reference**                                                   | `contact`      |
| **Inactive** — inverted                                              | `active`       |
| **Invoice email**, followed by **Invoice email Cc** separated by `;` | `email`        |
| Country of the **Invoice address** — two-letter code                 | `country-code` |
| — always empty                                                       | `phone`        |
| — always `0`                                                         | `accountnr`    |

#### Client address

The address sent is the account's default **Invoice address**. Fields the account does not have are sent empty.

| Younium field              | Kleer field        |
| -------------------------- | ------------------ |
| **Street**                 | `address.address1` |
| **Street 2**               | `address.address2` |
| **Zip**                    | `address.zip-code` |
| **City**                   | `address.state`    |
| **Country** — country name | `address.country`  |

#### Delivery type, user and category

**Delivery type** follows **Pe-Accounting Invoice Delivery Type** when the account has a value there. When it does not, Younium derives it from the account's **Invoice delivery method**. Whenever an electronic delivery type is sent and the account has an **E-Invoice Address**, that address is sent as `gln`.

| Younium value                                                           | Kleer field     | Kleer value                |
| ----------------------------------------------------------------------- | --------------- | -------------------------- |
| **Pe-Accounting Invoice Delivery Type**                                 | `delivery-type` | The selected delivery type |
| **Invoice delivery method** *Electronic invoice* (no delivery type set) | `delivery-type` | `Efaktura`                 |
| **Invoice delivery method** *Email* (no delivery type set)              | `delivery-type` | `Email`                    |
| **Invoice delivery method** *Print* (no delivery type set)              | `delivery-type` | `Mail`                     |
| **E-Invoice Address**                                                   | `gln`           | The address as entered     |

| Younium field                                                                              | Kleer field                                 |
| ------------------------------------------------------------------------------------------ | ------------------------------------------- |
| **Pe-Accounting User** — Kleer id of the selected user, `0` when none is selected          | `user.id`                                   |
| **Pe-Accounting Category** — Kleer id of the selected entry; omitted when none is selected | `dimension-entries.dimension-entries[0].id` |

### Import (Kleer → Younium)

**Which clients are read.** Every client in the Kleer company. A client that is inactive in Kleer and has no matching Younium account is skipped; an inactive client that is already linked is still updated, which marks the Younium account inactive.

**Create or update.** A client is matched to a Younium account by **Pe-Accounting Client Id**. When there is no match, Younium creates a new account with the legal entity's default values and sets **Pe-Accounting Client Id** and **Pe-Accounting Customer No** on it. Those two fields are set only when the account is created; an import never changes them on an existing account.

**Failures.** The import stops at the first client it cannot process and logs the reason. Accounts handled before that point keep their changes, and the last account sync time is not moved forward.

> **Note on overwriting:** Import treats Kleer as the master for the fields below. On every linked account it overwrites them with the Kleer values, including empty ones, makes the account a *Customer*, and clears **Site** and **Our reference**. Changes made to these fields in Younium are lost on the next import unless they are made in Kleer as well.

#### Account

| Kleer field                                 | Younium field                                                                                                                                    |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`                                        | **Pe-Accounting Client Id** (new accounts only)                                                                                                  |
| `foreign-id`                                | **Pe-Accounting Customer No** (new accounts only)                                                                                                |
| `name`                                      | **Name**                                                                                                                                         |
| `email`                                     | **Invoice email**                                                                                                                                |
| `vat-nr`                                    | **Tax reg. nr**                                                                                                                                  |
| `orgno`                                     | **Org number**                                                                                                                                   |
| `payment-days`                              | **Payment term** — the Younium payment term with the same number of days; left empty when there is none                                          |
| `contact`                                   | **Your reference**                                                                                                                               |
| `active`                                    | **Inactive** — set when the client is inactive in Kleer                                                                                          |
| `currency-type`                             | **Currency** — the Younium currency with the same code, when Kleer returns one                                                                   |
| `user.id`                                   | **Pe-Accounting User** — the matching user, once users have been synchronised                                                                    |
| `dimension-entries.dimension-entries[0].id` | **Pe-Accounting Category** — the matching entry, once categories have been synchronised. Only the first category on the Kleer client is imported |
| `delivery-type`                             | **Pe-Accounting Invoice Delivery Type**                                                                                                          |
| —                                           | **Account type** — always *Customer*                                                                                                             |
| —                                           | **Site** and **Our reference** — cleared                                                                                                         |

#### Invoice address

The address is imported only when the Kleer client has a country code. It updates the account's default **Invoice address**, or creates one — with the description *{account name} Address* — and makes it the default when the account has none.

| Kleer field        | Younium field                                                                                    |
| ------------------ | ------------------------------------------------------------------------------------------------ |
| `name`             | **Name**                                                                                         |
| `address.address1` | **Street**                                                                                       |
| `address.address2` | **Street 2**                                                                                     |
| `address.zip-code` | **Zip**                                                                                          |
| `address.state`    | **City**                                                                                         |
| `country-code`     | **Country** — matched on the two-letter code. A country that is inactive in Younium is activated |

***

## Product synchronisation

Products are imported from Kleer, from the integration settings or as a scheduled job. Each Kleer product is matched to a Younium product by **Pe-Accounting Product Id**.

A Kleer product with no match creates a new *Simple* product in Younium with one charge plan and one charge, all three named after the Kleer product, and **Pe-Accounting Product Id** set on the product and the charge. A matched product has its name, and the name of its first charge plan and charge, updated from Kleer, and its end of new sales date cleared.

A Younium product that was imported earlier but no longer appears in Kleer gets an end of new sales date of today, so it can no longer be sold. Its existing subscriptions are not changed.

| Kleer field | Younium field                                              |
| ----------- | ---------------------------------------------------------- |
| `id`        | **Pe-Accounting Product Id** on the product and its charge |
| `name`      | Product name, charge plan name and charge name             |

The product id travels with the charge onto subscriptions, and it is the id each invoice line is sent with.

***

## Exchange rate synchronisation

Exchange rates are imported from Kleer, from the integration settings or as a scheduled job that can run no more often than every 30 minutes. For each currency in Younium other than the base currency, Younium reads the current Kleer rate. When the rate differs from the one in effect, Younium ends the current rate yesterday and adds the new rate effective from today. A currency without any rate gets one effective from today. The run is logged with the number of rates added.

***

## Eligibility and filtering — posted invoices

Every posted invoice is sent once invoice posting is turned on. Younium refuses to send an invoice, and logs why, in these cases:

| Condition                                                                | Result                                                               |
| ------------------------------------------------------------------------ | -------------------------------------------------------------------- |
| The account has no **Pe-Accounting Client Id**                           | Not sent: the account has not been synchronised with Kleer           |
| A line's charge has no **Pe-Accounting Product Id**                      | Not sent: one or more products have not been synchronised from Kleer |
| Certifying is on and the invoice date is in the future                   | Not sent: Kleer does not certify future-dated invoices               |
| Certifying is on and the invoice date is more than 14 days ago           | Not sent: Kleer allows back-dating by 14 days at most                |
| An invoice with a negative total has no **Pe-Accounting Invoice Number** | Not sent: Kleer needs the number of the debit invoice being credited |

Lines are filtered before they are sent. Younium's own zero-amount line settings apply, and when the option to exclude zero-quantity recurring lines is on, recurring lines with a quantity of 0 are left out.

***

## Field mapping — posted invoice (Younium → Kleer)

### Invoice header

| Younium field                                                                                            | Kleer field                        |
| -------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| Invoice currency code                                                                                    | `currency`                         |
| **Pe-Accounting Client Id** on the invoice account                                                       | `client-ref.id`                    |
| Invoice number                                                                                           | `foreign-id`                       |
| Your order number                                                                                        | `po-nr`                            |
| Your reference                                                                                           | `your-reference`                   |
| Notes                                                                                                    | `notes`                            |
| **Invoice email** on the account                                                                         | `invoice-email`                    |
| Invoice date (`yyyy-MM-dd`)                                                                              | `invoice-date` and `delivery-date` |
| Due date (`yyyy-MM-dd`)                                                                                  | `due-date`                         |
| **Pe-Accounting User** on the account — Kleer id, `0` when none is selected                              | `our-reference.id`                 |
| Delivery address country, or invoice address country when there is no delivery address — two-letter code | `country-code`                     |
| **Pe-Accounting Client Id** on the order's account, when the option to map the invoice account is on     | `end-client.id`                    |
| **Pe-Accounting Invoice Number** on an invoice with a negative total, up to the first `(`                | `debit-invoice-nr`                 |

`delivery-name` and `delivery-email` are always sent empty.

### Addresses

Both addresses are always sent. When the invoice has no delivery address, the delivery address is sent with empty values.

| Younium field             | Kleer invoice address      | Kleer delivery address      |
| ------------------------- | -------------------------- | --------------------------- |
| Street                    | `invoice-address.address1` | `delivery-address.address1` |
| Street 2                  | `invoice-address.address2` | `delivery-address.address2` |
| Zip                       | `invoice-address.zip-code` | `delivery-address.zip-code` |
| City                      | `invoice-address.state`    | `delivery-address.state`    |
| Country — two-letter code | `invoice-address.country`  | `delivery-address.country`  |

### Invoice line

**Quantity and price.** Each line is sent with quantity 1 and the line subtotal as price. Two exceptions apply. A zero-amount line with a quantity is sent with its quantity, so the quantity still reaches Kleer. When the option to send quantity and price in Kleer custom fields is on, the line's quantity and unit price go to the Kleer invoice row fields *Antal Younium* and *Pris Younium* instead; for rated charges the unit price is the subtotal divided by the quantity.

**Description.** The charge description, followed by the quantity and unit of measure (unless quantity and price go to custom fields), the service period as `yyyy-MM-dd - yyyy-MM-dd`, and the line notes, separated by commas.

**Unit.** Sent for non-flat charges with a unit of measure when the quantity sent is not 1, or when quantity and price go to custom fields. Otherwise empty.

**Period.** Sent for recurring and usage lines when the option to map effective dates is on. When the accounting period containing the service period start is closed in Younium, the start moves to the first open accounting period, and the end moves with it if it falls before that date.

| Younium field                                            | Kleer field                                              |
| -------------------------------------------------------- | -------------------------------------------------------- |
| **Pe-Accounting Product Id** on the order product charge | `product.id`                                             |
| Quantity (see above)                                     | `quantity`                                               |
| Line subtotal × 100, as a whole number                   | `price`                                                  |
| Sum of the line's tax rates × 100, as a whole number     | `vat`                                                    |
| Description (see above)                                  | `description`                                            |
| Unit of measure display name (see above)                 | `unit`                                                   |
| Service period start / end (`yyyy-MM-dd`)                | `period.start-date` / `period.end-date`                  |
| Line quantity                                            | Row field `AntalYounium` (*Antal Younium*)               |
| Unit price                                               | Row field `PrisYounium` (*Pris Younium*), omitted when 0 |

### Invoice fields and attachment

| Younium value                                          | Kleer field                                                     | Sent when                                                       |
| ------------------------------------------------------ | --------------------------------------------------------------- | --------------------------------------------------------------- |
| Online payment link key                                | Invoice field `StripeLink` (*Stripe link*)                      | The option to map the Stripe link is on and the invoice has one |
| Invoice number                                         | Invoice field `YouniumFakturanummer` (*Younium Invoice number*) | The option to map the Stripe link is on                         |
| Younium invoice PDF, as `Younium_Invoice_Template.pdf` | `files`                                                         | The option to send the invoice PDF is on                        |

### Categories

When the option to apply categories from the Kleer customer is on, Kleer fills the invoice's categories from the client. When the option to apply categories from the Kleer product is on, Kleer fills them from each product. Both can be on together.

### Write-back (Kleer → Younium)

| Kleer value    | Younium field                                                      | Written when                                                     |
| -------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------- |
| Invoice id     | **Pe-Accounting Invoice Id**                                       | Always, once Kleer has created the invoice                       |
| Invoice number | **Pe-Accounting Invoice Number** and the invoice's external ERP id | Only when certifying is on, once Kleer has certified the invoice |

Kleer gives an invoice its number only when it is certified, so without certifying Younium receives the id but no number.

***

## Post invoice workflow

**Runs when:** an invoice is posted in Younium, while invoice posting is turned on.

Younium checks the invoice against the eligibility rules, then creates the customer invoice in Kleer. Requests to Kleer are paced to stay within its rate limit, so a large batch is sent steadily rather than all at once.

**Certifying.** When certifying is on, Younium certifies the new Kleer invoice immediately. If Kleer refuses to certify it, Younium deletes the invoice it just created in Kleer, so no uncertified copy is left behind, and the posting fails with Kleer's reason. For a credit invoice the usual reason is that the debit invoice has already been credited in Kleer. After certifying, Younium reads the invoice number from Kleer, trying up to three times. If the number still is not available, the invoice stays posted in both systems and the missing number is recorded in the integration log.

**Outcome.** Each invoice sent is logged as *Younium invoice {number} was created in Kleer*. When an invoice cannot be sent, the failure is logged with Kleer's message or the eligibility rule that stopped it.

> **Note on credit invoices:** An invoice with a negative total is sent as a credit of a specific Kleer debit invoice. Younium takes the Kleer number of that debit invoice from **Pe-Accounting Invoice Number** on the credit invoice itself, so the field must hold it before the credit invoice is posted.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.younium.com/erp-and-accounting-integrations/kleer.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
