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

Version 1.0.0
The program is signed by Klar Insights GmbH and keeps itself up to date: it checks daily for new versions and offers them in the taskbar menu.
Download: jtl-klar-sync-setup.exe
Questions and problems: [email protected]

Still on a beta version? Then there is one thing to do, once. Section 15. Upgrading from a beta version explains it.

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 takes 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 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 permanent error stops all new orders. Check the taskbar menu when the Errors line is no longer 0.

How changes are detected

JTL-Wawi cannot tell the program which orders changed. So in each cycle the program compares the orders of the last 90 days against the last known state.

One kind of change is only detected with a delay: a change to a line item that does not change the order total — a corrected SKU, for example. The program finds these with a slow sweep that re-checks every order once within 24 hours. The maximum delay is therefore 24 hours.

How deletions are detected

If an order is no longer in JTL-Wawi's answer, the program asks JTL-Wawi about that one order again. If JTL-Wawi answers that the order does not exist, it counts as deleted. The program then reports it to Klar as cancelled, using the last known state of the order.

2. What data goes to Klar

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

Per order the program sends:

Order ID, order number and the order's dates
Payment status and shipment status
Currency, totals, taxes and discounts
The name of the payment method and of the payment gateway
Sales channel and platform of the order (see below)
The line items: SKU, product name, quantity, amounts, taxes and discounts
Product tags: the article's category paths, its Warengruppe and allow-listed custom fields
Customer tags: Kundengruppe and Kundenkategorie
Shipping costs and shipping taxes
Refunds from returns and from credit notes (see below)
The customer number from JTL-Wawi
The customer's e-mail address, or a hash of it (see below)
From the delivery 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 address.

Refunds: returns and credit notes

Klar receives refunds from two sources in JTL-Wawi:

from Retouren (returns), including the return reason your team recorded
from Gutschriften and Rechnungskorrekturen (credit notes and invoice corrections)

The second source matters for everything refunded without a return: goodwill, price corrections, partial refunds. Those amounts used to be missing from Klar.

If a return and a credit note describe the same refund, the credit note wins and the return's reason is carried over. Nothing is counted twice.

Not transferred:

Cancellations (Stornos) — the order itself is already reported as cancelled.
Refunded shipping costs and coupon lines — Klar records refunds per article. Refunded articles and quantities are therefore correct; refunded shipping is not represented in Klar.

Note: For orders already transferred before version 1.0.0, the program does not backfill credit notes by itself. That needs a one-off Re-export: full refresh from JTL (section 9).

Sales channel and platform

Every order gets a sales channel and a platform in Klar, so you can see which shop or marketplace it was sold through.

Where the order came from	Sales channel	Platform
JTL-Shop	The shop's name from JTL-Wawi	Online-Shop
eBay	The name of the eBay account	eBay
Amazon	The name of the Amazon account	Amazon
SCX marketplace (OTTO, Kaufland and others)	The marketplace name	SCX - <marketplace>
Entered directly in JTL-Wawi	JTL-Wawi	JTL-Wawi
REST API, XML import, Fulfillment, POS	accordingly	REST-API, XML-Import, JTL-Fulfillment-Network, JTL-POS

Good to know: For some shops JTL-Wawi reports no name over the API — mainly B2B shops and deleted shops. In Klar those are called, for example, Online-Shop 2. That is not an error. If you create a new shop, the program picks it up without a restart.

Renaming a shop in JTL-Wawi does not by itself trigger a re-transfer. For orders from before version 1.0.0 you need a one-off Re-export: full refresh from JTL so that channel and platform appear in Klar.

The e-mail address

By default the program sends the customer's e-mail address to Klar.

You can set a Hash salt in the settings window. The program then sends a SHA1 hash of the address instead of the address itself, and the address never leaves the machine.

Caution: The salt must be the same salt Klar uses. Agree it with us. If you change the salt later, Klar sees every customer as new.

The Google Analytics transaction ID

Klar uses this ID to match an order to the matching transaction in GA4. For that, the program has to send the same field your shop sends to GA4.

You choose the field in the settings window under GA transaction id:

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 a marketplace. If it is missing, the program sends the JTL order number.
id	The internal, numeric order ID from JTL-Wawi
number	Always the JTL order number, with no fallback

