JTL Vouchers Portal-Fehlermeldung auf einem Bildschirm mit rotem Warnsymbol, daneben Wawi-Oberfläche

JTL Vouchers Fehler lösen — Portal nicht erreichbar, Sync bricht ab, falscher Gutscheinwert

JTL Vouchers läuft in vielen Setups unauffällig im Hintergrund, bis es plötzlich nicht mehr tut. Das Portal zeigt einen 502-Fehler, der Sync zwischen Wawi und dem Vouchers-Service schreibt jede Sekunde einen neuen Eintrag ins Log, oder Kunden lösen einen 50-Euro-Gutschein ein und der Wert landet nicht vollständig in der Bestellung. Wir sehen diese drei Fehlerbilder regelmäßig bei Händlern, die JTL Vouchers neu eingerichtet haben oder nach einem Update mit Problemen kämpfen.

Du willst wissen, woran es liegt — und wie du es schnell wieder zum Laufen bringst?

Dieser Beitrag geht die drei häufigsten Fehler bei JTL Vouchers durch, erklärt die Ursachen und zeigt dir einen klaren Diagnoseweg.

Auf einen Blick

  • ✓Aus mehreren Vouchers-Projekten, die wir betreut haben: Über 60 Prozent der Fehler liegen nicht am Vouchers-Service selbst, sondern an fehlerhafter Wawi-Konfiguration oder einem Lizenzproblem.
  • ✓Drei Fehlerbilder stehen im Vordergrund: Portal nicht erreichbar (meist Infrastruktur-seitig oder Lizenz abgelaufen), Sync-Schleife im Log (API-Token falsch oder Connector nicht aktuell), falscher Gutscheinwert (Wawi-Artikelkonfiguration mit falschem Attribut oder Steuerklasse).
  • ✓Die Vlarom E-Commerce Agentur ist JTL Service Partner Gold: wir beheben Vouchers-Probleme als Teil unserer JTL-Betreuungspakete.

JTL Vouchers ist ein cloudbasierter Dienst, der von einem externen Portal abhängt. Wenn das Portal einen 502 meldet, ist es oft kein Fehler in deiner Wawi-Installation, sondern ein serverseitiges Problem bei JTL. Trotzdem gibt es auf deiner Seite mehrere Stellen, an denen Konfigurationsfehler die gleichen Symptome erzeugen. Wir bei der Vlarom E-Commerce Agentur prüfen bei der Diagnose deshalb beide Seiten. Bevor du ein Support-Ticket öffnest, lohnt es sich, die lokalen Ursachen auszuschließen.

Die drei häufigsten JTL Vouchers Fehler und ihre Ursachen

Jedes der drei Fehlerbilder hat eine eigene Logik. Wer sie kennt, spart sich lange Debugging-Sessions.

1

Fehler 1: Portal nicht erreichbar (502 / 404)

Das JTL-Vouchers-Portal unter vouchers.api.jtl-software.com ist ein externer Dienst. Wenn du eine 502- oder 404-Meldung siehst, kann das an einem JTL-seitigen Ausfall liegen, wie im Januar 2026, als mehrere Händler ab 17:45 Uhr gleichzeitig die gleiche Fehlermeldung bekamen. Es kann aber genauso gut bedeuten, dass deine JTL-Lizenz nicht mehr aktiv ist oder der gebuchte Vouchers-Tarif ausgelaufen ist.

Prüfe zuerst im JTL-Kundencenter ob dein Vouchers-Abonnement aktiv ist. Prüfe danach ob andere Händler im JTL-Forum zeitgleich dasselbe melden. Nur wenn beides grün ist, liegt das Problem in deiner lokalen Konfiguration.

2

Fehler 2: Sync-Fehler — Log läuft voll

Wenn dein Wawi-Log oder dein Shop-Log jede Sekunde eine neue Fehlermeldung schreibt — typisch ist `cURL error 28: Failed to connect to vouchers.api.jtl-software.com port 443: Connection timed out` — liegt das fast immer an einem ungültigen API-Token oder an einem veralteten JTL-Vouchers-Plugin im Shop. Der Service versucht zu verbinden, scheitert, und wiederholt das im kurzen Takt.

Überprüfe im JTL-Vouchers-Portal ob der API-Token noch gültig ist. Generiere bei Bedarf einen neuen und trage ihn sowohl in der Wawi-Verbindungseinstellung als auch im Shop-Plugin nach. Ältere Plugin-Versionen sind mit neueren API-Endpunkten nicht immer kompatibel, also prüfe auch die installierte Version.

3

Fehler 3: Falscher Gutscheinwert bei Einlösung

