Zum Hauptinhalt springen
Ein Kaufgutschein ist ein Produkt im Katalog, das der Kunde wie jeden anderen Artikel bestellt und bezahlt. Nach Abschluss der Bestellung generiert der Shop für jede bestellte Einheit einen Gutscheincode und stellt diesen als PDF bereit. Das Produkt allein genügt dafür nicht. Es verweist auf eine Kaufgutscheinvorlage, die zuvor unter Marketing → Gutscheine angelegt werden muss. Wie das geht, ist unter Gutscheine beschrieben. Diese Seite setzt voraus, dass die Vorlage existiert und ihre Chargen-ID bekannt ist.

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:
Doku Kaufgutschein Produktfelder

Screenshot Stand 02.09.2026

In das Feld “Gutschein-Charge” gehört die Chargen-ID, nicht die Bezeichnung der Vorlage. Der Shop sucht die Kaufgutscheinvorlage ausschließlich über diese ID. Eine Vorlagen-ID oder ein Anzeigename führt beim Bezahlen zum Abbruch.

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üfservice paymentValidation.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üfservice shippingMethodValidation.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.
Die Regel entscheidet anhand des Produkttyps der Artikel im Warenkorb. Trägt das Kaufgutschein-Produkt nicht den Typ, den die Regelliste erwartet, lehnt die Prüfung die Versandart mit dem Fehler productTypeDenied ab, und der Kunde fällt auf eine physische Versandart samt Versandkosten zurück. Das passiert auch dann, wenn das Feld “Produkttyp” am Produkt leer bleibt.

Was beim Bestellabschluss passiert

Die Gutscheine entstehen nicht beim Legen in den Warenkorb, sondern beim Abschluss der Bestellung:
  1. Der Shop liest die Chargen-ID aus dem Produktfeld und sucht die Kaufgutscheinvorlage mit dieser ID.
  2. Er erzeugt je bestellter Einheit einen Gutschein mit den Daten der Vorlage.
  3. 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.
  4. 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.
Die erzeugten Codes und die Links auf die Gutschein-PDFs stehen anschließend in den Bestelldaten unter 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