Die Gutscheinfelder am Produkt
Ein Kaufgutschein-Produkt wird über folgende Felder gesteuert. Diese befinden sich in der Produktmaske im Abschnitt “Allgemeine Felder”:Das Kaufgutschein-Produkt anlegen
Angelegt wird das Produkt im Admin-Interface unter Katalog → Produkte über ”+ Neues Produkt”. Zuerst die üblichen Angaben im Abschnitt Allgemeine Felder:
Weiter unten im selben Abschnitt stehen die Gutscheinfelder:

Screenshot Stand 02.09.2026
Den Wert des Gutscheins festlegen
Der Wert eines gekauften Gutscheins kann aus zwei Quellen kommen. Welche gilt, entscheidet der Schalter “Produktpreis entspricht Gutschein-Wert” am Produkt.Dem Kunden mehrere Wertstufen anbieten
Für einen frei eingetippten Betrag gibt es keine Funktion. Der Kunde wählt immer aus fest angelegten Wertstufen, und dafür gibt es zwei Wege:
Beide Wege kommen mit einer einzelnen Kaufgutscheinvorlage aus, solange “Produktpreis entspricht Gutschein-Wert” eingeschaltet ist.
Zahlungsarten und Versandarten
Weil ein gekaufter Gutschein sofort einlösbar ist, greifen im Bestellablauf Einschränkungen, die gesetzt werden müssen.Zahlungsarten
Ein Gutschein ist sofort einlösbar, das Geld dafür ist bei einer Zahlungsart mit Zahlungsziel aber noch nicht eingegangen. Um dieses Risiko auszuschließen, gibt es den PrüfservicepaymentValidation.voucherDeny. Er sperrt eine Zahlungsart, sobald ein Gutscheinprodukt im Warenkorb liegt.
Eingetragen wird er nicht zentral, sondern je Zahlungsart in deren Liste validations unter payment.payment. Sinnvoll ist der Eintrag bei allen Zahlungsarten mit Zahlungsziel, typischerweise Rechnung, Vorkasse, Nachnahme und Lastschrift.
Ohne diesen Eintrag bleiben alle Zahlungsarten wählbar, auch mit einem Gutschein im Warenkorb. Die Prüfservices selbst tragen keine Werte, sie werden nur referenziert. Wer die Sperre auf der Seite der Prüfservices sucht, findet dort nichts.Greift der Service, wirkt er auf die gesamte Bestellung und nicht nur auf die Gutscheinposition. Liegt ein Gutscheinprodukt neben regulären Artikeln im Warenkorb, ist die Zahlungsart für den ganzen Warenkorb gesperrt.
Versandart und Produkttyp
Ein Warenkorb, der nur Gutscheine enthält, braucht keinen physischen Versand. Dafür wird eine eigene, immer kostenfreie Versandart angelegt und über den PrüfserviceshippingMethodValidation.productType auf Gutscheinprodukte beschränkt. Auch dieser Eintrag steht je Versandart in deren Liste validations unter checkout.shippingMethod. Das vollständige Beispiel mit Preisstaffel und Regelliste steht in den Praxisbeispielen Gutscheine.
Was beim Bestellabschluss passiert
Die Gutscheine entstehen nicht beim Legen in den Warenkorb, sondern beim Abschluss der Bestellung:- Der Shop liest die Chargen-ID aus dem Produktfeld und sucht die Kaufgutscheinvorlage mit dieser ID.
- Er erzeugt je bestellter Einheit einen Gutschein mit den Daten der Vorlage.
- Ist “Produktpreis entspricht Gutschein-Wert” aktiv, übernimmt er den Positionspreis als Gutscheinwert, andernfalls gilt der Wert aus der Vorlage, siehe Den Wert des Gutscheins festlegen.
- Existiert zu der ID keine Vorlage, behandelt er die Charge als Pool importierter Codes und reserviert daraus. Ist auch das nicht möglich, bricht der Bestellabschluss ab.
data.orderList.item[].voucher, siehe API-Referenz Bestellungen. Solange eine Bestellung nicht abgeschlossen ist, bleiben beide Listen leer.
Anzeige im Shop
Wie der Gutschein im Shop erscheint, bestimmt das Template. Im Admin-Interface gibt es dafür keine Einstellungen.- Das im Feld “HTML-Template” hinterlegte View-Template erzeugt das PDF. Grundlagen dazu stehen unter PDF-Ansichten.
- Der Download-Link für den Kunden wird auf der Bestellbestätigungsseite und in der Bestellbestätigungs-E-Mail ausgegeben. Ein vollständiges Beispiel steht in den Praxisbeispielen Gutscheine.
Typische Fehler
Die genaue Ursache steht im Log-Manager. Alle Meldungen der Gutscheinerzeugung beginnen mit
voucherService.:
Wegweiser
- Gutscheine beschreibt das Anlegen der Kaufgutscheinvorlage.
- content - Katalog, Kategorien und Produkte beschreibt die benutzerdefinierten Produktfelder und ihre Zuordnung.
- API-Referenz Produkte beschreibt dieselben Felder über die Schnittstelle.
- PDF-Ansichten beschreibt die Erzeugung des Gutschein-PDFs.
