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.

Inhaltsverzeichnis

1 1. checkout* - Grundstruktur
2 2. checkout.checkout - Bestellablauf
3 3. checkout.direktOrder - Onlinebestellschein
4 4. checkout.productDependency - Produktabhängigkeiten
5 5. checkout.shippingMethod - Versandarten
6 6. checkout.shipTrack - Paketverfolgung

1. `checkout*` - Grundstruktur

Nachfolgend der Grundaufbau des Knotens checkout:

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

Parameterübersicht

Parameter	Beschreibung

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.

2. `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,
  "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

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.

3. `checkout.direktOrder` - 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

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

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

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: https://websale.atlassian.net/wiki/spaces/WSDOKU/pages/3457744913/Validierungs-+und+Pr+fservices#4.-shippingMethodValidation.*---Versandarten-Validierung
`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`

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

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.

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

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 - Bestellablauf

Inhaltsverzeichnis

1. checkout* - Grundstruktur

Parameterübersicht

2. checkout.checkout - Bestellablauf

Beispielkonfiguration checkout.checkout

Parameterübersicht

3. checkout.direktOrder - Onlinebestellschein

Beispielkonfiguration checkout.directOrder

Parameterübersicht

4. checkout.productDependency - Produktabhängigkeiten

Beispielkonfiguration checkout.productDependency

Parameterübersicht

5. checkout.shippingMethod - Versandarten

Beispielkonfiguration checkout.shippingMethod

Parameterübersicht

6. checkout.shipTrack - Paketverfolgung

Beispielkonfiguration checkout.shippingMethod

Parameterübersicht

1. `checkout*` - Grundstruktur

2. `checkout.checkout` - Bestellablauf

Beispielkonfiguration `checkout.checkout`

3. `checkout.direktOrder` - Onlinebestellschein

Beispielkonfiguration `checkout.directOrder`

4. `checkout.productDependency` - Produktabhängigkeiten

Beispielkonfiguration `checkout.productDependency`

5. `checkout.shippingMethod` - Versandarten

Beispielkonfiguration `checkout.shippingMethod`

6. `checkout.shipTrack` - Paketverfolgung

Beispielkonfiguration `checkout.shippingMethod`