> ## 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 - Order flow
> The checkout configuration node controls the storefront's order process: guest and fast orders, additional fields, rounding, voucher logic, small-quantity surcharge, shipping methods and groups, parcel tracking, and error display.
export const KonfigDeeplink = ({node}) => <>
You can open this setting directly in the Admin Interface via the following link:{" "}
{`https:///admin/config/${node}`}{" "}
(Deeplink overview)
;
The `checkout` section covers everything that controls the order process in the storefront: from the simple guest or fast order via custom input fields to the rounding of subtotals. It also enables quick item entry by item number, checks basket contents against rules on demand (e.g. mandatory accessories), manages shipping methods including price logic and integrates parcel tracking.
## `checkout*` - Basic structure
The basic structure of the `checkout` node is shown below:
```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 overview
| **Parameter** | **Description** |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `checkout` | Overarching checkout settings for the order process. |
| `voucher` | Settings for the use of vouchers in the order process. |
| `voucherErrors` | Error texts for vouchers that have no effect in the basket. See [Blocking ineffective vouchers](#blocking-ineffective-vouchers). |
| `directOrder` | Configuration for direct orders. |
| `productDependency` | Rules for product dependencies in checkout. |
| `bankInfoField` | Control of bank data fields. |
| `shippingMethod` | Shipping method settings. |
| `shippingMethodGroup` | Groups into which shipping methods can be combined. |
| `shipTrack` | Options for shipment tracking. |
## `checkout.checkout` - Order flow
This section bundles the central settings of the order process. It is aimed at shop operators who define the flow commercially and at frontend developers who output the result in the template. It is assumed that you are familiar with the general [order flow](/en/frontend/funktionsubersicht/bestellablauf).
Defined here is how the order process runs, which additional fields appear and how shipping and payment methods are pre-selected. Also located here are the rules for voucher calculations, a small-quantity surcharge, the handling of addresses from the PayPal Express Checkout, and the point at which field errors become visible.
Not covered in this section: shipping methods and their price logic are under [`checkout.shippingMethod`](#checkout-shippingmethod-shipping-methods), the rounding of voucher amounts under [`checkout.voucher`](#checkout-voucher-voucher-settings), payment methods under `payment.payment`.
The settings take effect at four different points in the flow. This categorisation helps to find the right parameter:
* **Before the order - access and pre-selection:** Who is allowed to order (`allowGuestAccounts`, `allowFastOrder`), what is pre-selected (`defaults`), which additional fields appear (`freeFields`).
* **During the order - calculation:** Subtotal rounding (`subtotalRounding`), voucher calculation (`voucherAppliesPerItem`, `minOrderValueCalculation`, `minOrderValueIgnoreVoucherReduction`, `disableOrderOnIneffectiveVoucher`) and the small-quantity surcharge (`surcharge`).
* **During the order - display of errors:** `fieldErrorVisibility`.
* **After the order:** Which templates may still access the order data (`templatesAfterCheckout`).
Below is an example configuration for `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 overview
| **Parameter** | **Type** | **Description** |
| ----------------------------------------------------------------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `allowGuestAccounts` | bool | Allows orders without a customer account (guest order). Default: `true` |
| `allowFastOrder` | bool | Allows ordering via express checkout. Default: `true` |
| `allowShipTrack` | bool | Activates shipment tracking for the shop. The credentials of the service provider are stored under [`checkout.shipTrack`](#checkout-shiptrack-parcel-tracking). Default: `false` |
| `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` |
| `subtotalRounding` | object | Rounding of the subtotal before further calculations (e.g. before shipping / vouchers). |
| `active` | bool | Activates 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 total basket). Default: `false` |
| `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 applies. With voucher A (€20) and voucher B (€30), €30 in the basket is sufficient. Default: `sum` |
| `minOrderValueIgnoreVoucherReduction` | bool | Determines which merchandise value is used for the minimum order value check. Possible values: `true` - only the plain merchandise value counts. `false` - the merchandise value less already-applied vouchers is used. Default: `true` |
| `disableOrderOnIneffectiveVoucher` | bool | Blocks the order as long as a redeemed voucher does not produce a discount in the current basket. The default `true` prevents a customer from ordering in the belief that a discount will apply. When a voucher is considered ineffective is described under [Blocking ineffective vouchers](#blocking-ineffective-vouchers). Default: `true` |
| `surcharge` | object | Small-quantity surcharge for small baskets. See [Small-quantity surcharge](#small-quantity-surcharge). |
| `cost` | float | Surcharge amount in shop currency that is charged if the threshold is not exceeded. Default: `0.0` |
| `threshold` | float | Threshold: if the sum of the surchargeable line items exceeds this value, the surcharge is waived. With the default `0.0`, the surcharge is effectively disabled, as any basket with value is above that. Default: `0.0` |
| `expressCheckoutSkipsAddressValidation` | bool | Controls whether the address delivered by the PayPal Express Checkout is taken over as the regular billing and delivery address and checked against the shop's validation rules. See [Addresses from the PayPal Express Checkout](#addresses-from-the-paypal-express-checkout). Default: `true` |
| `templatesAfterCheckout` | list (string) | Templates that may still access the order data after order completion. See [Templates after order completion](#templates-after-order-completion). Default: `[]` |
| `fieldErrorVisibility` | object | Defines from when field errors are displayed in checkout. See [Error display in checkout](#error-display-in-checkout). |
| `showMissingBeforeSubmit` | bool | Displays missing required fields already before the click on "Buy". Default: `false` |
| `showInvalidBeforeSubmit` | bool | Displays validation errors already before the click on "Buy". Default: `true` |
| `showIncompatibleBeforeSubmit` | bool | Displays incompatibility errors already before the click on "Buy". Default: `true` |
| `freeShippingCountries` (**future feature,** **not yet fully** **implemented!**) | multiAssoc | Countries in which shipping is free. Target: `general.country` |
| `defaultFreeShippingMethod` | singleAssoc | Defines the standard shipping method that is used for "free shipping" calculations (e.g. display "€45 to free shipping"). Target: `checkout.shippingMethod` |
| `freeFields` | list (object) | Configurable additional fields in checkout (e.g. notes, customer notes, T\&C confirmation). Each object describes a field. |
| `id` | string | Unique identifier of the additional field. Via this identifier you read the field in the template from `$wsCheckout.freeFields`. |
| `name` | text | Display name / label in checkout. |
| `required` | bool | Marks the field as required. Default: `false` |
| `type` | oneOf | Field type and detail configuration: `text` or `checkbox`. |
| `text` | object | Text field configuration. |
| `default` | string | Prefilled value of the text field. |
| `textfieldChecks` | multiService | Check rules for the input. Target: `dataChecker` |
| `checkbox` | object | Checkbox configuration. |
| `default` | bool | Defines whether the checkbox is pre-selected. Default: `false` |
| `merchantText` | string | Internal text for the checkbox for the merchant. |
| `defaults` | object | Defines default values for fields in checkout. |
| `defaultBillCountry` | singleAssoc | Default country for the billing address. Pre-filled when creating a new address in checkout - when using the draft address ([draftBillAddress](/en/frontend/referenz/aktionen/checkout)) as well as in guest orders. Target: `general.country` |
| `defaultShippingCountry` | singleAssoc | Default country for the delivery address. Pre-filled when creating a new address in checkout - when using the draft address ([draftShippingAddress](/en/frontend/referenz/aktionen/checkout)) as well as in guest orders. Target: `general.country` |
| `defaultPaymentMethod` | singleAssoc | Payment method that is pre-selected by default in checkout. Target: `payment.payment` |
| `defaultShippingMethod` | singleAssoc | Delivery method that is pre-selected by default in checkout. Target: `checkout.shippingMethod` |
| `autoSelectSingleOption` | bool | When enabled, a shipping method or payment method is automatically selected if only one valid option is available. This spares the customer a selection without an alternative. Default: `true` |
| `prevSelectionInvalidAutoSelect` | enum | Controls whether an already selected shipping or payment method is automatically replaced when it becomes invalid due to a change in the order context (e.g. change of 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 chooses anew (`autoSelectSingleOption` continues to apply). `ifSingleOption` - if exactly one valid method remains, it is automatically chosen (even if `autoSelectSingleOption` is disabled); if several remain valid, no automatic selection is made. `always` - a valid replacement method is always chosen: preferably the configured default method (`defaultShippingMethod` or `defaultPaymentMethod`), if valid; otherwise the only remaining valid method. The default `disabled` is the most restrained variant: a deliberate customer selection is never silently swapped for another. Default: `disabled` |
Whether a guest order with an already registered email address is allowed is not defined here, but in the configuration of the `CheckoutSetGuestEmail` action under `restrictions.allowGuestOrderWithRegisteredEmail`.
**Priority logic for** `defaults`:
If several sources (e.g. user selection or customer preferences) provide a value for a field in `defaults`, the following order of priority applies:
1. Active user selection in the current session - is never automatically overwritten.
2. Stored customer preferences of a logged-in customer (if supported).
3. Merchant configuration - the `defaults` values defined here.
4. System fallback - e.g. automatic selection when only one option is available, or the 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, on the other hand, an already made but now invalid selection is handled - e.g. because the customer changes the delivery country and the chosen 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 for line-item-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 minimally from the expected total.
### Small-quantity surcharge
The small-quantity surcharge is a fixed amount that is added to small baskets. In this way, the shop covers the processing and shipping costs that are proportionally too high for a small order.
The shop recalculates the surcharge on every basket calculation, in the following order:
1. The shop forms the sum of the surchargeable line items. What is counted is the line total, i.e. price times quantity. Sub-items of a set are not counted, because otherwise they would go into the sum twice.
2. If the basket contains no surchargeable line items, no surcharge is applied.
3. If the sum exceeds the value `threshold`, no surcharge is applied.
4. Otherwise `cost` is calculated as the surcharge.
The comparison in step 3 is a "greater than". With `"threshold": 30` and a sum of exactly €30.00, the surcharge still applies; from €30.01 upwards it no longer does. Set the threshold accordingly to the last amount for which the surcharge should still apply.
By default, every line item is surchargeable. You can exempt individual products via the product field that is stored under `content.usedFields.validForSurcharge`: if this field returns `false` for a line item, it is neither counted for the check nor does it trigger the surcharge. This is useful, for example, for voucher products or digital items that do not incur processing effort.
An example: A surcharge of €1.99 should apply up to a merchandise value of €30. The configuration in `checkout.checkout` is then:
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"surcharge": {
"cost": 1.99,
"threshold": 30.0
}
}
```
Output in the cost breakdown of the template. The surcharge is available as a calculated amount in `$wsCheckout.sum.surchargeCost`; if it is `0`, the line is not output:
```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ if $wsCheckout.sum.surchargeCost > 0 }}
Small-quantity surcharge
{{= $wsCheckout.sum.surchargeCost | currency }}
{{ /if }}
```
Expected effect: For a basket of €24.50, the line appears with €1.99, and the total rises to €26.49. For a basket of €45.00, the line is omitted.
### Blocking ineffective vouchers
A customer can redeem a voucher that produces no discount at all in the current basket. If they order in this state, this leads to a query or complaint because the expected discount is missing. `disableOrderOnIneffectiveVoucher` prevents this.
The flow:
1. The customer redeems a voucher. The voucher is stored in the session.
2. On every calculation, the shop checks for each redeemed voucher whether it produces a discount greater than `0` in the current basket.
3. A voucher is considered ineffective in two cases: the basket does not reach its minimum order value, or the calculated discount is `0` because no line item in the basket is eligible for a discount from this voucher.
4. Pure shipping-cost vouchers without a percentage or absolute value are exempt. They act via the shipping costs and never block the order.
5. If `disableOrderOnIneffectiveVoucher` is active and at least one voucher is ineffective, the shop reports the order as blocked.
In the template, you read the state via the flag `$wsCheckout.isOrderBlockedByIneffectiveVoucher` and disable the order button:
```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ if $wsCheckout.isOrderBlockedByIneffectiveVoucher }}
A redeemed voucher does not take effect in this basket. Please check the
minimum order value or remove the voucher.
{{ else }}
{{ /if }}
```
Expected effect: After redeeming a voucher with a €50 minimum order value into a basket of €20, the order button is disabled and the notice appears. After topping up the basket beyond €50, the button is active again.
You maintain the associated error texts not here, but in the configuration node `checkout.voucherErrors` under `ineffectiveVoucherErrorCodes`. There the two cases are stored separately as `noValidProducts` and `minOrderValueNotReached`, so that you can give the customer the concrete reason instead of a general notice.
Only set the parameter to `false` if customers in your shop are deliberately allowed to leave vouchers in the basket without them taking effect.
### Addresses from the PayPal Express Checkout
If a customer starts the PayPal Express Checkout from the basket, PayPal returns the address stored there. This address does not always meet the validation rules of your shop - for example because PayPal does not pass on the house number separately. `expressCheckoutSkipsAddressValidation` defines how the shop handles this.
**`true` (default):** The shop does not validate the address and does not take it over as the billing or delivery address of the order. It remains in the session and is available in the order data under `paypalCheckout.rawAddress`. Third-party systems can read it there and, if needed, process it themselves. The default `true` thus keeps the shop's address data free from unvalidated third-party data - the delivery address in the shop remains clean.
**`false`:** The address is taken directly from PayPal as a regular address. It then has to meet the shop's validation rules. Since it comes unvalidated from the PayPal account, it may not comply with these rules. In this case the customer must edit the address before completing the order - the Express Checkout thereby loses its advantage of being completable without an additional entry step.
Regardless of this setting, the address data is displayed to the customer as far as PayPal supplies it. If PayPal does not deliver a street, for example, no street is shown either.
Excerpt from the order data with the parameter active:
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"paypalCheckout": {
"expressCheckout": "true",
"rawAddress": {
"...": "Address object delivered by PayPal"
}
}
}
```
With the parameter active, the regular address fields of the order do not contain an address from the Express Checkout. It is therefore possible for an order to be created without regular address data. Whether such an order can be further processed depends on the connected connector. Check this before putting the Express Checkout into production.
`true` is the standard path for the PayPal Express Checkout: the shop does not validate the address and does not take it over. Only disable the parameter after review, as effects on the Express Checkout itself cannot be ruled out. PayPal's requirements for this flow are not documented here - clarify them directly with PayPal if needed.
### Templates after order completion
After the order is completed, the session is considered ended. The order data is then only available to the templates that count as part of the order confirmation. If the customer calls up another template, they receive a new session. In this new session, the order data can no longer be reached. This is intentional: a completed order session should not live on longer than necessary.
The target page after checkout is included automatically. Every additional template that needs order data must be entered in `templatesAfterCheckout` - typically a PDF order confirmation:
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"templatesAfterCheckout": [
"pdf/checkoutConfirm.htm"
]
}
```
Expected effect: Without this entry, the PDF order confirmation is empty because `$wsCheckout.orderId` and the remaining order data are missing in the new session. With the entry, order number, line items and totals are output. Missing order data on a follow-up page after checkout is therefore almost always a missing entry in this list.
### Error display in checkout
Not every error should be shown to the customer immediately. Marking an empty required field red before the customer has even reached it feels like a customer's mistake. An incorrectly formatted postal code, on the other hand, should be correctable immediately. `fieldErrorVisibility` separates these cases by error type.
| **Parameter** | **Type** | **Description** |
| ------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `showMissingBeforeSubmit` | bool | If `true`, "required field missing" fields are already displayed before the customer clicks "Buy". If `false`, they only appear after the click on "Buy". The default `false` avoids displaying still-untouched fields as errors. Default: `false` |
| `showInvalidBeforeSubmit` | bool | If `true`, validation errors (e.g. invalid postal code, incorrect date format) are displayed immediately after entry. If `false`, they only appear after the click on "Buy". The default `true` allows correction while the customer is still in the field. Default: `true` |
| `showIncompatibleBeforeSubmit` | bool | If `true`, incompatibility errors (e.g. payment method not available for this country) are displayed immediately. If `false`, they only appear after the click on "Buy". The default `true` prevents the customer from continuing the checkout with a combination that will fail anyway. Default: `true` |
After the click on "Buy", all errors are displayed by default, regardless of this setting.
In checkout there are basically two types of errors:
* Errors that the system itself detects (e.g. "required field empty", "invalid postal code"): These are provided via [\$wsCheckout.problems.\*](/en/frontend/referenz/module/wscheckout) and can be fully controlled via the `show*BeforeSubmit` parameters.
* Errors returned by the server (e.g. after the click on "Buy"): Here the settings of the `show*BeforeSubmit` parameters only apply partially. For customer data and [draft addresses](/en/frontend/referenz/aktionen/checkout), `$wsCheckout.problems.*` is not available, so server errors there are instead filtered via the `show*BeforeSubmit` parameters. In all other areas of the checkout (e.g. payment method), server errors are always displayed immediately, regardless of the configuration.
## `checkout.voucher` - Voucher settings
This section bundles the settings for the use of vouchers in the order process. Here, among other things, the number of vouchers a customer can redeem at the same time and how discount amounts for percentage vouchers are computationally rounded is defined.
Below is an example configuration for `checkout.voucher`:
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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 first calculated per item without rounding. All discount amounts are added up and the result is rounded only at the end. `single` - the discount amount of each voucher is rounded immediately per item, individually. Because each rounding can introduce a small error, the total savings may deviate by a few cents from the `sum` result depending on item price and voucher amount. |
## `checkout.directOrder` - Online order form
Enables quick capture of items by item number - for example for large or recurring orders. It is defined which columns per row are visible (e.g. item number, quantity). On demand, the system remembers the most recently used row count via `saveCountInSession`.
Below is an example configuration for `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 overview
| **Parameter** | **Type** | **Description** |
| -------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fields` | multiAssoc | Defines which product fields 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 item number. Target: `[content.productField], [content.customProductField]` |
| `initialNumber` | int | Number of rows that are visible on initial load. Default: **5** |
| `itemNumberFields` | list (object) | Input fields per row for the item number capture - defines columns / fields and labels (e.g. order, label, placeholder). |
| `maximalNumber` | int | Upper limit of the total number of allowed input rows. Default: **1000** |
| `refreshedNumber` | int | Number of available rows that are added on click of the "Add rows" button. Default: **5** |
| `saveCountInSession` | bool | Saves the current row count in the session so that it is restored on the next call. Default: **true** |
## `checkout.productDependency` - Product dependencies
This section defines when certain steps or options are allowed in checkout. To do so, it checks the contents of the basket - such as properties like size, colour, or whether an additional field is filled in - and can display a notice or block the action if not fulfilled. Typical use cases include mandatory accessories or preventing forbidden combinations in checkout.
Below is an example configuration for `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"
}
]
}
]
}
```
### Evaluation logic
The rule groups and conditions are evaluated according to a fixed scheme:
* **`dependencyGroups` are OR-linked**: It is sufficient for **one** of the groups to be fully satisfied.
* **`dependencies` within a group are AND-linked**: Within a group, **all** conditions must be satisfied.
* Whether a single condition is considered satisfied is additionally controlled by `basketBehavior`: With `matchOnce`, at least one basket line item must satisfy the condition; with `matchAll`, all line items for which the checked field returns a value.
In the example above, the dependency is therefore considered satisfied if either the first group applies (one line item with the colour `camel` **and** one line item with an empty free field `engraving` 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 freely chosen. The `id` is specified in the validations `shippingMethodValidation.productDependency` (shipping methods) and `paymentValidation.productDependency` (payment methods). More on this under: [Validation and check services](/en/konfiguration/validierungs-und-prufservices#4-shippingmethodvalidation-versandarten-validierung) |
| `disabledText` | string | Notice / error message displayed when conditions are not satisfied. For shipping methods, the text is output in the frontend via [`$wsCheckout.getShippingMethodDisabledErrors()`](/en/frontend/referenz/module/wscheckout#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 it is checked and, if necessary, which comparison value is required. |
| `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. free field on 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). E.g. 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 satisfy the condition: `matchOnce` = at least one line item. `matchAll` = all line items for which the checked field returns 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 specified in `input`. |
| `notvalue` | The value of the field does not equal the value specified in `input`. |
| `inlist` | The value of the field is contained in the list specified in `input`. |
| `notinlist` | The value of the field is not contained in the list specified in `input`. |
| `prefix` | The value of the field starts with the prefix specified in `input`. |
| `notprefix` | The value of the field does not start with the prefix specified in `input`. |
| `greater` | The value of the field is (numerically) greater than the value specified in `input`. |
| `smaller` | The value of the field is (numerically) smaller than the value specified in `input`. |
| `includedinlist` | The value specified in `input` is contained in the value list of the product data field (for fields that contain multiple values). |
| `notincludedinlist` | The value specified in `input` is not contained in the value list of the product data field. |
| `matchsimplewildcard` | The value of the field matches the pattern specified in `input`. Available wildcards are `?` (exactly one arbitrary character) and `*` (any number of arbitrary characters); both may be used multiple times and at any position. |
| `notmatchsimplewildcard` | The value of the field does not match the pattern specified in `input`. |
## `checkout.shippingMethod` - Shipping methods
Defines available shipping methods and their behaviour in 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 further 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](#checkout-shippingmethodgroup-shipping-method-groups). This produces clearly named, rule-compliant shipping options with transparent price logic and optional restrictions.
Below is an example configuration for `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": "Shipping with DHL, delivery time 2–3 business days.",
"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": "Reliable standard shipping within DE/AT.",
"image": "https://cdn.example.com/shipping/dhl.png",
"type": "standard",
"group": "checkout.shippingMethodGroup.standard"
}
```
### Parameter overview
| **Parameter** | **Type** | **Description** |
| ----------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `active` | bool | Activates / deactivates 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 under development**) | text | Order / notice texts on the shipping method. |
| `validations` | multiService | List of check / release rules (e.g. country / product restrictions). |
| `link` (**future feature / still under development**) | text | External link with additional info. |
| `description` (**future feature / still under development**) | string | Short description of the shipping method. |
| `image` (**future feature / still under development**) | string | Image / icon URL of the shipping method. |
| `weightCost` | object | Scaled prices by weight. |
| `basicCost` | object | Scaled prices by basket subtotal. |
| `taxable` | bool | Defines whether taxes are charged on the shipping costs. If `false`, the shipping-cost tax rate is shown as `0` in the order. |
| `type` | enum | `standard` or `pickup`. With `standard`, this is a "normal" shipment via a carrier like DHL, UPS, etc. `pickup` indicates "Click and Collect" and therefore a pickup from a store, market or branch. For the selection in the order flow, the action `CheckoutStoreIdSelect` is used. If no market was selected, the market 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 into which shipping methods can be combined (e.g. by provider or delivery type). A shipping method is assigned to a group via its `group` field. Per group, name, description, image and a link can be stored - for example to present several shipping methods bundled and uniformly in the frontend.
Below is an example configuration for `checkout.shippingMethodGroup`:
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"id": "checkout.shippingMethodGroup.express",
"name": "Express shipping",
"description": "Fast delivery within 24 hours.",
"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 info 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` - Parcel tracking
Configures the connection to shipping service providers for **shipment tracking**. Stored are the provider identifier and **credentials** (API user/token) as well as a **language code** for provider responses and labeling. Based on this data, **tracking links** and status information can be provided in checkout or in the customer account and used automatically in notifications.
Below is an example configuration for `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 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 username / 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 = `de` is used for `DHL`. |
## Related topics
- [$wsCheckout - Checkout](/en/frontend/referenz/module/wscheckout.md)
- [actions - Basket & checkout](/en/konfiguration/actions-fehlertexte-e-mails/actions-warenkorb-checkout.md)
- [Configuration deep links](/en/admin-interface/konfigurations-deeplinks.md)
- [Checkout process](/en/frontend/funktionsubersicht/bestellablauf.md)
- [Storefront API Checkout (In Progress)](/en/schnittstellen/storefront-api/storefront-api-checkout-in-progress.md)