The JTL-Klar-Sync automatically transfers your orders from JTL-Wawi 1.x to Klar. You install a program on the machine where JTL-Wawi runs. After that, the transfer keeps running in the background without you having to do anything.

⚠️ Beta test — version 1.0.0-beta.15
The program is in beta testing. It is signed by Klar Insights GmbH and reports new versions itself. The Updates section explains how that works. Report problems to [email protected].

Download Link: jtl-klar-sync-setup.exe

1. What the program does

The program consists of three parts:

Part	Where it runs	Task
Windows service	In the background, always	Reads the orders and sends them to Klar
Taskbar app	In your Windows session, next to the clock	Shows the status. Starts tasks. Reports updates.
Setup wizard	Once, on first launch	Asks for the credentials and the import period

The work is done by the service. The taskbar app only shows the status. If you close it, the transfer keeps running.

The service runs these steps in each cycle:

It resends orders that failed in an earlier cycle.
It reads the new orders from JTL-Wawi.
It looks for changes in the orders of the last 90 days.
It looks for orders that you deleted in JTL-Wawi.
It sends the result to Klar.

The default interval between two cycles is 1 hour. You can change it in the settings window.

Why one error stops everything

If Klar rejects a group of orders, the service stops. It reads no new orders. It resends the failed group, with increasing wait time, until Klar accepts it.

This is intentional. That way no order is lost. But it also means: a persistent error stops all new orders. Check the taskbar menu when the Errors line is no longer at 0.

How changes are detected

JTL-Wawi cannot tell the program which orders have changed. The program therefore compares, in each cycle, the orders of the last 90 days with the last known state.

The program detects one type of change only with a delay: a change to a line item that does not change the order total. An example is a corrected SKU. The program finds such changes with a slow pass that checks all orders once every 24 hours. The maximum delay is therefore 24 hours.

How deletions are detected

When an order is no longer in JTL-Wawi's response, the program asks JTL-Wawi again specifically for that order. If JTL-Wawi replies that the order does not exist, it is treated as deleted. The program then reports it to Klar as cancelled. It uses the last known state of the order for this.

2. Which data goes to Klar

Only order data goes to Klar. The program sends no product master data, no stock levels and no supplier data.

For each order, the program sends:

Order ID, order number and the order's dates
Payment status and shipping status
Currency, totals, taxes and discounts
Name of the payment method and name of the payment provider
The line items: SKU, product name, quantity, amounts, taxes and discounts
Product tags: the item's category paths, its product group and released custom fields
Shipping costs and shipping taxes
Refunds and returns, matched via the SKU
The customer number from JTL-Wawi
The customer's email address, or a hash of the email address (see below)
From the shipping address: city, state, postal code and country
The Google Analytics transaction ID (see below)

The program does not send the customer's name. It does not send the street.

The email address

By default, the program sends the customer's email address to Klar.

You can set a Hash salt in the settings window. The program then sends a SHA1 hash of the email address instead of the address itself. The address then does not leave the machine.

Caution: The salt must be the same salt that Klar uses. Agree on it with us. If you change the salt later, Klar sees all customers as new customers.

The Google Analytics transaction ID

Klar links an order to the matching transaction in GA4 via this ID. For this, the program must send the same field that your shop sends to GA4.

You choose the field in the settings window under GA transaction id. There are three options:

Option	What is sent
externalNumber (falls back to number) — Default	The external order number from JTL, for example the order number from JTL-Shop or from the marketplace. If it is missing, the program sends the JTL order number.
number	Always the JTL order number, with no fallback
id	The internal, numeric order ID from JTL-Wawi

The default fits most shops. When in doubt, check in GA4 which value is shown there as the transaction ID, and choose the same field here.

Caution: A change only affects new and changed orders. Orders already transferred keep the old ID. To bring them up to date, you need Re-export: full refresh from JTL (section 9). The other two re-export variants resend the stored state and change nothing.

Where the credentials are stored

The program stores the JTL-Wawi API key and the Klar token in the file config.yaml. Both values are encrypted with the Windows Data Protection API and bound to the machine. Only the same machine can decrypt them.

3. Requirements

Item	Requirement
Operating system	Windows 10, Windows 11, or Windows Server 2019 or newer
Architecture	64-bit
JTL-Wawi	Version 1.x, on the same machine as the program
JTL-Wawi API	The JTL-Wawi API license, booked in the JTL-Kundencenter
JTL API server	Started and reachable at `http://127.0.0.1:5883/api/eazybusiness/`
Klar	A Klar account and an access token (see section 4)
Permissions	Administrator rights, only for the installation and for updates
Disk space	100 MB for the program. About 2 MB per 1,000 orders.
Network	Outbound HTTPS to the Klar API and to the Klar update server

