checkout - Checkout process - WEBSALE Dokumentation

The checkout section covers everything that controls the order process in the storefront: from simple guest or quick orders through custom input fields to rounding of subtotals. It also enables fast item entry by article number, validates basket content against rules (e.g. mandatory accessories) if required, manages shipping methods including pricing logic and integrates package tracking.

`checkout*` - Basic structure

Below is the basic structure of the checkout node

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

Parameter overview

Parameter	Description
`checkout`	Overall checkout settings for the order process.
`voucher`	Settings for the use of vouchers in the order process.
`directOrder`	Configuration for direct orders.
`productDependency`	Rules for product dependencies in the checkout.
`bankInfoField`	Control of bank data fields.
`shippingMethod`	Settings for shipping methods.
`shippingMethodGroup`	Groups to which shipping methods can be assigned.
`shipTrack`	Options for shipment tracking.
`fieldErrorVisibility`	Controls when field errors are displayed in the checkout.

`checkout.checkout` - Checkout process

This section bundles the checkout settings. It defines how the order process runs, which additional fields are displayed and how, for example, shipping options are selected by default. In addition, rules can be defined for voucher calculations, country-specific free shipping and, optionally, for package tracking.

Example configuration `checkout.checkout`

{
  "allowFastOrder": true,
  "allowGuestAccounts": true,
  "allowGuestOrderWithRegisteredEmail": true,
  "allowShipTrack": false,
  "defaults": {
    "defaultBillCountry": null,
    "defaultShippingCountry": null,
    "defaultPaymentMethod": null,
    "defaultShippingMethod": null,
    "autoSelectSingleOption": true,
    "prevSelectionInvalidAutoSelect": "disabled"
  },
  "defaultFreeShippingMethod": null,
  "deliveryRequiredForOrder": true,
  "freeFields": [...],
  "freeShippingCountries": null,
  "subtotalRounding": {
    "active": true,
    "decimalPlaces": 2
  },
  "voucherAppliesPerItem": true,
  "minOrderValueCalculation": "max",
  "minOrderValueIgnoreVoucherReduction": true
}

Parameter overview

