checkout - Bestellablauf - WEBSALE Dokumentation

Der Abschnitt checkout umfasst alles, was den Bestellprozess in der Storefront steuert: von der einfachen Gast- oder Schnellbestellung über eigene Eingabefelder bis zur Rundung von Zwischensummen. Er ermöglicht zudem eine schnelle Artikelerfassung per Artikelnummer, prüft bei Bedarf Warenkorbinhalte gegen Regeln (z. B. Pflichtzubehör), verwaltet Versandarten inklusive Preislogik und bindet Paketverfolgung an.

`checkout*` - Grundstruktur

Nachfolgend der Grundaufbau des Knotens checkout

{
    "checkout": {
      "checkout": {...},
      "voucher": {...},
      "voucherErrors": {...},
      "directOrder": {...},
      "productDependency": {...},
      "bankInfoField": {...},
      "shippingMethod": {...},
      "shippingMethodGroup": {...},
      "shipTrack": {...}
    }
}

Parameterübersicht

Parameter	Beschreibung
`checkout`	Übergreifende Checkout-Einstellungen für den Bestellprozess.
`voucher`	Einstellungen für die Gutscheinverwendung im Bestellprozess.
`voucherErrors`	Fehlertexte für Gutscheine, die im Warenkorb keine Wirkung haben. Siehe `checkout.voucherErrors`.
`directOrder`	Konfiguration für Direktbestellungen.
`productDependency`	Regeln für Produktabhängigkeiten im Checkout.
`bankInfoField`	Steuerung von Bankdatenfeldern.
`shippingMethod`	Einstellungen zu Versandarten.
`shippingMethodGroup`	Gruppen, zu denen Versandarten zusammengefasst werden können.
`shipTrack`	Optionen für die Sendungsverfolgung.

`checkout.checkout` - Bestellablauf

Dieser Abschnitt bündelt die zentralen Einstellungen des Bestellprozesses. Er richtet sich an Shop-Betreiber, die den Ablauf kaufmännisch festlegen, und an Frontend-Entwickler, die das Ergebnis im Template ausgeben. Vorausgesetzt wird, dass Sie mit dem grundsätzlichen Bestellablauf vertraut sind. Festgelegt wird hier, wie der Bestellprozess abläuft, welche Zusatzfelder erscheinen und wie Versand- und Zahlungsarten vorausgewählt werden. Ebenfalls hier angesiedelt sind die Regeln für Gutschein-Berechnungen, ein Mindermengenzuschlag, die Behandlung von Adressen aus dem PayPal Express Checkout und der Zeitpunkt, ab dem Feldfehler sichtbar werden. Nicht in diesem Abschnitt behandelt: Versandarten und deren Preislogik stehen unter checkout.shippingMethod, die Rundung von Gutscheinbeträgen unter checkout.voucher, die Fehlertexte zu wirkungslosen Gutscheinen unter checkout.voucherErrors, Zahlungsarten unter payment.payment. Die Einstellungen wirken an vier verschiedenen Stellen im Ablauf. Diese Einordnung hilft beim Finden des passenden Parameters:

Vor der Bestellung - Zugang und Vorauswahl: Wer darf bestellen (allowGuestAccounts, allowFastOrder), was ist vorausgewählt (defaults), welche Zusatzfelder erscheinen (freeFields).
Während der Bestellung - Berechnung: Rundung der Zwischensumme (subtotalRounding), Gutschein-Verrechnung (voucherAppliesPerItem, minOrderValueCalculation, minOrderValueIgnoreVoucherReduction, disableOrderOnIneffectiveVoucher) und der Mindermengenzuschlag (surcharge).
Während der Bestellung - Anzeige von Fehlern: fieldErrorVisibility.
Nach der Bestellung: welche Templates noch auf die Bestelldaten zugreifen dürfen (templatesAfterCheckout).

Nachfolgend eine Beispielkonfiguration für checkout.checkout:

{
  "allowFastOrder": true,
  "allowGuestAccounts": true,
  "allowShipTrack": false,
  "defaults": {
    "defaultBillCountry": null,
    "defaultShippingCountry": null,
    "defaultPaymentMethod": null,
    "defaultShippingMethod": null,
    "autoSelectSingleOption": true,
    "prevSelectionInvalidAutoSelect": "disabled"
  },
  "defaultFreeShippingMethod": null,
  "deliveryRequiredForOrder": true,
  "disableOrderOnIneffectiveVoucher": true,
  "expressCheckoutSkipsAddressValidation": true,
  "fieldErrorVisibility": {
    "showMissingBeforeSubmit": false,
    "showInvalidBeforeSubmit": true,
    "showIncompatibleBeforeSubmit": true
  },
  "freeFields": [...],
  "freeShippingCountries": null,
  "minOrderValueCalculation": "max",
  "minOrderValueIgnoreVoucherReduction": true,
  "subtotalRounding": {
    "active": true,
    "decimalPlaces": 2
  },
  "surcharge": {
    "cost": 1.99,
    "threshold": 30.0
  },
  "templatesAfterCheckout": [
    "pdf/checkoutConfirm.htm"
  ],
  "voucherAppliesPerItem": true
}

Parameterübersicht