Kunden kaufen einen Gutschein über 50 Euro, aber bei der Einlösung stimmt der Wert nicht — entweder wird ein falscher Betrag abgezogen, oder der Restbetrag nach Teileinlösung verschwindet einfach. Das passiert, wenn der Wawi-Artikel für den Gutschein falsch konfiguriert ist: falsches Attribut (jtl_vouchers oder jtl_vouchers_flex), falsche Steuerklasse, oder der Artikelwert wurde bei der Erstellung nicht korrekt mit dem Vouchers-Portal synchronisiert.

Prüfe im Wawi-Artikel die gesetzten Attribute. Der Artikel braucht entweder das Attribut `jtl_vouchers` für feste Gutscheine oder `jtl_vouchers_flex` für flexible Beträge. Fehlt eines, behandelt das System den Artikel nicht als Vouchers-Gutschein und übergibt keinen Wert ans Portal. Ein häufiges Problem bei Erst-Einrichtungen: Wird der Artikel angelegt bevor die Vouchers-Verbindung aktiv ist, fehlt die Seriennummern-Zuweisung durch das Portal.

4

Sonderfall: Consent-Plugin blockiert Checkout

Ein weniger offensichtliches Fehlerbild: Gutscheine lassen sich in den Warenkorb legen, aber beim Checkout passiert nichts mehr. Zahlungsarten erscheinen, aber der Kauf bricht ab. Ein Händler im JTL-Forum berichtete, dass sein EU-Cookie-Consent-Plugin die Anfragen ans Vouchers-API blockiert hat. Nach dem Wechsel auf das native JTL-Consent-Tool lief alles wieder.

Wenn du Vouchers-Probleme ausschließlich im Checkout-Prozess siehst, prüfe deine Consent-Konfiguration. Drittanbieter-Consent-Tools können API-Calls zu externen Diensten unterbinden, auch wenn das nicht explizit so konfiguriert ist.

Schritt für Schritt: JTL Vouchers Fehler diagnostizieren

Geh diese Punkte der Reihe nach durch. Die meisten Probleme lösen sich in Schritt 1 bis 3.

Schritt 1: Lizenz und Portal-Status prüfen

Melde dich im JTL-Kundencenter an und prüfe, ob dein JTL-Vouchers-Abonnement aktiv ist und welches Paket gebucht ist. Öffne parallel das JTL-Forum unter forum.jtl-software.de und such nach aktuellen Meldungen zu Vouchers-Ausfällen. Wenn andere Händler zeitgleich dasselbe melden, ist es ein serverseitiger Ausfall. Dann hilft nur warten oder ein Support-Ticket bei JTL.

Schritt 2: API-Token erneuern und Verbindung neu herstellen

Öffne das JTL-Vouchers-Portal und gehe in die Verbindungseinstellungen. Generiere einen neuen API-Token und trage ihn in JTL-Wawi unter den Vouchers-Verbindungseinstellungen ein. Mach dasselbe im JTL-Shop-Plugin für JTL-Vouchers. Prüfe danach ob die Verbindungstests erfolgreich sind. Laut JTL-Guide zur Wawi-Verbindung ist dieser Schritt auch nach größeren Wawi-Updates manchmal notwendig.

Schritt 3: Wawi-Artikel-Attribute kontrollieren

Öffne den Wawi-Artikel, der als Gutschein verkauft werden soll. Prüfe unter den Attributen ob `jtl_vouchers` (für feste Beträge) oder `jtl_vouchers_flex` (für flexible Beträge) gesetzt ist. Fehlt das Attribut, wird der Artikel vom Vouchers-System nicht erkannt. Prüfe außerdem die Steuerklasse: Gutscheine sind in Deutschland steuerneutral beim Kauf, der Steuersatz wird erst bei Einlösung fällig.

Schritt 4: Plugin-Version im Shop aktualisieren

Veraltete JTL-Vouchers-Plugins im JTL-Shop sind eine häufige Fehlerquelle bei Sync-Problemen. Prüfe im Shop-Backend unter Plugins die installierte Version und vergleiche sie mit der aktuellen Version im JTL-Store. Aktualisiere das Plugin und prüfe danach ob der Sync-Log ruhig bleibt.

Schritt 5: Consent-Konfiguration und Checkout-Flow testen

Wenn Schritte 1 bis 4 keine Lösung bringen und das Problem beim Checkout auftritt, teste mit deaktiviertem Consent-Plugin. Öffne die Browser-Entwickler-Tools (F12) und prüfe im Netzwerk-Tab ob API-Calls zu vouchers.api.jtl-software.com blockiert werden. Bei Drittanbieter-Consent-Tools musst du die Vouchers-API-Domain als erlaubt eintragen oder auf das native JTL-Consent-Tool wechseln.