Parameter	Type	Description
`allowGuestAccounts`	bool	Allows orders without a customer account (guest order). Default: `true`
`allowGuestOrderWithRegisteredEmail`	bool	Defines whether a guest order using an already registered email address is allowed. Default: `true`
`subtotalRounding`	object	Rounding of the subtotal before further calculations (e.g. before shipping / vouchers).
`active`	bool	Enables the rounding logic. Default: `true`
`decimalPlaces`	uint	Number of decimal places for rounding. Default: `2`
`voucherAppliesPerItem`	bool	Controls whether vouchers are applied per line item (instead of on the entire basket).
`minOrderValueCalculation`	enum	Defines how the minimum order value from which a voucher can be applied is calculated. Possible values: `sum` - the minimum order values of all applied vouchers are added up. If, for example, voucher A has a minimum order value of €20 and voucher B of €30, the basket must reach at least €50. `max` - only the highest minimum order value of all applied vouchers counts. With voucher A (€20) and voucher B (€30), €30 in the basket is sufficient.
`minOrderValueIgnoreVoucherReduction`	bool	Determines which goods value is used to check the minimum order value. Possible values: `true` - only the pure goods value counts. `false` - the goods value minus already applied vouchers is used.
`freeShippingCountries` (future feature, not yet fully implemented!)	multiAssoc	Countries in which delivery is free of shipping costs. Target: `general.country`
`allowFastOrder`	bool	Allows ordering via express checkout. Default: `true`
`defaultFreeShippingMethod`	singleAssoc	Defines the default shipping method used for “free shipping” calculations (e.g. displaying “€45 more for free shipping”). Target: `checkout.shippingMethod`
`deliveryRequiredForOrder`	bool	Specifies whether a shipping method must be selected in order to complete the order. `true` - checkout only possible with a selected shipping method. `false` - order allowed without selecting a shipping method. Default: `true`
`freeFields`	list (object)	Configurable additional fields in the checkout (e.g. notes, customer comments). Each object describes one field.
`id`	string	Unique identifier of the additional field.
`name`	string	Display name / label in the checkout.
`required`	string	Marks the field as required. Default: `false`
`type`	oneOf	Field type and detailed configuration.
`text`	object	Text field configuration.
`checkbox`	object	Checkbox configuration.
`defaults`	object	Defines default values for fields in the checkout.
`defaultBillCountry`	singleAssoc	Default country for the billing address. Pre-filled when a new address is created in the checkout — for the draft address (draftBillAddress) as well as for guest orders. Target: `general.country`
`defaultShippingCountry`	singleAssoc	Default country for the shipping address. Pre-filled when a new address is created in the checkout — for the draft address (draftShippingAddress) as well as for guest orders. Target: `general.country`
`defaultPaymentMethod`	singleAssoc	Payment method that is preselected by default in the checkout. Target: `payment.payment`
`defaultShippingMethod`	singleAssoc	Shipping method that is preselected by default in the checkout. Target: `checkout.shippingMethod`
`autoSelectSingleOption`	bool	If enabled, a shipping method or payment method is selected automatically if only one valid option is available. Default: `true`
`prevSelectionInvalidAutoSelect`	enum	Controls whether a previously selected shipping or payment method is automatically replaced when it becomes invalid due to a change in the order context (e.g. change of the delivery country). Applies to shipping and payment methods (no separate option per type). Possible values: `disabled` - no automatic re-selection through this option; the selection is marked as invalid and the customer picks again (`autoSelectSingleOption` still applies). `ifSingleOption` - if exactly one valid method remains, it is chosen automatically (even if `autoSelectSingleOption` is disabled); if several remain valid, no automatic selection is made. `always` - a valid replacement method is always selected: preferably the configured default (`defaultShippingMethod` or `defaultPaymentMethod`) if it is valid; otherwise the single remaining valid method. Default: `disabled`

Priority logic for defaults: If multiple sources (e.g. user selection or customer preferences) provide a value for a field in defaults, the following priority order applies:

Active user selection in the current session — is never automatically overridden.
Stored customer preferences of a signed-in customer (where supported).
Merchant configuration — the defaults values defined here.
System fallback — e.g. automatic selection if only one option is available or first valid option after sorting (see autoSelectSingleOption).

Re-selection when a chosen method subsequently becomes invalid:The priority logic above applies to the initial selection. If, however, a previously made but now invalid selection is handled — for example because the customer changes the delivery country and the selected shipping method is not offered there — prevSelectionInvalidAutoSelect controls how the shop reacts (see table above). autoSelectSingleOption remains active as a fallback in all modes.

Note on rounding behaviour with position-based voucher calculation:
If “voucherAppliesPerItem” is set to “true” and a percentage voucher with a configured maximum amount is used, the granted discount may exceed this maximum amount by up to €0.01. The reason is that the discount is rounded individually per line item and the sum of these roundings may deviate slightly from the expected total.

`checkout.voucher` - Voucher settings

This section bundles the settings for the use of vouchers in the order process. Among other things, it defines how many vouchers a customer can redeem at the same time and how discount amounts of percentage vouchers are rounded arithmetically.

Example configuration `checkout.voucher`:

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

Parameter overview

Parameter	Type	Description
`maxNumberVouchersPerOrder`	uint	Maximum number of vouchers that can be applied per order. Possible values: `1` - `20` Default: `1`
`roundPercentalVoucherInBasketItem`	enum	Defines how discount amounts from percentage vouchers are rounded per item when several vouchers are active at the same time. Possible values: `sum` - the discount of each individual voucher is initially calculated unrounded per item. All discount amounts are added up and the result is rounded only at the end. `single` - the discount amount of each voucher is rounded individually per item immediately. Because every rounding can introduce a small error, the total savings deviate by a few cents from the `sum` result depending on the item price and voucher amount.