Parameter	Typ	Beschreibung
`allowGuestAccounts`	bool	Erlaubt Bestellungen ohne Kundenkonto (Gastbestellung). Default: `true`
`allowFastOrder`	bool	Erlaubt die Bestellung per Express-Checkout. Default: `true`
`allowShipTrack`	bool	Aktiviert die Sendungsverfolgung für den Shop. Die Zugangsdaten des Dienstleisters werden unter `checkout.shipTrack` hinterlegt. Default: `false`
`deliveryRequiredForOrder`	bool	Gibt vor, ob eine Versandart ausgewählt sein muss, damit die Bestellung abgeschlossen werden kann. `true` - Checkout nur mit gewählter Versandart möglich. `false` - Bestellung ohne Auswahl einer Versandart zulässig. Default: `true`
`subtotalRounding`	object	Rundung der Zwischensumme vor weiteren Berechnungen (z.B. vor Versand / Gutscheinen).
`active`	bool	Aktiviert die Rundungslogik. Default: `true`
`decimalPlaces`	uint	Anzahl der Nachkommastellen für die Rundung. Default: `2`
`voucherAppliesPerItem`	bool	Steuert, ob Gutscheine pro Position (statt auf den Gesamtwarenkorb) angewendet werden. Default: `false`
`minOrderValueCalculation`	enum	Legt fest, wie der Mindestbestellwert berechnet wird, ab dem ein Gutschein angewendet werden kann. Mögliche Werte: `sum` - die Mindestbestellwerte aller verwendeten Gutscheine werden addiert. Hat z.B. Gutschein A einen Mindestbestellwert von 20€ und Gutschein B von 30€, muss der Warenkorb mindestens 50€ erreichen. `max` - es gilt nur der höchste Mindestbestellwert aller verwendeter Gutscheine. Bei Gutschein A (20€) und Gutschein B (30€) reichen 30€ im Warenkorb aus. Default: `sum`
`minOrderValueIgnoreVoucherReduction`	bool	Bestimmt, welcher Warenwert für die Prüfung des Mindestbestellwertes herangezogen wird. Mögliche Werte: `true` - nur der reine Warenwert zählt. `false` - der Warenwert abzüglich bereits angewandter Gutscheine wird verwendet. Default: `true`
`disableOrderOnIneffectiveVoucher`	bool	Sperrt die Bestellung, solange ein eingelöster Gutschein im aktuellen Warenkorb keinen Rabatt bewirkt. Der Default `true` verhindert, dass ein Kunde in der Annahme bestellt, ein Rabatt greife. Wann ein Gutschein als wirkungslos gilt, steht unter Wirkungslose Gutscheine blockieren. Default: `true`
`surcharge`	object	Mindermengenzuschlag für kleine Warenkörbe. Siehe Mindermengenzuschlag.
`cost`	float	Zuschlagsbetrag in Shop-Währung, der berechnet wird, wenn der Schwellenwert nicht überschritten wird. Default: `0.0`
`threshold`	float	Schwellenwert: Übersteigt die Summe der zuschlagspflichtigen Positionen diesen Wert, entfällt der Zuschlag. Mit dem Default `0.0` ist der Zuschlag praktisch abgeschaltet, da jeder Warenkorb mit Wert darüber liegt. Default: `0.0`
`expressCheckoutSkipsAddressValidation`	bool	Steuert, ob die vom PayPal Express Checkout gelieferte Adresse als reguläre Rechnungs- und Lieferadresse übernommen und gegen die Prüfregeln des Shops geprüft wird. Siehe Adressen aus dem PayPal Express Checkout. Default: `true`
`templatesAfterCheckout`	list (string)	Templates, die nach dem Bestellabschluss noch auf die Bestelldaten zugreifen dürfen. Siehe Templates nach dem Bestellabschluss. Default: `[]`
`fieldErrorVisibility`	object	Legt fest, ab wann Feldfehler im Checkout angezeigt werden. Siehe Fehleranzeige im Checkout.
`showMissingBeforeSubmit`	bool	Zeigt fehlende Pflichtfelder bereits vor dem Klick auf „Kaufen”. Default: `false`
`showInvalidBeforeSubmit`	bool	Zeigt Validierungsfehler bereits vor dem Klick auf „Kaufen”. Default: `true`
`showIncompatibleBeforeSubmit`	bool	Zeigt Inkompatibilitätsfehler bereits vor dem Klick auf „Kaufen”. Default: `true`
`freeShippingCountries` (zukünftiges Feature, noch nicht vollständig implementiert!)	multiAssoc	Länder, in denen versandkostenfrei geliefert wird. Target: `general.country`
`defaultFreeShippingMethod`	singleAssoc	Legt die Standard-Versandart fest, die für Berechnungen zu „kostenlosem Versand” verwendet wird (z.B. Anzeige „noch 45€ bis zum kostenlosen Versand”). Target: `checkout.shippingMethod`
`freeFields`	list (object)	Konfigurierbare Zusatzfelder im Checkout (z.B. Hinweise, Kundennotizen, AGB-Bestätigung). Jedes Objekt beschreibt ein Feld.
`id`	string	Eindeutige Kennung des Zusatzfeldes. Über diese Kennung lesen Sie das Feld im Template aus `$wsCheckout.freeFields`.
`name`	text	Anzeigename / Label im Checkout.
`required`	bool	Markiert das Feld als Pflichtfeld. Default: `false`
`type`	oneOf	Feldtyp und Detailkonfiguration: `text` oder `checkbox`.
`text`	object	Textfeld-Konfiguration.
`default`	string	Vorbelegung des Textfeldes.
`textfieldChecks`	multiService	Prüfregeln für die Eingabe. Target: `dataChecker`
`checkbox`	object	Checkbox-Konfiguration.
`default`	bool	Legt fest, ob die Checkbox vorausgewählt ist. Default: `false`
`merchantText`	string	Interner Text zur Checkbox für den Händler.
`defaults`	object	Definiert Standardwerte für Felder im Checkout.
`defaultBillCountry`	singleAssoc	Standardland für die Rechnungsadresse. Wird beim Anlegen einer neuen Adresse im Checkout vorausgefüllt - bei Nutzung der Draft-Adresse (draftBillAddress) sowie bei Gastbestellungen. Target: `general.country`
`defaultShippingCountry`	singleAssoc	Standardland für die Lieferadresse. Wird beim Anlegen einer neuen Adresse im Checkout vorausgefüllt - bei Nutzung der Draft-Adresse (draftShippingAddress) sowie bei Gastbestellungen. Target: `general.country`
`defaultPaymentMethod`	singleAssoc	Zahlungsart, die im Checkout standardmäßig vorausgewählt wird. Target: `payment.payment`
`defaultShippingMethod`	singleAssoc	Liefermethode, die im Checkout standardmäßig vorausgewählt wird. Target: `checkout.shippingMethod`
`autoSelectSingleOption`	bool	Wenn aktiviert, wird automatisch eine Versandmethode oder Zahlungsart ausgewählt, sofern nur eine gültige Option verfügbar ist. Das erspart dem Kunden eine Auswahl ohne Alternative. Default: `true`
`prevSelectionInvalidAutoSelect`	enum	Steuert, ob eine bereits gewählte Versand- oder Zahlungsart automatisch ersetzt wird, wenn sie durch eine Änderung des Bestellkontexts (z.B. Wechsel des Lieferlandes) ungültig wird. Gilt für Versand- und Zahlungsarten (keine getrennte Option je Art). Mögliche Werte: `disabled` - keine automatische Neuauswahl durch diese Option; die Auswahl wird als ungültig markiert und der Kunde wählt neu (`autoSelectSingleOption` greift weiterhin). `ifSingleOption` - bleibt genau eine gültige Art übrig, wird diese automatisch gewählt (auch wenn `autoSelectSingleOption` deaktiviert ist); bleiben mehrere gültig, erfolgt keine automatische Auswahl. `always` - es wird immer eine gültige Ersatz-Art gewählt: bevorzugt die konfigurierte Standard-Art (`defaultShippingMethod` bzw. `defaultPaymentMethod`), sofern gültig; andernfalls die einzige verbleibende gültige Art. Der Default `disabled` ist die zurückhaltendste Variante: eine bewusste Kundenauswahl wird nie stillschweigend gegen eine andere getauscht. Default: `disabled`