The program needs no database of its own and no web server of its own.

Note for terminal servers and servers without a graphics card

The setup wizard and the settings window need OpenGL 2.1 or newer. The taskbar icon and the service need no OpenGL.

Caution: On a server without a graphics adapter and in some remote desktop sessions, OpenGL may be missing. The setup wizard may then not open. In that case, run it directly at the machine's console. Please report this case to us — we want to know whether it occurs in practice.

4. Preparation

Have these five things ready before you install:

Download the installation file jtl-klar-sync-setup.exe
Administrator rights on the JTL-Wawi machine.
The JTL-Wawi API license. Book it in the JTL-Kundencenter.
A JTL-Wawi user who is allowed to accept an app registration.
The Klar access token (see below).

Good to know: The JTL-Wawi API is free during the JTL beta phase. JTL charges for it after the official release.

Without an API license, JTL-Wawi answers every request with HTTP 402. The setup wizard then shows a note about the license. As long as the license is missing, no order reaches Klar.

Creating the Klar access token

The token authorizes the program to write your orders into Klar. You create it in the Klar dashboard.

Go to Settings → Store Configurator → your store → Data Sources.
Click Connect Data Source.
In the dialog, select Klar API.
Give the data source a name, for example JTL-Wawi, and save it.
Open the new data source.
Go to the Access Token tab.
Click Copy Token.

The token is a long string that begins with eyJ. Full description: API Authentication.

Caution: Create a separate data source for JTL-Wawi. Do not use the token of an existing data source that already delivers orders from another source.

5. Installation

Copy jtl-klar-sync-setup.exe to the JTL-Wawi machine.
Double-click the file.
Confirm the User Account Control prompt with Yes. The publisher shown there is Klar Insights GmbH.
Confirm the suggested destination folder and click Install.
Wait until the installation is finished.
Click Close.

Installer: choosing the destination folder with the Install button.

Good to know: For a brand-new version, Windows may show a one-time SmartScreen notice despite a valid signature, because the file has rarely been downloaded so far. In that case, check that the publisher is Klar Insights GmbH and continue. Do not turn off any virus scanner.

The installation does the following:

It copies the program to C:\Program Files\JtlKlarSync\.
It creates the data folder C:\ProgramData\JtlKlarSync\.
It registers the Windows service JtlKlarSync. The service runs as NetworkService.
It creates four Start menu entries (see section 11).
It creates an autostart entry so that the taskbar app starts at every sign-in.
It starts the taskbar app.

For a first-time installation, the installer does not start the service yet. The setup wizard does that.

The setup wizard opens automatically after the installation, because no configuration exists yet.

6. The setup wizard

The wizard has three steps. Do not close the window before step 3 is finished. The wizard's interface is in English, JTL-Wawi is in German.

Step 1 of 3 — Connect to JTL WaWi

In this step, the program registers itself as an app in JTL-Wawi. JTL-Wawi gives the program an API key for this.

Important: Open the app registration in JTL-Wawi first. JTL-Wawi must be waiting for the request before you send it in the wizard. Otherwise the API rejects the request.

Open JTL-Wawi.
Sign in to the same database that the API serves. The database name is shown in the API URL in the wizard, usually eazybusiness.
Open Admin and then App-Registrierung.
Start a new app registration.
Switch to the setup wizard.
Check the API URL. The default value is http://127.0.0.1:5883/api/eazybusiness/.
Change the port if the JTL API server uses a different port.
Click Register with JTL-Wawi.
Switch to JTL-Wawi.
Accept the Klar Sync request.
Assign the JTL-Wawi user under which the program should work.
Grant the requested permission. The program needs only read rights (all.read).
Click Fertigstellen.
Switch to the wizard. It shows ✓ Registered — API key received. Click Continue.
Click Continue ▸.

Setup wizard, step 1 of 3, with the API URL field and the Register with JTL-Wawi button.

JTL-Wawi: Admin ▸ App-Registrierung with the open Klar Sync request.

JTL-Wawi: user assignment and permission approval, with the Fertigstellen button.

Setup wizard with the success message ✓ Registered — API key received.

The wizard asks JTL-Wawi for the result every 3 seconds. After 10 minutes it aborts. Restart the process in that case.