The default fits most shops. If in doubt, check in GA4 which value appears as the transaction ID and pick the same field here.

Note: A change only affects new and changed orders. To backfill orders already transferred, use Re-export: full refresh from JTL (section 9).

Where the credentials live

The program stores the JTL-Wawi API key and the Klar token in 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 licence, booked in the JTL Customer Center
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)
Rights	Administrator rights, for installation and updates only
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 separate database and no separate web server.

Windows Server or Remote Desktop? The setup wizard and the settings window need a graphics driver with OpenGL 2.1. Servers without a graphics card and some Remote Desktop sessions do not have one. The installer has the Software OpenGL option for that — see section 5. The service itself and the taskbar icon need no OpenGL.

4. Before you start

Have these five things ready before installing:

The installer: jtl-klar-sync-setup.exe
Administrator rights on the JTL-Wawi machine.
The JTL-Wawi API licence. Book it in the JTL Customer Center.
A JTL-Wawi user who may accept an app registration.
The Klar access token (see below).

Good to know: The JTL-Wawi API is free while JTL's API is in beta. JTL charges for it afterwards.

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

Creating the Klar access token

The token authorises 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 starting with eyJ. Full description: API Authentication.

Caution: Create a dedicated data source for JTL-Wawi. Do not reuse 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 is Klar Insights GmbH.
On the components page, leave the default and click Next. Tick Software OpenGL only if this machine has no graphics driver — that is, on Windows Server or when you work over Remote Desktop. On a normal PC the option replaces a working driver and the windows may not open at all.
Confirm the suggested target folder and click Install.
Wait until the installation finishes.
Click Close.

Installer: choosing the target folder, with the Install button.

Good to know: With a brand-new version, Windows may show a one-off SmartScreen notice despite a valid signature, because the file has not been downloaded often yet. Check that the publisher reads Klar Insights GmbH and continue. Do not switch 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.
It creates four Start Menu entries (see section 11).
It adds a startup entry so the taskbar app starts at every logon.
It starts the taskbar app.

On a first installation the installer does not start the service yet. The setup wizard does that, and opens automatically afterwards.

6. The setup wizard

The wizard has three steps. Do not close the window before step 3 is finished. The wizard 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 it an API key in return.

Important: Open the app registration in JTL-Wawi first. JTL-Wawi has to be waiting for the request before you send it from the wizard, otherwise the API refuses it.

Open JTL-Wawi.
Sign in to the same database the API serves. The database name is 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 is http://127.0.0.1:5883/api/eazybusiness/.
Change the port if the JTL API server uses a different one.
Click Register with JTL-Wawi.

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

Now switch to JTL-Wawi and finish the registration there:

Accept the request Klar Sync.
Assign the JTL-Wawi user the program should act as.
Grant the requested permission. The program needs read access only (all.read).
Click Fertigstellen.

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

JTL-Wawi: assigning the user and granting the permission, with the Fertigstellen button.

Switch back to the wizard. It shows ✓ Registered: API key received. Click Continue. Click Continue ▸.

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

The wizard asks JTL-Wawi for the result every 3 seconds and gives up after 10 minutes. Start the process again if that happens.

Caution: JTL-Wawi issues the API key only once, per App ID, and cannot re-issue the same key. Keep a copy somewhere safe.

If you already have an API key — after a reinstall, for example: click I already have an API key, enter the key and click Continue ▸. After a factory reset the wizard offers the old key itself if it still works; then Use the preserved API key appears.

Step 2 of 3: Connect to Klar

Leave the pre-filled API URL unchanged unless Klar told you otherwise.
Paste the Klar token into the Access token field.
Click Continue ▸.

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

Good to know: The wizard does not verify the token at this step. You can test the connection any time after setup with Test connection in the settings window. On success it shows ✓ Connected to Klar.

Step 3 of 3: Sync settings

Here you decide how far back the history should reach and how fast the program may work.

Order history

Under Import orders from, pick the month and year from which Klar should see your orders. The default is 24 months back, so you have a year-over-year comparison in Klar straight away.
Tick 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 in the chosen period and states the expected duration. It updates when you change the period or the speed.

Sync behaviour

Under Check JTL every, choose how often to look 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 hard the program may work the JTL API.

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

Then click Finish and start sync.

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