`checkout.directOrder` - Online order form

Allows fast entry of items by article number — for example for large or recurring orders. It defines which columns are visible per row (e.g. article number, quantity). Optionally, the system remembers the last used number of rows via saveCountInSession.

Example configuration `checkout.directOrder`

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

Parameter overview

Parameter	Type	Description
`fields`	multiAssoc	Defines the product fields that are searched to find a product (e.g. `content.productField.id, content.productField.itemnumber).` Example: if `id` or `itemNumber` are configured, the user can enter either the product ID or the article number. Target: `[content.productField], [content.customProductField]`
`initialNumber`	int	Number of rows visible on the first load. Default: 5
`itemNumberFields`	list (object)	Input fields per row for capturing article numbers — defines columns / fields and labels (e.g. order, label, placeholder).
`maximalNumber`	int	Upper limit of the total permitted input rows. Default: 1000
`refreshedNumber`	int	Number of additional rows added when clicking the “Add rows” button. Default: 5
`saveCountInSession`	bool	Saves the current row count in the session so it is restored on the next visit. default: true

`checkout.productDependency` - Product dependencies

This section defines when certain steps or options are allowed in the checkout. It checks the contents of the basket — such as properties like size, colour or whether an additional field has been filled — and can display a notice or block the action if the conditions are not met. Typical use cases are, for example, mandatory accessories or preventing prohibited combinations in the checkout.

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

Evaluation logic

The rule groups and conditions are evaluated according to a fixed scheme:

dependencyGroups are OR-linked: it is sufficient if one of the groups is completely fulfilled.
dependencies within a group are AND-linked: within a group, all conditions must be fulfilled.
Whether an individual condition is considered fulfilled is additionally controlled by basketBehavior: with matchOnce, at least one basket line item must fulfil the condition; with matchAll, all line items in which the checked field provides a value must do so.

In the example above the dependency is therefore considered fulfilled if either the first group applies (one line item with the colour camel and one line item with an empty engraving free field in the basket) or the second group (one line item with size S, M or L).

Parameter overview

Parameter	Type	Description
`id`	string	Unique identifier of the product dependency, which can be chosen freely. The `id` is referenced in the validations `shippingMethodValidation.productDependency` (shipping methods) and `paymentValidation.productDependency` (payment methods). More on this under: Validation and checking services
`disabledText`	string	Notice/error message displayed when conditions are not fulfilled. For shipping methods the text is output in the frontend via `$wsCheckout.getShippingMethodDisabledErrors()`.
`dependencyGroups`	list (object)	Contains one or more rule groups. The groups are OR-linked (see evaluation logic above).
`dependencies`	list (object)	List of individual conditions within a group. The conditions are AND-linked. Each condition defines which field is checked, how the check is performed and which comparison value is needed, if any.
`target`	oneOf	Defines which field is checked. (Required)
`field`	singleAssoc	Reference to a product field that is checked. Target: `content.productField, content.customProductField`
`freeField`	string	Name of a free field (e.g. a free field on the product/basket) that is checked. (Alternative to `field`)
`type`	enum	Required Comparison type of the condition. The possible values are described in the “Check types” table below.
`input`	oneOf	Comparison value of the condition. (Only required if the `type` needs a comparison value). For example, not required for `filled` / `empty.`
`text`	object	Text-based comparison value.
`value`	string	Value for text-based comparisons. (e.g. for `value`, `prefix`, `matchsimplewildcard`)
`list`	object	Value list for list comparisons (e.g. for `inlist`, `includedinlist`).
`value`	list (string)	Value list for the comparison.
`basketBehavior`	enum	Defines how many basket line items must fulfil the condition: `matchOnce` = at least one line item `matchAll` = all line items in which the checked field provides a value. Default:`matchOnce`

Check types (`type`)

Value	Description
`filled`	The field is filled. No `input` required.
`empty`	The field is empty. No `input` required.
`value`	The value of the field equals the value provided in `input`.
`notvalue`	The value of the field does not equal the value provided in `input`.
`inlist`	The value of the field is contained in the list provided in `input`.
`notinlist`	The value of the field is not contained in the list provided in `input`.
`prefix`	The value of the field starts with the prefix provided in `input`.
`notprefix`	The value of the field does not start with the prefix provided in `input`.
`greater`	The value of the field is (numerically) greater than the value provided in `input`.
`smaller`	The value of the field is (numerically) smaller than the value provided in `input`.
`includedinlist`	The value provided in `input` is contained in the value list of the product data field (for fields that contain multiple values).
`notincludedinlist`	The value provided in `input` is not contained in the value list of the product data field.
`matchsimplewildcard`	The value of the field matches the pattern provided in `input`. The placeholders `?` (exactly one arbitrary character) and `*` (any number of arbitrary characters) are available; both can be used multiple times and in any position.
`notmatchsimplewildcard`	The value of the field does not match the pattern provided in `input`.

`checkout.shippingMethod` - Shipping methods

Defines available shipping methods and their behaviour in the checkout. In addition to activation, name and order notes, price scales by weight (weightCost) and by basket subtotal (basicCost) can be configured. Via validations (validations) conditions such as allowed countries, physical products only or other rules can be set. Additionally, description, image/icon and external link (e.g. carrier info) are possible. Via the group field a shipping method can also be assigned to a shipping method group. This results in clearly named, rule-compliant shipping options with transparent pricing logic and optional restrictions.

Example configuration `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 overview

Parameter	Type	Description
`active`	bool	Enables / disables the shipping method in the shop.
`id`	string	Unique identifier of the shipping method.
`name`	string	Display name of the shipping method.
`orderText` (future feature / still in development)	text	Order / note text for the shipping method.
`validations`	multiService	List of check / approval rules (e.g. country / product restrictions).
`link` (future feature / still in development)	text	External link with additional information.
`description` (future feature / still in development)	string	Short description of the shipping method.
`image` (future feature / still in development)	string	Image / icon URL of the shipping method.
`weightCost`	object	Tiered prices by weight.
`basicCost`	object	Tiered prices by basket subtotal.
`taxable`	bool	Defines whether taxes are calculated on the shipping cost. With `false`, the shipping-cost tax rate is reported as `0` in the order.
`type`	enum	`standard` or `pickup`. `standard` refers to a “normal” shipment via a carrier such as DHL, UPS, etc. `pickup` indicates “click and collect” — pickup at a store, market or branch. The `CheckoutStoreIdSelect` action is used for selection in the checkout process. If no store has been selected, the store from the general selection is used by default.
`group`	singleAssoc	Assigns the shipping method to a shipping method group. Target: `checkout.shippingMethodGroup`

`checkout.shippingMethodGroup` - Shipping method groups

Defines groups to which shipping methods can be combined (e.g. by carrier or delivery type). A shipping method is assigned to a group via its group field. For each group, name, description, image and a link can be defined — for example to bundle and display several shipping methods uniformly in the frontend.

Example configuration `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 overview

Parameter	Type	Description
`id`	string	Unique identifier of the shipping method group.
`name`	text	Display name of the group.
`description`	text	Description of the group.
`image`	string	Image / icon URL of the group.
`link`	string	External link with additional information about the group.

In the template the groups are read via $wsConfig.shippingMethodGroups. The group assigned to a shipping method is available there in the group field of the shipping method.

`checkout.shipTrack` - Package tracking

Configures the connection to shipping service providers for shipment tracking. Provider identifier and credentials (API user/token) are stored as well as a language code for provider responses and labelling. Based on this data, tracking links and status information can be provided in the checkout or in the customer account and used automatically in notifications.

Example configuration `checkout.shipTrack`

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

Parameter overview

Parameter	Type	Description
`id`	string	Unique identifier of the shipment-tracking configuration.
`provider`	string	Provider identifier. Currently only `DHL` is supported — the value must be written exactly like this (case-sensitive), otherwise the tracking integration cannot be assigned.
`username`	string	API user name / access for the provider.
`password`	string	API password / token for the provider.
`languageCode`	string	Language code for labels / responses of the provider (ISO, e.g. de, en). Empty = for `DHL`, `de` is used.

`checkout.fieldErrorVisibility` - Error display

Defines when error messages are displayed in the checkout, e.g. whether a hint about a missing required field appears immediately, even without the customer having interacted with the field, or only when the customer clicks “Buy”.

Example configuration `checkout.fieldErrorVisibility`

{
  "showMissingBeforeSubmit": false,
  "showInvalidBeforeSubmit": true,
  "showIncompatibleBeforeSubmit": true
}

Parameter overview

Parameter	Type	Description
`showMissingBeforeSubmit`	bool	If `true`, “required field missing” indicators are already shown before the customer clicks “Buy”. If `false`, they only appear after the click on “Buy”.
`showInvalidBeforeSubmit`	bool	If `true`, validation errors (e.g. invalid ZIP, incorrect date format) are shown immediately after input. If `false`, they only appear after the click on “Buy”.
`showIncompatibleBeforeSubmit`	bool	If `true`, incompatibility errors (e.g. payment method not available for this country) are shown immediately. If `false`, they only appear after the click on “Buy”.

After clicking “Buy”, all errors are displayed by default, regardless of this setting.In the checkout there are basically two types of errors:

Errors that the system detects itself (e.g. “required field empty”, “invalid ZIP”):
These are provided via $wsCheckout.problems.* and can be fully controlled via the show*BeforeSubmit parameters.
Errors that the server reports back (e.g. after clicking “Buy”):
Here the settings of the show*BeforeSubmit parameters only apply in part. For customer data and draft addresses, $wsCheckout.problems.* is not available, so server errors are filtered there via the show*BeforeSubmit parameters instead. In all other areas of the checkout (e.g. for the payment method), server errors are always displayed immediately, regardless of the configuration.

​checkout* - Basic structure

​Parameter overview

​checkout.checkout - Checkout process

​Example configuration checkout.checkout

​Parameter overview

​checkout.voucher - Voucher settings

​Example configuration checkout.voucher:

​Parameter overview

​checkout.directOrder - Online order form

​Example configuration checkout.directOrder

​Parameter overview

​checkout.productDependency - Product dependencies

​Example configuration checkout.productDependency

​Evaluation logic

​Parameter overview

​Check types (type)

​checkout.shippingMethod - Shipping methods

​Example configuration checkout.shippingMethod

​Parameter overview

​checkout.shippingMethodGroup - Shipping method groups

​Example configuration checkout.shippingMethodGroup

​Parameter overview

​checkout.shipTrack - Package tracking

​Example configuration checkout.shipTrack

​Parameter overview

​checkout.fieldErrorVisibility - Error display

​Example configuration checkout.fieldErrorVisibility

​Parameter overview

`checkout*` - Basic structure

Parameter overview

`checkout.checkout` - Checkout process

Example configuration `checkout.checkout`

Parameter overview

`checkout.voucher` - Voucher settings

Example configuration `checkout.voucher`:

Parameter overview

`checkout.directOrder` - Online order form

Example configuration `checkout.directOrder`

Parameter overview

`checkout.productDependency` - Product dependencies

Example configuration `checkout.productDependency`

Evaluation logic

Parameter overview

Check types (`type`)

`checkout.shippingMethod` - Shipping methods

Example configuration `checkout.shippingMethod`

Parameter overview

`checkout.shippingMethodGroup` - Shipping method groups

Example configuration `checkout.shippingMethodGroup`

Parameter overview

`checkout.shipTrack` - Package tracking

Example configuration `checkout.shipTrack`

Parameter overview

`checkout.fieldErrorVisibility` - Error display

Example configuration `checkout.fieldErrorVisibility`

Parameter overview