Ob eine Gastbestellung mit einer bereits registrierten E-Mail-Adresse erlaubt ist, wird nicht hier festgelegt, sondern in der Konfiguration der Aktion CheckoutSetGuestEmail unter restrictions.allowGuestOrderWithRegisteredEmail.

Prioritätslogik für defaults: Wenn mehrere Quellen (z.B. Benutzerauswahl oder Kundenpräferenzen) einen Wert für ein Feld in defaults liefern, gilt folgende Rangfolge der Priorisierung:

Aktive Benutzerauswahl in der aktuellen Sitzung - wird niemals automatisch überschrieben.
Gespeicherte Kundenpräferenzen eines eingeloggten Kunden (sofern unterstützt).
Händler-Konfiguration - die hier definierten defaults-Werte.
System-Fallback - z.B. automatische Auswahl bei nur einer verfügbaren Option oder erste gültige Option nach Sortierung (siehe autoSelectSingleOption).

Neuauswahl, wenn eine gewählte Art nachträglich ungültig wird:Die Prioritätslogik oben gilt für die Erstauswahl. Wird dagegen eine bereits getroffene, aber inzwischen ungültige Auswahl behandelt - etwa weil der Kunde das Lieferland wechselt und die gewählte Versandart dort nicht angeboten wird -, steuert prevSelectionInvalidAutoSelect, wie der Shop reagiert (siehe Tabelle oben). autoSelectSingleOption bleibt dabei in allen Modi als Rückfallebene aktiv.

Hinweis zum Rundungsverhalten bei positionsbasierter Gutschein-Berechnung:
Wenn „voucherAppliesPerItem” auf „true” gesetzt ist und ein prozentualer Gutschein mit einem konfigurierten Maximalbetrag verwendet wird, kann der gewährte Rabatt diesen Maximalbetrag um bis zu 0,01 € überschreiten. Grund dafür ist, dass der Rabatt pro Position einzeln gerundet wird und die Summe dieser Rundungen minimal vom erwarteten Gesamtbetrag abweichen kann.

Mindermengenzuschlag

Der Mindermengenzuschlag ist ein fester Betrag, der auf kleine Warenkörbe aufgeschlagen wird. Damit deckt der Shop die Bearbeitungs- und Versandkosten, die bei einer Kleinbestellung anteilig zu hoch ausfallen. Der Shop berechnet den Zuschlag bei jeder Warenkorb-Berechnung neu, in dieser Reihenfolge:

Der Shop bildet die Summe der zuschlagspflichtigen Positionen. Gezählt wird die Positionssumme, also Preis mal Menge. Unterpositionen eines Sets zählen nicht mit, weil sie sonst doppelt in die Summe eingehen würden.
Enthält der Warenkorb keine zuschlagspflichtige Position, fällt kein Zuschlag an.
Übersteigt die Summe den Wert threshold, fällt kein Zuschlag an.
Andernfalls wird cost als Zuschlag berechnet.

Der Vergleich in Schritt 3 ist ein „größer als”. Bei "threshold": 30 und einer Summe von genau 30,00 € fällt der Zuschlag also noch an, ab 30,01 € nicht mehr. Setzen Sie den Schwellenwert entsprechend auf den letzten Betrag, für den noch zugeschlagen werden soll. Standardmäßig ist jede Position zuschlagspflichtig. Ausnehmen können Sie einzelne Produkte über das Produktfeld, das unter content.usedFields.validForSurcharge hinterlegt ist: Liefert dieses Feld für eine Position false, zählt sie weder für die Prüfung mit, noch löst sie den Zuschlag aus. Das ist etwa für Gutscheinprodukte oder digitale Artikel sinnvoll, die keinen Bearbeitungsaufwand verursachen. Ein Beispiel: Ein Zuschlag von 1,99 € soll bis zu einem Warenwert von 30 € anfallen. Die Konfiguration in checkout.checkout lautet dann:

{
  "surcharge": {
    "cost": 1.99,
    "threshold": 30.0
  }
}

Ausgabe in der Kostenaufstellung des Templates. Der Zuschlag steht als berechneter Betrag in $wsCheckout.sum.surchargeCost; ist er 0, wird die Zeile nicht ausgegeben:

{{ if $wsCheckout.sum.surchargeCost > 0 }}
   <tr>
      <td>Mindermengenzuschlag</td>
      <td>{{= $wsCheckout.sum.surchargeCost | currency }}</td>
   </tr>
{{ /if }}

Erwartete Wirkung: Bei einem Warenkorb von 24,50 € erscheint die Zeile mit 1,99 €, und die Gesamtsumme steigt auf 26,49 €. Bei einem Warenkorb von 45,00 € entfällt die Zeile.

Wirkungslose Gutscheine blockieren

Ein Kunde kann einen Gutschein einlösen, der im aktuellen Warenkorb gar keinen Rabatt bewirkt. Bestellt er in diesem Zustand, entsteht eine Rückfrage oder Reklamation, weil der erwartete Rabatt fehlt. disableOrderOnIneffectiveVoucher verhindert das. Der Ablauf:

Der Kunde löst einen Gutschein ein. Der Gutschein liegt in der Session.
Bei jeder Berechnung prüft der Shop für jeden eingelösten Gutschein, ob er im aktuellen Warenkorb einen Rabatt größer 0 erzeugt.
Als wirkungslos gilt ein Gutschein in zwei Fällen: Der Warenkorb erreicht den Mindestbestellwert nicht, oder der berechnete Rabatt ist 0, weil keine Position im Warenkorb für diesen Gutschein rabattfähig ist. Welcher der beiden Fälle vorliegt, ist im Template auswertbar. Die genauen Regeln stehen unter Wann welcher Fehler entsteht.
Reine Versandkosten-Gutscheine ohne Prozent- und ohne Absolutwert sind davon ausgenommen. Sie wirken über die Versandkosten und blockieren die Bestellung nie.
Ist disableOrderOnIneffectiveVoucher aktiv und mindestens ein Gutschein wirkungslos, meldet der Shop die Bestellung als gesperrt.

Im Template lesen Sie den Zustand über das Flag $wsCheckout.isOrderBlockedByIneffectiveVoucher und deaktivieren den Bestellbutton. Über die Liste $wsCheckout.ineffectiveVoucherErrors nennen Sie dem Kunden zusätzlich den Grund und den betroffenen Gutschein:

{{ if $wsCheckout.isOrderBlockedByIneffectiveVoucher }}
   <div role="alert">
      <strong>Gutscheine können nicht eingelöst werden:</strong>
      <ul>
         {{ foreach $cError in $wsCheckout.ineffectiveVoucherErrors }}
            <li>
               {{ if $cError.details.voucherId }}
                  Gutschein <strong>{{= $cError.details.voucherId }}</strong>:
               {{ /if }}
               {{= $cError.text | ifNull($cError.code) }}
            </li>
         {{ /foreach }}
      </ul>
   </div>
   <button type="submit" class="btn btn-warning" disabled>Bestellung absenden</button>
{{ else }}
   <button type="submit" class="btn btn-warning">Bestellung absenden</button>
{{ /if }}

Erwartete Wirkung: Nach dem Einlösen eines Gutscheins mit 50 € Mindestbestellwert in einen Warenkorb über 20 € wird der Bestellbutton deaktiviert, und der Hinweis nennt den Gutschein samt Grund. Nach dem Auffüllen des Warenkorbs über 50 € ist der Button wieder aktiv, und die Liste ist leer. Die ausgegebenen Texte pflegen Sie nicht hier, sondern im Konfigurationsknoten checkout.voucherErrors. Den Aufbau der einzelnen Fehlerobjekte finden Sie in der Modul-Referenz unter $wsCheckout.ineffectiveVoucherErrors. Setzen Sie den Parameter nur dann auf false, wenn Kunden in Ihrem Shop bewusst Gutscheine im Warenkorb liegen lassen dürfen, ohne dass diese wirken.

Adressen aus dem PayPal Express Checkout

Startet ein Kunde den PayPal Express Checkout aus dem Warenkorb, liefert PayPal die dort hinterlegte Adresse zurück. Diese Adresse erfüllt die Prüfregeln Ihres Shops nicht immer - etwa weil PayPal keine Hausnummer getrennt übergibt. expressCheckoutSkipsAddressValidation legt fest, wie der Shop damit umgeht. true (Default): Der Shop prüft die Adresse nicht und übernimmt sie nicht als Rechnungs- oder Lieferadresse der Bestellung. Sie bleibt in der Session und steht in den Bestelldaten unter paypalCheckout.rawAddress. Drittsysteme können sie dort auslesen und bei Bedarf selbst weiterverarbeiten. Der Default true hält damit die Adressdaten des Shops frei von ungeprüften Fremddaten - die Lieferadresse im Shop bleibt sauber. false: Die Adresse wird direkt von PayPal als normale Adresse übernommen. Dann muss sie auch die Prüfregeln des Shops erfüllen. Da sie ungeprüft aus dem PayPal-Konto stammt, kann es passieren, dass sie diesen Regeln nicht entspricht. In diesem Fall muss der Kunde die Adresse vor dem Bestellabschluss bearbeiten - der Express Checkout verliert damit seinen Vorteil, ohne zusätzlichen Eingabeschritt abschließbar zu sein. Unabhängig von dieser Einstellung werden die Adressdaten dem Kunden angezeigt, soweit PayPal sie liefert. Übergibt PayPal beispielsweise keine Straße, wird auch keine Straße angezeigt. Ausschnitt aus den Bestelldaten bei aktivem Parameter:

{
  "paypalCheckout": {
    "expressCheckout": "true",
    "rawAddress": {
      "...": "von PayPal geliefertes Adressobjekt"
    }
  }
}

Bei aktivem Parameter enthalten die regulären Adressfelder der Bestellung keine Adresse aus dem Express Checkout. Es kann also eine Bestellung ohne reguläre Adressdaten entstehen. Ob eine solche Bestellung weiterverarbeitet werden kann, hängt vom angebundenen Connector ab. Prüfen Sie das, bevor Sie den Express Checkout produktiv nehmen.

true ist der Standardweg für den PayPal Express Checkout: Der Shop prüft die Adresse nicht und übernimmt sie nicht. Deaktivieren Sie den Parameter nur nach Prüfung, denn Auswirkungen auf den Express Checkout selbst sind nicht auszuschließen. Die Anforderungen von PayPal an diesen Ablauf bildet diese Dokumentation nicht ab - klären Sie sie bei Bedarf direkt mit PayPal.

Templates nach dem Bestellabschluss

Nach dem Bestellabschluss gilt die Session als beendet. Die Bestelldaten stehen dann nur noch den Templates zur Verfügung, die zur Bestellbestätigung zählen. Ruft der Kunde ein anderes Template auf, erhält er eine neue Session. In dieser neuen Session sind die Bestelldaten nicht mehr erreichbar. Das ist beabsichtigt: Eine abgeschlossene Bestell-Session soll nicht länger als nötig weiterleben. Die Zielseite nach dem Checkout ist automatisch enthalten. Jedes weitere Template, das Bestelldaten braucht, müssen Sie in templatesAfterCheckout eintragen - typischerweise eine PDF-Bestellbestätigung:

{
  "templatesAfterCheckout": [
    "pdf/checkoutConfirm.htm"
  ]
}

Erwartete Wirkung: Ohne diesen Eintrag ist die PDF-Bestellbestätigung leer, weil $wsCheckout.orderId und die übrigen Bestelldaten in der neuen Session fehlen. Mit dem Eintrag werden Bestellnummer, Positionen und Summen ausgegeben. Fehlende Bestelldaten auf einer Folgeseite nach dem Checkout sind deshalb fast immer ein fehlender Eintrag in dieser Liste.