Caution: JTL-Wawi hands out the API key only once, and only per app ID. It cannot hand out the same key again. Keep a copy of the key in a safe place.

If you already have an API key — for example after a reinstallation:

Click I already have an API key.
Enter the existing key.
Click Continue ▸.

Good to know: After a Factory Reset, the wizard offers the old key by itself, provided it still works. The Use the preserved API key button then appears. Use it — a new registration with the same app ID would be rejected.

Step 2 of 3 — Connect to Klar

Leave the pre-filled API URL unchanged, unless Klar has given you a different URL.
Paste the Klar token into the Access token field.
Click Continue ▸.

Good to know: The wizard does not check the token in this step yet. You can check the connection at any time after setup in the settings window with Test connection. On success, ✓ Connected to Klar. appears there.

Setup wizard, step 2 of 3, with the API URL and Access/Bearer token fields.

Step 3 of 3 — Sync settings

Here you set how far back the history should reach and how fast the program is allowed to work.

Order history

Under Import orders from, choose the month and the year from which Klar should see your orders. The default is 24 months back, so that you have a year-over-year comparison in Klar right away.
Enable Import the entire history instead if Klar really should see everything.
Read the estimate below the field. The wizard asks JTL how many orders fall within the chosen period, and states the expected duration. The estimate updates when you change the period or the speed.

Sync behaviour

Under Check JTL every, choose how often the program looks for new orders after the import. The options are 15 minutes, 30 minutes, 1, 2, 4, 8, 12 and 24 hours. The default is 1 hour.
Under Speed, choose how heavily the program may load the JTL API:

Speed	When
Conservative (5 requests/second) — Default	JTL-Wawi runs on a workstation or on a server that also runs other things
Balanced (15 requests/second)	A dedicated JTL server
Fast (30 requests/second)	A machine that does nothing else

Then click Finish and start sync.

The wizard encrypts the credentials and starts the service. The message Setup complete then appears. You can close the window.

Setup wizard, step 3 of 3, with Import orders from, the estimate, Check JTL every and Speed.

The final message Setup complete.

Caution: The chosen start month determines what history Klar sees. You can extend the period later with Re-import a date range… in the taskbar menu, but it is easier to choose it correctly right here. Do not choose less than 24 months if you need year-over-year comparisons.

7. The first import

The service starts immediately. The first cycle transfers the chosen history. This takes time, and the wizard has already given you an estimate for it.

These values come from a test system and apply to Conservative, that is 5 requests per second. They are guide values and may differ on your machine:

Operation	Measured time
First import of 5,000 orders	about 19 minutes
One cycle with 140 new orders	about 32 seconds
One cycle with no new orders	about 2.4 seconds
Memory used by the service	under 100 MB

A history of 200,000 orders takes several hours. The taskbar menu shows the progress meanwhile, for example Status: Importing order history: 1,200 of 203,400 (0%).

Leave the machine on until the first import is finished. If the machine goes off, the program resumes at the last position after the next start. No order is lost, and no order is counted twice.

8. The taskbar icon

The icon is the Klar mark, next to the clock. It has three states:

Icon	Meaning
Mark without a dot	The service is idle
Mark with a pulsing dot	A sync is running right now
Mark with an orange dot	A new version is available (see section 10)

The animation only starts when an operation takes longer than 2 seconds. A short cycle therefore shows no animation.

Hover over the icon to see the status as text.

Taskbar with the Klar icon and the tooltip Update 1.0.0-beta.8 available - JTL-to-Klar Sync: idle.

If the icon is missing, the taskbar app is not running. Start JTL-to-Klar Sync from the Start menu. Also check the area of hidden icons.

Click the icon once to open the menu.

The taskbar menu in its normal state.

The status lines

The top lines show the status. They are not clickable.

Line	Bedeutung
Status: Idle, up to date	What the service is doing right now. During an import, the progress is shown here.
Last Sync: 2026-08-11 12:46:38 · no changes	The time of the last cycle, and what it did: no changes, 1 order or, for example, 1,072 orders.
Synced to Klar: 465 orders since 01.01.2026	How many orders this installation manages in Klar, and from which date. For a full history, (full history) is shown there.
Errors: 0	The number of orders waiting for a retry. Anything other than 0 blocks new orders.
JTL: ✓ · Klar: ✓ · 1.072 orders in JTL	The state of the two connections, and how many orders JTL-Wawi has in total.

Good to know: Synced to Klar and orders in JTL are deliberately two separate numbers and not a fraction. The first number applies only to the period you chose during setup. The second is the total inventory in JTL-Wawi, including from years that should never have been synced. It is normal, and not an error, that the first number is smaller.