Häufige Fragen zu JTL Vouchers Fehlern

Was bedeutet der Fehler 'cURL error 28: Failed to connect to vouchers.api.jtl-software.com port 443'?

Diese Fehlermeldung bedeutet, dass dein System keine Verbindung zum JTL-Vouchers-API-Server herstellen kann. Das passiert bei einem API-Timeout, wenn der Server nicht antwortet. Mögliche Ursachen: JTL-seitiger Ausfall, abgelaufener API-Token, oder eine Firewall auf deiner Seite die ausgehende Verbindungen auf Port 443 zu externen Servern blockiert. Prüfe zuerst den JTL-Forum-Status, dann deinen Token, dann deine Firewall-Regeln.

Ein 502 Bad Gateway bedeutet, dass der JTL-Vouchers-Server selbst nicht antwortet. Das ist fast immer ein serverseitiger Ausfall bei JTL, kein Fehler auf deiner Seite. Ein Händler im JTL-Forum: ‚Das Portal war um 17:45 Uhr nicht mehr erreichbar, andere hatten exakt dasselbe.‘ Prüfe das JTL-Forum auf aktuelle Meldungen. Wenn der Ausfall bestätigt ist, bleibt dir nur warten. Nach einem Ausfall musst du die Verbindung in Wawi und im Shop-Plugin meist manuell neu herstellen.

Falsche Gutscheinwerte entstehen fast immer durch eine fehlerhafte Artikel-Konfiguration in JTL-Wawi. Der häufigste Grund: das Attribut `jtl_vouchers` oder `jtl_vouchers_flex` fehlt am Artikel. Ohne dieses Attribut übergibt Wawi keinen gültigen Vouchers-Wert ans Portal und die Einlösung läuft über einen nicht-verknüpften Pfad. Prüfe den Artikel und setze das richtige Attribut, dann teste mit einem neuen Testgutschein.

Das ist ein bekanntes Problem, wenn beim Artikel die Option ‚Wert gleich Verkaufspreis‘ aktiviert ist. Diese Einstellung setzt den Vouchers-Wert auf null, wenn der Sync aktiv ist. Deaktiviere diese Option und gib den Gutscheinwert manuell ein. Alternativ nutze ausschließlich das `jtl_vouchers_flex`-Attribut, das für flexible Beträge vorgesehen ist und den Wert vom Käufer bestimmen lässt.

Ja. Wenn dein Log sekündlich Vouchers-Fehlermeldungen schreibt, auch wenn Kunden noch Gutscheine kaufen können, läuft dein System nicht stabil. Die Log-Einträge können Festplatte und Performance belasten, und der nächste Ausfall des Vouchers-Portals trifft dich ohne Vorwarnung hart. Bereinige die Ursache so schnell wie möglich. Meistens ist es ein veralteter API-Token oder ein ausstehendes Plugin-Update.

Öffne ein Support-Ticket wenn: Das Portal über mehrere Stunden nicht erreichbar ist und keine Forum-Meldung existiert. Der Fehler nach Token-Erneuerung und Plugin-Update weiterhin auftritt. Falsche Werte zu echten Buchungsfehlern in deiner Buchhaltung geführt haben. Mehrere Kunden gleichzeitig Probleme melden. Als JTL Service Partner Gold hat die Vlarom E-Commerce Agentur kurze Reaktionszeiten im JTL-Partnersupport. Bei eskalierenden Vouchers-Problemen ist das ein echter Vorteil.

Ja, JTL Vouchers unterstützt auch das Kassensystem JTL-POS. Die Einlösung am POS ist aber ein häufiger Fehlerort, besonders wenn zwei Gutscheine gleichzeitig eingelöst werden oder ein Restbetrag entsteht. Ein bekanntes Problem: bei Teileinlösung mit zwei Gutscheinen verschwindet manchmal der Restbetrag statt auf dem zweiten Gutschein zu verbleiben. Wenn du dieses Fehlerbild hast, öffne ein Support-Ticket bei JTL mit dem genauen Kassenbon und den Gutscheincodes.

JTL Service Partner Gold

Vlarom löst dein Vouchers-Problem

Die Vlarom E-Commerce Agentur richtet JTL Vouchers ein, behebt Sync-Fehler und prüft die Wawi-Konfiguration. Als JTL Service Partner Gold haben wir direkten Zugang zum JTL-Partnersupport. Das spart Zeit, wenn ein Fehler auf JTL-Infrastruktur-Seite liegt. Ruf uns an unter +49 30 91473862, schreibe an info@vlarom.de oder nutze unser Kontaktformular.