The wizard encrypts the credentials and starts the service. Then Setup complete appears and you can close the window.

The Setup complete message.

Caution: The start month you choose decides what history Klar sees. You can widen it later with Re-import a date range… in the taskbar menu, but it is easier to get it right here. Do not go below 24 months if you need year-over-year comparisons.

7. The first import

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

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:

Task	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 done. If it shuts down, the program continues from its last position after the next start. No order is lost and none 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 ready (see section 10)

The animation only starts if a task takes longer than 2 seconds, so a short cycle shows none. Hover over the icon to see the status as text.

The taskbar with the Klar icon and the tooltip for an available update.

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

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	Meaning
Status: Idle, up to date	What the service is doing. During an import the progress appears here.
Last Sync: 2026-08-11 12:46:38 · no changes	When the last cycle ran 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. With a full history it reads (full history).
Errors: 0	Orders the program is still retrying. Anything other than 0 blocks new orders.
Validation errors: 0	Orders Klar rejected and the program gave up on. They block nothing but are missing from Klar.
JTL: ✓ · Klar: ✓ · 1.072 orders in JTL	The state of both connections, and how many orders JTL-Wawi holds in total.

Good to know: Synced to Klar and orders in JTL are deliberately two separate numbers, not a fraction. The first covers only the period you chose at setup. The second is the total in JTL-Wawi, including years that were never meant to be synced. It is normal for the first number to be smaller.

If the program needs your help, a line with a ⚠ appears below the status lines. It names the action in one sentence.

The menu items

Item	Function
⚠ Update to … available	Only appears when a new version is ready. Opens the update window (section 10).
Tenant: default	Selects the JTL-Wawi installation the menu applies to. Normally there is only one.
Sync Now	Starts a cycle within a few seconds. Use it 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 from JTL-Wawi again and resends them to Klar
Re-export orders with validation errors	Reads only the orders Klar rejected from JTL-Wawi again and sends each once. Greyed out while Validation errors is 0.
Re-import a date range…	Reads a period from JTL-Wawi again. Use it to backfill history outside the chosen start month.
View Logs	Opens the log file
Settings…	Opens the settings window
Version 1.0.0	Shows the running version. Quote it when you contact support.
Quit	Closes the taskbar app. The service keeps running.

The taskbar menu with the update line at the top.

Backfilling a date range

Click Re-import a date range….
Enter the bounds in From and To in DD.MM.YYYY format. The end date is included.
Tick Ignore the local cache and re-import everything in this range if the period should be read completely afresh.
Click Start re-import.

The re-export options

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 orders with validation errors — after you have fixed the cause of a rejection in JTL-Wawi.
Re-export: full refresh from JTL — when data in Klar has to be brought up to date because the mapping changed: a new program version, a changed GA transaction id, credit notes or sales channel names. Only this mode reads the data from JTL-Wawi again.

Caution: Re-export: full refresh from JTL makes one request per order. On a large installation that takes several hours. Normal syncing waits until it is finished. You cannot stop it and cannot resume it after a restart. From about 20,000 orders upwards, work through it quarter by quarter with Re-import a date range… instead.

10. Updates

The program checks daily for new versions and tells you about them. It installs nothing without your consent, and you do not have to configure anything.

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

An orange dot appears on the taskbar icon.
The taskbar menu shows ⚠ Update to … 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 names the new and the running version, how long the update has been waiting, and what 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 install

The program checks the downloaded file: checksum and signature. A file 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 on their own.

Configuration, credentials and the entire sync state survive. 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 logon and every 4 hours.
From day 7	The window opens every hour. The buttons are disabled for the first 10 seconds.

Remind me tomorrow does not reset this clock. It runs from the moment the update was found.

11. The Start Menu entries

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

Use Restart Service after editing config.yaml by hand, or when the service does not respond.

⚠️ Warning: Factory Reset deletes the configuration, the Klar token and all sync positions. Use it only after talking to support, and back up config.yaml first.

The factory reset preserves the JTL-Wawi API key, because JTL cannot re-issue it. The next start opens the setup wizard, which offers the key again if it still works. The orders in Klar stay; a new sync replaces them by order ID, with no duplicates.

12. The settings window

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

JTL-Wawi connection and Klar connection

