> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.
# checkout - Bestellablauf
> Der Konfigurationsknoten checkout steuert den Bestellprozess der Storefront: Gast- und Schnellbestellung, Zusatzfelder, Rundung, Gutscheinlogik, Mindermengenzuschlag, Versandarten und -gruppen, Paketverfolgung sowie Fehleranzeige.
export const TextbausteinHinweis = () => <>
Dieser Text wird über einen Textbaustein realisiert.
Alles zu Textbausteinen in Konfigurationen finden Sie{" "}
hier.
;
export const KonfigDeeplink = ({node}) => <>
Die Einstellung kann über folgenden Link direkt im Admin-Interface geöffnet werden:{" "}
{`https:///admin/config/${node}`}{" "}
(Deeplink-Übersicht)
;
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`
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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`](#checkout-vouchererrors-fehlertexte-zu-wirkungslosen-gutscheinen). |
| `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](/frontend/funktionsubersicht/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`](#checkout-shippingmethod-versandarten), die Rundung von Gutscheinbeträgen unter [`checkout.voucher`](#checkout-voucher-einstellungen-fur-gutscheine), die Fehlertexte zu wirkungslosen Gutscheinen unter [`checkout.voucherErrors`](#checkout-vouchererrors-fehlertexte-zu-wirkungslosen-gutscheinen), 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`:
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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`](#checkout-shiptrack-paketverfolgung) 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](#wirkungslose-gutscheine-blockieren). Default: `true` |
| `surcharge` | object | Mindermengenzuschlag für kleine Warenkörbe. Siehe [Mindermengenzuschlag](#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](#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](#templates-nach-dem-bestellabschluss). Default: `[]` |
| `fieldErrorVisibility` | object | Legt fest, ab wann Feldfehler im Checkout angezeigt werden. Siehe [Fehleranzeige im Checkout](#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](/frontend/referenz/aktionen/checkout)) 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](/frontend/referenz/aktionen/checkout)) 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:
1. Aktive Benutzerauswahl in der aktuellen Sitzung - wird niemals automatisch überschrieben.
2. Gespeicherte Kundenpräferenzen eines eingeloggten Kunden (sofern unterstützt).
3. Händler-Konfiguration - die hier definierten `defaults`-Werte.
4. 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:
1. 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.
2. Enthält der Warenkorb keine zuschlagspflichtige Position, fällt kein Zuschlag an.
3. Übersteigt die Summe den Wert `threshold`, fällt kein Zuschlag an.
4. 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:
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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:
```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ if $wsCheckout.sum.surchargeCost > 0 }}
Mindermengenzuschlag
{{= $wsCheckout.sum.surchargeCost | currency }}
{{ /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:
1. Der Kunde löst einen Gutschein ein. Der Gutschein liegt in der Session.
2. Bei jeder Berechnung prüft der Shop für jeden eingelösten Gutschein, ob er im aktuellen Warenkorb einen Rabatt größer `0` erzeugt.
3. 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](#wann-welcher-fehler-entsteht).
4. Reine Versandkosten-Gutscheine ohne Prozent- und ohne Absolutwert sind davon ausgenommen. Sie wirken über die Versandkosten und blockieren die Bestellung nie.
5. 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:
```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ if $wsCheckout.isOrderBlockedByIneffectiveVoucher }}
Gutscheine können nicht eingelöst werden:
{{ foreach $cError in $wsCheckout.ineffectiveVoucherErrors }}
{{ else }}
{{ /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`](#checkout-vouchererrors-fehlertexte-zu-wirkungslosen-gutscheinen). Den Aufbau der einzelnen Fehlerobjekte finden Sie in der Modul-Referenz unter [`$wsCheckout.ineffectiveVoucherErrors`](/frontend/referenz/module/wscheckout#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:
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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:
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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.\*](/frontend/referenz/module/wscheckout) 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](/frontend/referenz/aktionen/checkout) 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`:
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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`](/frontend/referenz/module/wscheckout#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](#wirkungslose-gutscheine-blockieren).
Nachfolgend eine Beispielkonfiguration für `checkout.voucherErrors`:
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"ineffectiveVoucherErrorCodes": {
"noValidProducts": "",
"minOrderValueNotReached": ""
}
}
```
### 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:
1. **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.
2. **Rabattwirkung im Warenkorb.** Erreicht der Warenkorb den Mindestbestellwert und bleibt der berechnete Rabatt trotzdem `0`, entsteht `noValidProducts` für diesen Gutschein.
3. **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](/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`:
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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`:
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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](/konfiguration/validierungs-und-prufservices#4-shippingmethodvalidation-versandarten-validierung) |
| `disabledText` | string | Hinweis-/Fehlermeldung, die angezeigt wird, wenn Bedingungen nicht erfüllt sind. Bei Versandarten wird der Text im Frontend über [`$wsCheckout.getShippingMethodDisabledErrors()`](/frontend/referenz/module/wscheckout#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](#checkout-shippingmethodgroup-versandarten-gruppen) zuordnen. So entstehen klar benannte, regelkonforme Versandoptionen mit transparenter Preislogik und optionalen Einschränkungen.
Nachfolgend eine Beispielkonfiguration für `checkout.shippingMethod`:
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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`:
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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`:
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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. |
## Related topics
- [Bestellablauf](/frontend/funktionsubersicht/bestellablauf.md)
- [Storefinder](/frontend/funktionsubersicht/storefinder.md)
- [Konfigurations-Deeplinks](/admin-interface/konfigurations-deeplinks.md)
- [$wsShipTrack - Sendungsverfolgung](/frontend/referenz/module/wsshiptrack.md)
- [$wsDirectOrder - Direktbestellung](/frontend/referenz/module/wsdirectorder.md)