Aufruf des Dienstes
Den Dienst erreichen Sie über folgende URL:Gutschein und Gutschein-Charge
Ein Gutschein ist der Code, den ein Kunde im Shop eilösen kann. Eine Gutschein-Charge regelt alles um den Gutschein herum, beispielsweise Wert, Währung, Gültigkeitszeitraum und Einlösebedingungen. Jeder Gutschein gehört zu genau einer Charge und erbt deren Einstellungen.Beim Anlegen eines Gutscheines entsteht daher immer eine Charge und, je nach Vorgangsweise, die Gutscheine darin.
Die Charge wird über ihre ID angesprochen. Diese ID ist die einzige Angabe, mit der anderen Stellen im System auf eine Charge verweisen, beispielsweise ein Kaufgutschein-Produkt.
Die Bereiche der Gutscheinverwaltung
Der Dienst gliedert sich in drei Reiter mit folgenden Inhalten:Screenshot Stand 01.09.2026
In der Liste der Chargen ist die Spalte “Anzahl” das schnellste Erkennungsmerkmal. Steht dort eine Zahl größer als null, enthält die Charge fertige Gutscheincodes. Steht dort
0, gehört die Charge zu einer Kaufgutscheinvorlage, deren Codes erst mit einer Bestellung entstehen.Gutscheinarten
Beim Anlegen wird unter “Art des Gutscheins” zwischen zwei Arten unterschieden. Die getroffene Auswahl entscheidet darüber, auf welche Positionen der Gutschein wirkt.Eine Gutschein-Charge anlegen
Über ”+ Neuer Gutschein” öffnet sich eine Maske mit mehreren Abschnitten. Sie wird von oben nach unten ausgefüllt, die Abschnitte sind zugleich als Reiter erreichbar.Vorlage
Zunächst wird eine Gutscheinvorlage ausgewählt oder die Option “Ohne Vorlage” gewählt. Erst nach dieser Auswahl werden die weiteren Abschnitte angezeigt. Eine gewählte Vorlage belegt die entsprechenden Felder und sperrt die übrigen.Allgemeine Einstellungen
Screenshot Stand 01.09.2026
Gutscheinwert
Die Verrechnungsart legt fest, ob der Gutschein einen absoluten Betrag abzieht, einen prozentualen Rabatt gewährt oder einen prozentualen Rabatt bis zu einem Höchstbetrag gewährt. Darunter steht für jede Währung eine Zeile mit Währung, Mehrwertsteuer-ID, Gutscheinwert und Mindestbestellwert. Über “Weitere Währung hinzufügen” können weitere Zeilen hinzugefügt werden. Ein Gutschein wirkt nur in Währungen, für die eine Zeile existiert. In diesem Abschnitt befinden sich noch zwei weitere Einstellungen:- Restbetrag: Bei “Restbetrag wiederverwendbar” bleibt ein nicht ausgeschöpfter Betrag erhalten und kann später erneut eingelöst werden. Bei “Restbetrag verfällt” ist der Gutschein nach der ersten Einlösung verbraucht.
- kostenloser Versand: Setzt bei Einlösung die Versandkosten auf null.
Weitere Abschnitte
Speichern
Der Button “Gutschein generieren” ist ein geteilter Button. Der Pfeil daneben öffnet drei weitere Optionen. Die Auswahl entscheidet darüber, was tatsächlich generiert wird:Screenshot Stand 01.09.2026
Kaufgutscheinvorlage anlegen
Eine Kaufgutscheinvorlage ist die Grundlage für Gutscheine, die im Shop verkauft werden. Sie enthält selbst keine Codes. Diese entstehen erst, wenn ein Kunde ein Kaufgutschein-Produkt bestellt, und zwar einer je bestellter Einheit. Die Vorlage wird in derselben Maske angelegt wie eine gewöhnliche Charge:1
Bezeichnung und Chargen-ID vergeben
Die Bezeichnung wird zur Kaufgutscheinvorlagen-ID. Die Chargen-ID sollte manuell und sprechend vergeben werden, beispielsweise
geschenkgutschein, denn genau dieser Wert wird später am Produkt eingetragen. Bleibt das Feld leer, muss die erzeugte Nummer hinterher in der Liste gesucht werden.2
Art des Gutscheins auf Kaufgutschein stellen
Verkaufte Gutscheine sind ein Zahlungsmittel und sollen unabhängig davon wirken, ob einzelne Produkte für Wertgutscheine freigegeben sind.
3
Gutscheinwert absolut, aber ohne Betrag
Die Verrechnungsart ist auf “absolut” eingestellt, der Gutscheinwert bleibt bei
0. Den tatsächlichen Wert setzt der Preis des verkauften Produkts. Die Charge sollte nur eine Währung führen. Beim Restbetrag ist “Restbetrag wiederverwendbar” die richtige Wahl, sonst verfällt bei einer Teileinlösung der Rest des gekauften Guthabens.4
Über das Pfeilmenü speichern
Im Menü neben “Gutschein generieren” den Eintrag “Gutschein als Kaufgutscheinvorlage speichern” wählen. Der Hauptknopf würde stattdessen fertige Gutscheincodes anlegen, die ein Kaufgutschein-Produkt nicht verwenden kann.
0.
Screenshot Stand 01.09.2026
Gutscheinvorlagen
Mit einer Gutscheinvorlage werden die Eingaben der Maske gespeichert, sodass wiederkehrende Aktionen nicht jedes Mal neu ausgefüllt werden müssen. Sie wird über den Eintrag “Gutschein generieren und als Vorlage speichern” angelegt und steht anschließend im Abschnitt “Vorlage” oben zur Auswahl. Vorlagen wirken nur beim Anlegen. Eine geänderte oder gelöschte Vorlage hat keinen Einfluss auf bereits erzeugte Chargen und Gutscheine.Anzeige im Shop
Wie Gutscheine im Shop erscheinen, bestimmt das Template. Im Admin-Interface gibt es dafür keine Einstellungen.- Das Eingabefeld für den Gutscheincode, die Liste der eingelösten Gutscheine und die Fehlertexte werden im Template ausgegeben. Beispiele dazu stehen in den Praxisbeispielen Gutscheine.
- Welche Daten dabei zur Verfügung stehen, beschreibt das Modul $wsVoucher.
- Verkaufte Gutscheine erscheinen nicht über dieses Modul, sondern am Warenkorbartikel, siehe Kaufgutschein-Produkt anlegen.
Begriffe und technische Namen
Wegweiser
- Kaufgutschein-Produkt anlegen beschreibt den zweiten Teil des Ablaufs.
- API-Referenz Gutscheine beschreibt dieselben Objekte über die Schnittstelle.
- Praxisbeispiele Gutscheine zeigt das Einlösen im Shop-Template.
- checkout - Bestellablauf beschreibt die Einstellungen zum Einlösen im Bestellablauf.