Fehleranzeige im Checkout

Nicht jeder Fehler soll dem Kunden sofort gezeigt werden. Ein leeres Pflichtfeld rot zu markieren, bevor der Kunde es überhaupt erreicht hat, wirkt wie ein Fehler des Kunden. Eine falsch formatierte Postleitzahl dagegen sollte er sofort korrigieren können. fieldErrorVisibility trennt diese Fälle nach Fehlerart.

Parameter	Typ	Beschreibung
`showMissingBeforeSubmit`	bool	Wenn `true`, werden „Pflichtfeld fehlt”-Felder bereits angezeigt, bevor der Kunde auf „Kaufen” klickt. Wenn `false`, erscheinen diese erst nach dem Klick auf „Kaufen”. Der Default `false` vermeidet, dass noch unbearbeitete Felder als Fehler erscheinen. Default: `false`
`showInvalidBeforeSubmit`	bool	Wenn `true`, werden Validierungsfehler (z.B. ungültige PLZ, fehlerhaftes Datumsformat) sofort nach der Eingabe angezeigt. Wenn `false`, erscheinen diese erst nach dem Klick auf „Kaufen”. Der Default `true` erlaubt die Korrektur, während der Kunde noch im Feld ist. Default: `true`
`showIncompatibleBeforeSubmit`	bool	Wenn `true`, werden Inkompatibilitätsfehler (z.B. Zahlart für dieses Land nicht verfügbar) sofort angezeigt. Wenn `false`, erscheinen diese erst nach dem Klick auf „Kaufen”. Der Default `true` verhindert, dass der Kunde den Checkout mit einer Kombination fortsetzt, die ohnehin scheitert. Default: `true`

Nach dem Klick auf „Kaufen” werden standardmäßig alle Fehler angezeigt, unabhängig von dieser Einstellung.Im Checkout gibt es grundsätzlich zwei Arten von Fehlern:

Fehler, die das System selbst erkennt (z.B. „Pflichtfeld leer”, „ungültige PLZ”):
Diese werden über $wsCheckout.problems.* bereitgestellt und lassen sich vollständig über die show*BeforeSubmit-Parameter steuern.
Fehler, die der Server zurückmeldet (z.B. nach dem Klick auf „Kaufen”):
Hier greifen die Einstellungen der show*BeforeSubmit-Parameter nur teilweise. Bei Kundendaten und Draft-Adressen steht $wsCheckout.problems.* nicht zur Verfügung, deshalb werden die Serverfehler dort stattdessen über die show*BeforeSubmit-Parameter gefiltert. In allen anderen Bereichen des Checkouts (z.B. bei der Zahlungsart) werden Serverfehler immer sofort angezeigt, unabhängig von der Konfiguration.

`checkout.voucher` - Einstellungen für Gutscheine

In diesem Abschnitt werden die Einstellungen für die Verwendung von Gutscheinen im Bestellprozess gebündelt. Hier wird unter anderem festgelegt, wie viele Gutscheine ein Kunde gleichzeitig einlösen kann und wie Rabattbeträge bei prozentualen Gutscheinen rechnerisch gerundet werden. Nachfolgend eine Beispielkonfiguration für checkout.voucher:

{
  "maxNumberVouchersPerOrder": 1,
  "roundPercentalVoucherInBasketItem": "single"
}

Parameterübersicht

Parameter	Typ	Beschreibung
`maxNumberVouchersPerOrder`	uint	Maximale Anzahl an Gutscheinen, die pro Bestellung angewandt werden können. Mögliche Werte: `1` - `20` Default: `1`
`roundPercentalVoucherInBasketItem`	enum	Legt fest, wie Rabattbeträge aus prozentualen Gutscheinen pro Artikel gerundet werden, wenn mehrere Gutscheine gleichzeitig aktiv sind. Mögliche Werte: `sum` - Der Rabatt jedes einzelnen Gutscheins wird pro Artikel zunächst ungerundet berechnet. Alle Rabattbeträge werden addiert und das Ergebnis erst am Ende gerundet. `single` - Der Rabattbetrag jedes Gutscheins wird pro Artikel sofort einzeln gerundet. Weil jede Rundung einen kleinen Fehler einführen kann, weicht die Gesamtersparnis je nach Artikelpreis und Gutscheinhöhe um wenige Cent vom `sum`-Ergebnis ab.

`checkout.voucherErrors` - Fehlertexte zu wirkungslosen Gutscheinen

Ein eingelöster Gutschein kann im aktuellen Warenkorb wirkungslos sein. Damit der Kunde nicht nur einen allgemeinen Hinweis liest, sondern den konkreten Grund erfährt, pflegen Sie in diesem Knoten je Fehlerfall einen eigenen Text. Der Shop übersetzt den passenden Text und stellt ihn im Template über $wsCheckout.ineffectiveVoucherErrors bereit. Der Knoten enthält ausschließlich Texte. Ob eine Bestellung mit einem wirkungslosen Gutschein tatsächlich blockiert wird, steuert disableOrderOnIneffectiveVoucher unter Wirkungslose Gutscheine blockieren. Nachfolgend eine Beispielkonfiguration für checkout.voucherErrors:

{
  "ineffectiveVoucherErrorCodes": {
    "noValidProducts": "<Textbaustein>",
    "minOrderValueNotReached": "<Textbaustein>"
  }
}

Parameterübersicht

Parameter	Typ	Beschreibung
`ineffectiveVoucherErrorCodes`	object	Bündelt die Fehlertexte für Gutscheine, die im Warenkorb keine Wirkung haben.
`noValidProducts`	string	Fehlermeldung, die ausgegeben wird, wenn der Gutschein auf keine Position im Warenkorb anwendbar ist. Das tritt beispielsweise auf, wenn der Gutschein nur für bestimmte Produkte oder Kategorien gilt und keine davon im Warenkorb liegt, oder wenn keine Position im Warenkorb rabattfähig ist. Default: `ws.error.checkout.ineffectiveVoucherNoValidProducts`
`minOrderValueNotReached`	string	Fehlermeldung, die ausgegeben wird, wenn der Mindestbestellwert für den Gutschein unterschritten ist. Default: `ws.error.checkout.ineffectiveVoucherMinOrderValueNotReached`