Field	Function
API URL (JTL)	The address of the JTL API server
API key	Shows the Re-register with JTL button. The key itself is not visible.
API URL (Klar)	Must start with `https://`
Access token	Leave blank to keep the stored token
Test connection	Tests the respective connection. On success it shows ✓ Reached Wawi. N orders visible. or ✓ Connected to Klar.

Settings window: the two connections.

Sync behaviour

Field	Function
Poll every	The interval between two cycles. A list from 15 minutes to 24 hours, default 1 hour.
Re-check window	How many days back to look for changes, default 90. Older orders stop updating in Klar.
Hash salt	Pseudonymises the customer e-mail. Blank = the address is sent. See section 2.
GA transaction id	Which JTL field is sent as the Google Analytics transaction ID. See section 2.
Earliest order date	Orders dated before this day are never sent to Klar, by any sync or re-export. Blank = no limit. Choose… opens a calendar.
Sync full order history on first run	Transfers the complete history on the first cycle
ID prefix	Only needed when several JTL-Wawi installations share one Klar token

Settings window: Sync behaviour.

Good to know: Earliest order date removes nothing that is already in Klar. It only stops older orders from being sent in future — useful when your books are only clean from a certain date onwards.

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

13. Several JTL-Wawi installations

One installation of the program can serve several JTL-Wawi installations. Each one is a tenant, with 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 made of letters, digits, hyphen and underscore, for example shop-de. Remove tenant… removes one again; the orders in Klar are not affected.

Caution: If two tenants write into the same Klar account, each needs its own ID prefix. Without one, the order IDs collide in Klar. The settings window refuses to save that configuration.

Most installations have exactly one tenant. Then there is nothing to do 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 log. The file rotates at 10 MB; up to 7 old files are kept, for at most 7 days.
`tenants\<ID>\sync.db`	The local state: positions, comparison data, failed groups
`tenants\<ID>\status.json`	The status for the taskbar app
`updates\<version>\`	The downloaded installer of a new version

The taskbar app has its own log at %LOCALAPPDATA%\JtlKlarSync\logs\jtl-klar-sync.log, because it runs without administrator rights. After an update the program folder also holds 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 in a text editor. For everything the settings window shows, the settings window is the better route. Two settings exist only here:

Key	Meaning
`sync.productTagCustomFields`	List of JTL-Wawi custom fields whose values go to Klar as product tags. Names as in JTL-Wawi, case-insensitive. Empty = none.
`sync.importCreditNotes`	Transfer credit notes as refunds. If the key is absent it is on. `false` switches it off.

The most important defaults:

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 sweep
  googleAnalyticsTransactionIdSource: orderNumber   # orderNumber | id | orderName
  productTagCustomFields: []                        # custom fields as product tags

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:
  checkUrl: "https://update.getklar.com/jtl/"
  checkInterval: 24h
  channel: "stable"

Good to know: Restart the service after editing config.yaml by hand — Start Menu entry Restart Service. Leave the update: section unchanged, or you will stop receiving updates.

15. Upgrading from a beta version

Installations from the beta phase do not check for updates themselves. They need your help once. After that the program keeps itself up to date.

First check the taskbar menu for the running version. If it reads 1.0.0 or newer, there is nothing to do.

Download the current installer: jtl-klar-sync-setup.exe
Run it on the JTL-Wawi machine, over the existing installation.
Confirm the User Account Control prompt and click through the installer.

The installer stops the service, replaces the program and starts the service again. Configuration, Klar token, JTL registration and the entire sync state survive. You do not have to register again, and nothing is re-imported.

One backfill afterwards: Version 1.0.0 transfers things that did not exist before — credit notes as refunds, and sales channel and platform. For orders already in Klar the program does not backfill these by itself.

Start Re-export: full refresh from JTL from the taskbar menu. With more than about 20,000 orders, use Re-import a date range… instead and work through it quarter by quarter, with Ignore the local cache ticked.

Schedule the re-export for a quiet time on that machine. While it runs, normal syncing is paused.

16. When something does not work

Check the taskbar menu first. The status lines and the ⚠ line name the cause.

Every message, its cause and the matching action are in a separate article: JTL-Klar-Sync: Fehler beheben. It also explains how to send the log files to support.

We answer questions at [email protected]. Please quote the version from the taskbar menu.

Connect JTL-Wawi 1.x to Klar