checkout - Bestellablauf - WEBSALE Dokumentation

Der Abschnitt checkoutumfasst 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": {...},
      "directOrder": {...},
      "productDependency": {...},
      "bankInfoField": {...},
      "shippingMethod": {...},
      "shipTrack": {...},
      "fieldErrorVisibility": {...}
    }
}

Parameterübersicht

Parameter	Beschreibung
`checkout`	Übergreifende Checkout-Einstellungen für den Bestellprozess.
`directOrder`	Konfiguration für Direktbestellungen.
`productDependency`	Regeln für Produktabhängigkeiten im Checkout.
`bankInfoField`	Steuerung von Bankdatenfeldern.
`shippingMethod`	Einstellungen zu Versandarten.
`shipTrack`	Optionen für die Sendungsverfolgung.
`fieldErrorVisibility`	Steuert, wann Feldfehler im Checkout angezeigt werden.

`checkout.checkout` - Bestellablauf

Dieser Abschnitt bündelt die Einstellungen für den Checkout. Hier wird festgelegt, wie der Bestellprozess abläuft, welche Zusatzfelder angezeigt werden und wie beispielsweise Versandoptionen standardmäßig gewählt werden. Zudem lassen sich Regeln für Gutschein-Berechnungen, länderspezifische Versandfreiheit und optional für die Paketverfolgung definieren.

Beispielkonfiguration `checkout.checkout`

{
  "allowFastOrder": true,
  "allowGuestAccounts": true,
  "allowGuestOrderWithRegisteredEmail": true,
  "allowShipTrack": false,
  "defaults": {
    "defaultBillCountry": null,
    "defaultShippingCountry": null,
    "defaultPaymentMethod": null,
    "defaultShippingMethod": null,
    "autoSelectSingleOption": true
  },
  "defaultFreeShippingMethod": null,
  "deliveryRequiredForOrder": true,
  "freeFields": [
    {
      "id": "agb",
      "name": "AGB",
      "required": true,
      "type": {
        "checkbox": {
          "merchantText": "agb text here"
        }
      }
    },
    {
      "id": "comment",
      "name": "Bemerkung",
      "required": false,
      "type": {
        "text": {
          "textfieldChecks": [
            {
              "options": {
                "len": 32
              },
              "service": "textfieldCheck.maxlen"
            }
          ]
        }
      }
    }
  ],
  "freeShippingCountries": null,
  "subtotalRounding": {
    "active": true,
    "decimalPlaces": 2
  },
  "voucherAppliesPerItem": true
}

Parameterübersicht

Parameter	Typ	Beschreibung
`allowGuestAccounts`	bool	Erlaubt Bestellungen ohne Kundenkonto (Gastbestellung). Default: `true`
`allowGuestOrderWithRegisteredEmail`	bool	Legt fest, ob eine Gastbestellung mit einer bereits registrierten E-Mail-Adresse erlaubt ist. 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.
`freeShippingCountries` (zukünftiges Feature, noch nicht vollständig implementiert!)	multiAssoc	Länder, in denen versandkostenfrei geliefert wird. Target: `general.country`
`allowFastOrder`	bool	Erlaubt die Bestellung per Express-Checkout. Default: `true`
`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`
`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`
`freeFields`	list (object)	Konfigurierbare Zustatzfelder im Checkout (z.B. Hinweise, Kundennotizen). Jedes Objekt beschreibt ein Feld.
`id`	string	Eindeutige Kennung des Zusatzfeldes.
`name`	string	Anzeigname / Label im Checkout
`required`	string	Markiert das Feld als Pflichtfeld. Default: `false`
`type`	oneOf	Feldtyp und Detailkonfiguration.
`text`	object	Textfeld-Konfiguration.
`checkbox`	object	Checkbox-Konfiguration.
`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-Addresse (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. Default: `true`

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).

`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.

Beispielkonfiguration `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.

Beispielkonfiguration `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"
        }
      ]
    }
  ]
}

Parameterübersicht