If the program needs your help, a line with a ⚠ appears below the status lines. It states in one sentence what to do.

The menu items

Item	Function
⚠ Update to … available	Appears only when a new version is available. Opens the update window (section 10).
Tenant: default	Selects the JTL-Wawi installation the menu applies to. Usually there is only one.
Sync Now	Starts a cycle within a few seconds. Use this after a change in JTL-Wawi.
Re-export: all synced	Resends all known orders to Klar, from the local copy
Re-export: full refresh from JTL	Reads all orders anew from JTL-Wawi and resends them to Klar
Re-import a date range…	Reads a period anew from JTL-Wawi. Use this to backfill history that lies outside the chosen start month.
View Logs	Opens the log file
Settings…	Opens the settings window
Version 1.0.0-beta.8	Shows the running version. State it when you contact support.
Quit	Quits the taskbar app. The service keeps running.

The taskbar menu with the update line at the very top.

Backfilling a period

Click Re-import a date range….
Enter the limits under From and To in the format TT.MM.JJJJ. The end date is included.
Enable Ignore the local cache and re-import everything in this range if the period should be read completely anew.
Click Start re-import.

The re-export variants

All re-export items ask for confirmation first.

Re-export: all synced — when data is missing in Klar that the program had already transferred.
Re-export: full refresh from JTL — when the data in Klar is wrong because the mapping has changed: a new program version, a changed GA transaction id or new product tags. Only this mode reads the data anew from JTL-Wawi.

Caution: Re-export: full refresh from JTL makes one request per order. On a large installation this takes several hours. The normal sync waits until the re-export is finished. You cannot abort it and cannot resume it after a restart.

When in doubt, ask at [email protected] before you start a re-export.

10. Updates

The program looks for new versions itself and reports them to you. It installs nothing without your consent.

When a new version is available, you see it in three places:

An orange dot appears on the taskbar icon.
The taskbar menu shows ⚠ Update to 1.0.0-beta.8 available at the top.
Once a day, a Windows notification appears.

Click the update line in the menu to open the update window.

The update window with What's changed and the Install now and Remind me tomorrow buttons.

The window states the new and the running version, how long the update has already been waiting, and what has changed. You have two options:

Button	Effect
Install now	Installs the new version. It takes about a minute.
Remind me tomorrow	Hides the window and the notification for 24 hours. The dot and the menu line stay.

What happens during the installation

The program checks the downloaded file: checksum and signature. A file that is not signed by Klar Insights GmbH is not installed.
Windows asks for administrator rights. Confirm with Yes.
The installer stops the service, replaces the program and starts the service again.
The update window and the taskbar icon close and come back by themselves.

Configuration, credentials and the entire sync state are preserved. No order is lost, and none is counted twice.

How often you are reminded

Waiting time	What happens
Day 0 to 2	Dot on the icon, line in the menu, one notification per day
From day 3	The menu line changes to ⚠ UPDATE OVERDUE. The window opens at sign-in and every 4 hours.
From day 7	The window opens every hour. The buttons are locked for the first 10 seconds.

Remind me tomorrow does not reset this clock. It runs from the moment the update was found. Install beta updates promptly — they contain the fixes we asked you for in the beta test.

11. The Start menu entries

Entry	Function	Admin rights required
JTL-to-Klar Sync	Starts the taskbar app	no
Settings	Opens the settings window	no
Restart Service	Stops the service and restarts it	no
Factory Reset	Deletes the configuration and the entire state	yes

Use Restart Service after you have manually changed config.yaml, or when the service does not respond.

⚠️ Warning: Factory Reset deletes the configuration, the Klar token and all sync positions. Use it only after consulting support. Back up config.yaml beforehand.

Factory Reset does the following:

It stops the service.
It deletes the files in C:\ProgramData\JtlKlarSync\.
It preserves the JTL-Wawi API key, because JTL cannot hand it out again.
It leaves the service stopped.

The next start of the program opens the setup wizard. It offers the preserved API key, provided it still works.

The orders in Klar are preserved. A new sync resends them and replaces them via the order ID. No duplicates arise.

12. The settings window

Open it via Settings… in the taskbar menu or via the Settings Start menu entry. The running version is shown at the bottom left.

JTL-Wawi connection

Field	Function
API URL	The address of the JTL API server
API key	Shows the Re-register with JTL button. The key itself is not visible.
Test connection	Makes a request to JTL-Wawi. On success, ✓ Reached Wawi. N orders visible. appears.