Wann welcher Fehler entsteht

Der Shop ermittelt die Fehler bei jeder Berechnung neu, einmal pro eingelöstem Gutschein. Welcher der beiden Codes gesetzt wird, entscheidet sich in dieser Reihenfolge:

Mindestbestellwert des einzelnen Gutscheins. Liegt der Mindestbestellwert eines Gutscheins über dem Prüfwert des Warenkorbs, entsteht minOrderValueNotReached für genau diesen Gutschein. Als Prüfwert gilt der Warenwert. Steht minOrderValueIgnoreVoucherReduction auf false, wird der Warenwert vorher um die bereits angerechneten Gutscheinwerte reduziert.
Rabattwirkung im Warenkorb. Erreicht der Warenkorb den Mindestbestellwert und bleibt der berechnete Rabatt trotzdem 0, entsteht noValidProducts für diesen Gutschein.
Summe der Mindestbestellwerte. Steht minOrderValueCalculation auf sum und erreichen alle Gutscheine ihren jeweils eigenen Mindestbestellwert, muss der Warenkorb zusätzlich die Summe aller Mindestbestellwerte erreichen. Wird sie nicht erreicht, entsteht minOrderValueNotReached genau einmal. Dieser Fehler lässt sich keinem einzelnen Gutschein zuordnen und enthält deshalb keine Gutschein-ID.

Reine Versandkosten-Gutscheine ohne Prozent- und ohne Absolutwert erzeugen keinen dieser Fehler.

Weil der Fehler aus Schritt 3 ohne Gutschein-ID kommt, prüfen Sie im Template immer erst, ob details.voucherId gesetzt ist, bevor Sie die ID ausgeben. Ein vollständiges Beispiel dazu finden Sie unter Praxisbeispiele - Gutscheine.

`checkout.directOrder` - Onlinebestellschein

Ermöglicht eine schnelle Erfassung von Artikeln per Artikelnummer - beispielsweise für große oder wiederkehrende Bestellungen. Festgelegt wird, welche Spalten pro Zeile sichtbar sind (z.B. Artikelnummer, Menge). Auf Wunsch merkt sich das System die zuletzt verwendete Zeilenanzahl über saveCountInSession. Nachfolgend eine Beispielkonfiguration für checkout.directOrder:

{
  "fields": [
    "content.productField.id",
    "content.productField.itemNumber"
  ],
  "initialNumber": 5,
  "itemNumberFields": [],
  "maximalNumber": 1000,
  "refreshedNumber": 1,
  "saveCountInSession": true
}

Parameterübersicht