Parameter	Typ	Beschreibung
`id`	string	Eindeutig Kennung der Produktabhängigkeit, die selbst gewählt werden kann. Die `id` wird in der Validierung `shippingMethodValidation.productDependency` angegeben. Mehr dazu unter: Validierungs- und Prüfservices
`disabledText`	string	Hinweis-/Fehlermeldung, die angezeigt wird, wenn Bedingungen nicht erfüllt sind. Wird im Frontend angezeigt.
`dependencyGroups`	list (object)	Enthält eine oder mehrere Regelgruppen.
`dependencies`	list (object)	Liste einzelner Bedingungen innerhalb einer Gruppe. 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 (z.B. gefüllt/leer, Größenvergleich). (`filled`, `empty`, `value`, `notvalue`, `inlist`, `notinlist`, `prefix`, `notprefix`, `includedinlist`, `notincludedinlist`, `greater`, `smaller`, `matchsimplewildcard`, `notmatchsimplewildcard`)
`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 relevanten Positionen. Default:`matchOnce`

`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. So entstehen klar benannte, regelkonforme Versandoptionen mit transparenter Preislogik und optionalen Einschränkungen.

Beispielkonfiguration `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": "shippingValidation.countryAllowed",
      "options": { "countries": ["DE", "AT"] }
    },
    {
      "service": "shippingValidation.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"
}

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.
`type`		`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.

`checkout.shipTrack` - Paketverfolgung

Konfiguriert die Anbindung an Versanddienstleister zur Sendungsverfolgung. Hinterlegt werden Provider-Kennung (z. B. DHL, Hermes, UPS) 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.

Beispielkonfiguration `checkout.shippingMethod`

{
  "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 nur “`dhl`” möglich). Wird für die Zuordnung der Tracking-Integration genutzt.
`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).

`checkout.fieldErrorVisibility` - Fehleranzeige

Legt fest, wann Fehlermeldungen im Checkout angezeigt werden, z.B. ob ein Hinweis auf ein fehlendes Pflichtfeld sofort erscheint, auch ohne dass der Kunde das Feld berührt hat, oder erst, wenn der Kunde auf “Kaufen” klickt.

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.

Beispielkonfiguration checkout.fieldErrorVisibility

{
fieldErrorVisibility:
  showMissingBeforeSubmit: false
  showInvalidBeforeSubmit: true
  showIncompatibleBeforeSubmit: true
}

Parameterübersicht

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”.
`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”.
`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”.

Konfiguration

Documentation Index

​checkout* - Grundstruktur

​Parameterübersicht

​checkout.checkout - Bestellablauf

​Beispielkonfiguration checkout.checkout

​Parameterübersicht

​checkout.directOrder - Onlinebestellschein

​Beispielkonfiguration checkout.directOrder

​Parameterübersicht

​checkout.productDependency - Produktabhängigkeiten

​Beispielkonfiguration checkout.productDependency

​Parameterübersicht

​checkout.shippingMethod - Versandarten

​Beispielkonfiguration checkout.shippingMethod

​Parameterübersicht

​checkout.shipTrack - Paketverfolgung

​Beispielkonfiguration checkout.shippingMethod

​Parameterübersicht

​checkout.fieldErrorVisibility - Fehleranzeige

`checkout*` - Grundstruktur

Parameterübersicht

`checkout.checkout` - Bestellablauf

Beispielkonfiguration `checkout.checkout`

Parameterübersicht

`checkout.directOrder` - Onlinebestellschein

Beispielkonfiguration `checkout.directOrder`

Parameterübersicht

`checkout.productDependency` - Produktabhängigkeiten

Beispielkonfiguration `checkout.productDependency`

Parameterübersicht

`checkout.shippingMethod` - Versandarten

Beispielkonfiguration `checkout.shippingMethod`

Parameterübersicht

`checkout.shipTrack` - Paketverfolgung

Beispielkonfiguration `checkout.shippingMethod`

Parameterübersicht

`checkout.fieldErrorVisibility` - Fehleranzeige