Klar connection

Field	Function
API URL	Must begin with `https://`
Access token	Leave empty to keep the stored token
Test connection	Makes a request to Klar. On success, ✓ Connected to Klar. appears.

The settings window: the two connections.

Sync behaviour

Field	Function
Poll every	The interval between two cycles. Dropdown list: 15 minutes to 24 hours, default 1 hour.
Re-check window	Number of days for change detection, default 90. Older orders are no longer updated in Klar.
Hash salt	Makes the customer email pseudonymous. Empty = the address is sent. See section 2.
GA transaction id	Which JTL field is sent as the Google Analytics transaction ID. See section 2.
Sync full order history on first run	Transfers the entire history on the first cycle
ID prefix	Only needed when several JTL-Wawi installations share one Klar token

The settings window: Sync behaviour with GA transaction id.

Click Save changes to write the configuration. ✓ Saved. The service picks the change up within a few seconds. appears. The service applies most changes without a restart. A change to the tenant list restarts the service automatically.

13. Multiple JTL-Wawi installations

One installation of the program can serve several JTL-Wawi installations. Each of them is a Tenant. Each tenant has its own credentials, its own state and its own status.

Add a tenant in the settings window with Add tenant…. Each tenant needs an ID. Use only letters, numbers, hyphen and underscore, for example shop-de. With Remove tenant… you remove a tenant again; the orders in Klar are not affected.

Caution: When two tenants write into the same Klar account, each tenant needs its own ID prefix. Without a prefix, the order IDs of the two tenants collide in Klar. The settings window refuses to save in that case.

Most beta installations have exactly one tenant. Then you do not need to do anything here.

14. Files and folders

Program folder: C:\Program Files\JtlKlarSync\

Data folder: C:\ProgramData\JtlKlarSync\

File	Content
`config.yaml`	The configuration. The credentials in it are encrypted.
`logs\jtl-klar-sync.log`	The service's log. At 10 MB the file rotates; up to 7 old files and at most 7 days are kept.
`tenants\<ID>\sync.db`	The local state: line items, comparison data, failed groups
`tenants\<ID>\status.json`	The status for the taskbar app
`updates\<Version>\`	The downloaded installation file of a new version

The taskbar app has its own log at %LOCALAPPDATA%\JtlKlarSync\logs\jtl-klar-sync.log. That is a different file, because the taskbar app runs without administrator rights.

After an update, the program folder additionally contains jtl-klar-sync.exe.previous, the previous version. Do not delete it — support needs it if a new version has a problem.

The configuration file

You can edit config.yaml with a text editor. For all values that the settings window shows, the settings window is the better way.

These are the most important default values:

sync:
  pollInterval: 1h                                  # interval between two cycles
  batchSize: 1000                                   # max. orders per request to Klar
  recheckWindowDays: 90                             # days checked for changes
  fullRecheckIntervalHours: 24                      # interval for the slow pass
  googleAnalyticsTransactionIdSource: orderNumber   # orderNumber | orderName | id

rateLimit:
  jtlRequestsPerSecond: 5.0                         # 5 = Conservative, 15 = Balanced, 30 = Fast
  klarRequestsPerSecond: 2.0

logging:
  level: "info"                                     # debug, info, warn or error
  maxSizeMB: 10
  maxBackups: 7
  maxAgeDays: 7

update:
  checkInterval: 24h
  channel: "beta"                                   # during the beta test

Good to know: Restart the service after a manual change to config.yaml. Use the Restart Service Start menu entry for this. Do not change update: without consulting us — otherwise you will no longer receive beta updates.

15. Beta test: what we are looking forward to

As a beta tester, we ask you for this feedback:

The number of orders in your JTL-Wawi and the chosen start month.
The duration of the first import and the chosen Speed level.
Any difference between JTL-Wawi and Klar that you notice — with the order number.
Whether the Google Analytics transaction IDs in Klar match your GA4 account.
The log files, when a warning appears in the taskbar menu.
Anything that does not go smoothly when updating from one version to the next.

Send everything to [email protected]. Please state the version from the taskbar menu.

Install new versions quickly. During the beta test they appear frequently, and each one contains fixes from the other testers' feedback.

16. When something does not work

First check the taskbar menu. The status lines and the ⚠ line state the cause.

All messages, their causes and the appropriate actions are in a separate article: JTL-Klar-Sync: Troubleshooting errors (Beta). It also explains how to send the log files to support.

Connect JTL-Wawi 1.x to Klar (Beta)