Parameter	Typ	Beschreibung
`fields`	multiAssoc	Legt fest, in welchen Produktfeldern gesucht wird, um ein Produkt zu finden (z.B. `content.productField.id, content.productField.itemnumber).` Beispiel: Wenn `id` oder `itemNumber` konfiguriert sind, kann der Nutzer entweder die Produkt-ID oder die Artikelnummer eingeben. Target: `[content.productField], [content.customProductField]`
`initialNumber`	int	Anzahl der Zeilen, die beim ersten Laden sichtbar sind. Default: 5
`itemNumberFields`	list (object)	Eingabefelder pro Zeile für die Artikelnummer-Erfassung - definiert Spalten / Felder und Beschriftungen (z.B. Reihenfolge, Label, Platzhalter).
`maximalNumber`	int	Obergrenze der insgesamt zulässigen Eingabezeilen. Default: 1000
`refreshedNumber`	int	Anzahl der verfügbaren Zeilen, die bei Klick auf den Button “Zeilen hinzufügen” hinzugefügt werden. Default: 5
`saveCountInSession`	bool	Speichert die aktuelle Zeilenanzahl in der Session, damit sie beim nächsten Aufruf wiederhergestellt wird. default: true

`checkout.productDependency` - Produktabhängigkeiten

Dieser Abschnitt legt fest, wann bestimmte Schritte oder Optionen im Checkout erlaubt sind. Er prüft dazu die Inhalte des Warenkorbs - etwa Eigenschaften wie Größe, Farbe oder ob ein Zusatzfeld ausgefüllt ist - und kann bei Nichterfüllung einen Hinweis anzeigen oder die Aktion sperren. Typische Einsatzfälle sind beispielsweise Pflichtzubehör oder das Verhindern verbotener Kombinationen im Checkout. Nachfolgend eine Beispielkonfiguration für checkout.productDependency:

{
  "id": "",
  "disabledText": "",
  "dependencyGroups": [
    {
      "dependencies": [
        {
          "target": { "field": "content.productField:color" },
          "type": "value",
          "input": { "text": { "value": "camel" } },
          "basketBehavior": "matchOnce"
        },
        {
          "target": { "freeField": "engraving" },
          "type": "empty",
          "input": { "text": { "value": "" } },
          "basketBehavior": "matchOnce"
        }
      ]
    },
    {
      "dependencies": [
        {
          "target": { "field": "content.customProductField:size" },
          "type": "inlist",
          "input": { "list": { "value": ["S", "M", "L"] } },
          "basketBehavior": "matchOnce"
        }
      ]
    }
  ]
}

Auswertungslogik

Die Regelgruppen und Bedingungen werden nach einem festen Schema ausgewertet:

dependencyGroups sind ODER-verknüpft: Es genügt, wenn eine der Gruppen vollständig erfüllt ist.
dependencies innerhalb einer Gruppe sind UND-verknüpft: Innerhalb einer Gruppe müssen alle Bedingungen erfüllt sein.
Ob eine einzelne Bedingung als erfüllt gilt, steuert zusätzlich basketBehavior: Bei matchOnce muss mindestens eine Warenkorb-Position die Bedingung erfüllen, bei matchAll alle Positionen, bei denen das geprüfte Feld einen Wert liefert.

Im Beispiel oben gilt die Abhängigkeit also als erfüllt, wenn entweder die erste Gruppe zutrifft (eine Position mit der Farbe camel und eine Position mit leerem Freifeld engraving im Warenkorb) oder die zweite Gruppe (eine Position mit Größe S, M oder L).

Parameterübersicht

Parameter	Typ	Beschreibung
`id`	string	Eindeutige Kennung der Produktabhängigkeit, die selbst gewählt werden kann. Die `id` wird in den Validierungen `shippingMethodValidation.productDependency` (Versandarten) und `paymentValidation.productDependency` (Zahlungsarten) angegeben. Mehr dazu unter: Validierungs- und Prüfservices
`disabledText`	string	Hinweis-/Fehlermeldung, die angezeigt wird, wenn Bedingungen nicht erfüllt sind. Bei Versandarten wird der Text im Frontend über `$wsCheckout.getShippingMethodDisabledErrors()` ausgegeben.
`dependencyGroups`	list (object)	Enthält eine oder mehrere Regelgruppen. Die Gruppen sind ODER-verknüpft (siehe Auswertungslogik oben).
`dependencies`	list (object)	Liste einzelner Bedingungen innerhalb einer Gruppe. Die Bedingungen sind UND-verknüpft. Jede Bedingung legt fest, welches Feld geprüft wird, wie geprüft wird und welcher Vergleichswert ggf. nötig ist.
`target`	oneOf	Definiert, welches Feld geprüft wird. (Pflichtfeld)
`field`	singleAssoc	Referenz auf ein Produktfeld, das geprüft wird. Target: `content.productField, content.customProductField`
`freeField`	string	Name eines freien Feldes (z.B. Freifeld am Produkt/Warenkorb), das geprüft wird. (Alternativ zu `field`)
`type`	enum	Pflichtfeld Vergleichsart der Bedingung. Die möglichen Werte sind in der Tabelle „Prüfarten” unten beschrieben.
`input`	oneOf	Vergleichswert der Bedingung. (nur erforderlich, wenn der `type` einen Vergleichswert benötigt). Z.b. nicht erforderlich bei `filled` / `empty.`
`text`	object	Textbasierter Vergleichswert.
`value`	string	Wert für textbasierte Vergleiche. (z. B. bei `value`, `prefix`, `matchsimplewildcard`)
`list`	object	Werteliste für Listenvergleiche (z. B. bei `inlist`, `includedinlist`).
`value`	list (string)	Werteliste für den Vergleich.
`basketBehavior`	enum	Legt fest, wie viele Warenkorb-Positionen die Bedingung erfüllen müssen: `matchOnce` = mind. eine Position `matchAll` = alle Positionen, bei denen das geprüfte Feld einen Wert liefert. Default:`matchOnce`

Prüfarten (`type`)

Wert	Beschreibung
`filled`	Das Feld ist gefüllt. Kein `input` erforderlich.
`empty`	Das Feld ist leer. Kein `input` erforderlich.
`value`	Der Wert des Feldes entspricht dem in `input` angegebenen Wert.
`notvalue`	Der Wert des Feldes entspricht nicht dem in `input` angegebenen Wert.
`inlist`	Der Wert des Feldes ist in der in `input` angegebenen Liste enthalten.
`notinlist`	Der Wert des Feldes ist nicht in der in `input` angegebenen Liste enthalten.
`prefix`	Der Wert des Feldes beginnt mit dem in `input` angegebenen Präfix.
`notprefix`	Der Wert des Feldes beginnt nicht mit dem in `input` angegebenen Präfix.
`greater`	Der Wert des Feldes ist (numerisch) größer als der in `input` angegebene Wert.
`smaller`	Der Wert des Feldes ist (numerisch) kleiner als der in `input` angegebene Wert.
`includedinlist`	Der in `input` angegebene Wert ist in der Werte-Liste des Produktdatenfeldes enthalten (für Felder, die mehrere Werte enthalten).
`notincludedinlist`	Der in `input` angegebene Wert ist nicht in der Werte-Liste des Produktdatenfeldes enthalten.
`matchsimplewildcard`	Der Wert des Feldes stimmt mit dem in `input` angegebenen Muster überein. Als Platzhalter stehen `?` (genau ein beliebiges Zeichen) und `*` (beliebig viele beliebige Zeichen) zur Verfügung; beide können mehrfach und an beliebiger Position verwendet werden.
`notmatchsimplewildcard`	Der Wert des Feldes stimmt nicht mit dem in `input` angegebenen Muster überein.

`checkout.shippingMethod` - Versandarten

Definiert verfügbare Versandarten und deren Verhalten im Checkout. Neben Aktivierung, Name und Bestellhinweisen lassen sich Preisstaffeln nach Gewicht (weightCost) und nach Warenkorb-Zwischensumme (basicCost) konfigurieren. Über Validierungen (validations) können Bedingungen wie zulässige Länder, nur physische Produkte oder weitere Regeln hinterlegt werden. Ergänzend sind Beschreibung, Bild/Icon und externer Link (z. B. Carrier-Info) möglich. Über das Feld group lässt sich eine Versandart zudem einer Versandarten-Gruppe zuordnen. So entstehen klar benannte, regelkonforme Versandoptionen mit transparenter Preislogik und optionalen Einschränkungen. Nachfolgend eine Beispielkonfiguration für checkout.shippingMethod:

{
  "active": true,
  "id": "checkout.shippingMethod.dhl_standard",
  "name": "DHL Standard",
  "orderText": "Versand mit DHL, Lieferzeit 2–3 Werktage.",
  "weightCost": [
    { "weight": 0.0,  "cost": 4.90 },
    { "weight": 5.0,  "cost": 6.90 },
    { "weight": 31.5, "cost": 12.90 }
  ],
  "basicCost": [
    { "subtotal": 0.0,  "cost": 4.90 },
    { "subtotal": 50.0, "cost": 0.0 }
  ],
  "validations": [
    {
      "service": "shippingMethodValidation.shippingCountry",
      "options": { "countries": ["DE", "AT"] }
    },
    {
      "service": "shippingMethodValidation.onlyPhysicalProducts",
      "options": { "enabled": true }
    }
  ],
  "link": "https://www.dhl.de/de/privatkunden/pakete-versenden.html",
  "description": "Zuverlässiger Standardversand innerhalb DE/AT.",
  "image": "https://cdn.example.com/shipping/dhl.png",
  "type": "standard",
  "group": "checkout.shippingMethodGroup.standard"
}

Parameterübersicht

Parameter	Typ	Beschreibung
`active`	bool	Aktiviert / deaktiviert die Versandart im Shop.
`id`	string	Eindeutige Kennung der Versandart.
`name`	string	Anzeigename der Versandart.
`orderText` (zukünftiges Feature / befindet sich noch in Entwicklung)	text	Bestell- / Hinweistexte zur Versandart.
`validations`	multiService	Liste von Prüf- / Freigaberegeln (z.B. Länder - / Produktbeschränkungen).
`link` (zukünftiges Feature / befindet sich noch in Entwicklung)	text	Externer Link mit Zusatzinfos.
`description` (zukünftiges Feature / befindet sich noch in Entwicklung)	string	Kurze Beschreibung der Versandart.
`image` (zukünftiges Feature / befindet sich noch in Entwicklung)	string	Bild- / Icon-URL der Versandart.
`weightCost`	object	Staffelpreise nach Gewicht.
`basicCost`	object	Staffelpreise nach Warenkorb-Zwischensumme.
`taxable`	bool	Legt fest, ob auf die Versandkosten Steuern berechnet werden. Bei `false` wird der Versandkosten-Steuersatz in der Bestellung mit `0` ausgewiesen.
`type`	enum	`standard` oder `pickup`. Bei `standard` handelt es sich um einen “normalen” Versand über einen Versender wie DHL, UPS etc. `pickup` kennzeichnet, dass es sich um “Click and Collect” und somit um eine Abholung in einem Store, Markt oder einer Filiale handelt. Für die Auswahl im Bestellablauf wird die Aktion `CheckoutStoreIdSelect` verwendet. Wurde kein Markt ausgewählt wird Standardmäßig der Markt aus der allgemeinen Auswahl verwendet.
`group`	singleAssoc	Ordnet die Versandart einer Versandarten-Gruppe zu. Target: `checkout.shippingMethodGroup`

`checkout.shippingMethodGroup` - Versandarten-Gruppen

Definiert Gruppen, zu denen Versandarten zusammengefasst werden können (z. B. nach Anbieter oder Lieferart). Eine Versandart wird über ihr Feld group einer Gruppe zugeordnet. Je Gruppe lassen sich Name, Beschreibung, Bild und ein Link hinterlegen - etwa, um im Frontend mehrere Versandarten gebündelt und einheitlich darzustellen. Nachfolgend eine Beispielkonfiguration für checkout.shippingMethodGroup:

{
  "id": "checkout.shippingMethodGroup.express",
  "name": "Express-Versand",
  "description": "Schnelle Lieferung innerhalb von 24 Stunden.",
  "image": "https://cdn.example.com/shipping/express.png",
  "link": "https://www.example.com/versand/express"
}

Parameterübersicht

Parameter	Typ	Beschreibung
`id`	string	Eindeutige Kennung der Versandarten-Gruppe.
`name`	text	Anzeigename der Gruppe.
`description`	text	Beschreibung der Gruppe.
`image`	string	Bild- / Icon-URL der Gruppe.
`link`	string	Externer Link mit Zusatzinfos zur Gruppe.

Im Template werden die Gruppen über $wsConfig.shippingMethodGroups gelesen. Die einer Versandart zugewiesene Gruppe steht dort im Feld group der Versandart.

`checkout.shipTrack` - Paketverfolgung

Konfiguriert die Anbindung an Versanddienstleister zur Sendungsverfolgung. Hinterlegt werden Provider-Kennung und Zugangsdaten (API-User/Token) sowie ein Sprachcode für Provider-Antworten und Labeling. Auf Basis dieser Daten lassen sich Tracking-Links und Statusinformationen im Checkout bzw. im Kundenkonto bereitstellen und automatisiert in Benachrichtigungen verwenden. Nachfolgend eine Beispielkonfiguration für checkout.shipTrack:

{
  "id": "shiptrack.dhl",
  "provider": "DHL",
  "username": "api-user-123",
  "password": "s3cr3t-token",
  "languageCode": "de"
}

Parameterübersicht

Parameter	Typ	Beschreibung
`id`	string	Eindeutige Kennung der Versand-Tracking-Konfiguration.
`provider`	string	Anbieter-Kennung. Derzeit wird ausschließlich `DHL` unterstützt - der Wert muss exakt so geschrieben werden (Groß-/Kleinschreibung beachten), sonst kann die Tracking-Integration nicht zugeordnet werden.
`username`	string	API-Benutzername / Zugang für den Provider.
`password`	string	API-Passwort / Token für den Provider.
`languageCode`	string	Sprachcode für Labels / Antworten des Providers (ISO, z.B. de, en). Leer = bei `DHL` wird `de` verwendet.

​checkout* - Grundstruktur

​Parameterübersicht

​checkout.checkout - Bestellablauf

​Parameterübersicht

​Mindermengenzuschlag

​Wirkungslose Gutscheine blockieren

​Adressen aus dem PayPal Express Checkout

​Templates nach dem Bestellabschluss

​Fehleranzeige im Checkout

​checkout.voucher - Einstellungen für Gutscheine

​Parameterübersicht

​checkout.voucherErrors - Fehlertexte zu wirkungslosen Gutscheinen

​Parameterübersicht

​Wann welcher Fehler entsteht

​checkout.directOrder - Onlinebestellschein

​Parameterübersicht

​checkout.productDependency - Produktabhängigkeiten

​Auswertungslogik

​Parameterübersicht

​Prüfarten (type)

​checkout.shippingMethod - Versandarten

​Parameterübersicht

​checkout.shippingMethodGroup - Versandarten-Gruppen

​Parameterübersicht

​checkout.shipTrack - Paketverfolgung

​Parameterübersicht

`checkout*` - Grundstruktur

Parameterübersicht

`checkout.checkout` - Bestellablauf

Parameterübersicht

Mindermengenzuschlag

Wirkungslose Gutscheine blockieren

Adressen aus dem PayPal Express Checkout

Templates nach dem Bestellabschluss

Fehleranzeige im Checkout

`checkout.voucher` - Einstellungen für Gutscheine

Parameterübersicht

`checkout.voucherErrors` - Fehlertexte zu wirkungslosen Gutscheinen

Parameterübersicht

Wann welcher Fehler entsteht

`checkout.directOrder` - Onlinebestellschein

Parameterübersicht

`checkout.productDependency` - Produktabhängigkeiten

Auswertungslogik

Parameterübersicht

Prüfarten (`type`)

`checkout.shippingMethod` - Versandarten

Parameterübersicht

`checkout.shippingMethodGroup` - Versandarten-Gruppen

Parameterübersicht

`checkout.shipTrack` - Paketverfolgung

Parameterübersicht