checkout - Order process - WEBSALE Dokumentation

The checkout section covers everything that controls the order process in the storefront: from a simple guest or express order through to custom input fields and the rounding of subtotals. It also enables quick item capture by item number, validates basket contents against rules (e.g. mandatory accessories) on demand, manages shipping methods including pricing logic and integrates parcel tracking.

`checkout*` - Basic structure

The basic structure of the checkout node is shown below:

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

Parameter overview

Parameter	Description
`checkout`	Cross-cutting checkout settings for the order process.
`voucher`	Settings for voucher usage 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.
`shipTrack`	Options for parcel tracking.
`fieldErrorVisibility`	Controls when field errors are displayed in the checkout.

`checkout.checkout` - Order process

This section bundles the settings for the checkout. Here you define how the order process runs, which additional fields are shown and, for example, how shipping options are selected by default. In addition, you can configure rules for voucher calculations, country-specific free shipping and optionally for parcel tracking.

Example configuration `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": [...],
  "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 with 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 used for rounding. Default: `2`
`voucherAppliesPerItem`	bool	Controls whether vouchers are applied per position (instead of on the total 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 vouchers used are summed up. For example, if 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 used vouchers applies. With voucher A (€20) and voucher B (€30), €30 in the basket is sufficient.
`minOrderValueIgnoreVoucherReduction`	bool	Determines which item value is used for the minimum order value check. Possible values: `true` — only the gross item value counts. `false` — the item value minus already applied vouchers is used.
`freeShippingCountries` (future feature, not yet fully implemented!)	multiAssoc	Countries that are delivered to free of shipping. 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. display “€45 left until free shipping”). Target: `checkout.shippingMethod`
`deliveryRequiredForOrder`	bool	Specifies whether a shipping method must be selected for the order to be completed. `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 remarks). 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 creating a new address in the checkout — when using the draft address (draftBillAddress) as well as for guest orders. Target: `general.country`
`defaultShippingCountry`	singleAssoc	Default country for the delivery address. Pre-filled when creating a new address in the checkout — when using the draft address (draftShippingAddress) as well as for guest orders. Target: `general.country`
`defaultPaymentMethod`	singleAssoc	Payment method that is pre-selected in the checkout by default. Target: `payment.payment`
`defaultShippingMethod`	singleAssoc	Shipping method that is pre-selected in the checkout by default. Target: `checkout.shippingMethod`
`autoSelectSingleOption`	bool	If enabled, a shipping method or payment method is automatically selected when only one valid option is available. Default: `true`

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 overwritten.
Stored customer preferences of a signed-in customer (if supported).
Merchant configuration — the defaults values defined here.
System fallback — e.g. automatic selection when only one option is available, or the first valid option after sorting (see autoSelectSingleOption).

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 position, and the sum of these roundings may deviate marginally from the expected total.

`checkout.voucher` - Voucher settings

This section bundles the settings for using vouchers in the order process. Among other things, it defines how many vouchers a customer can redeem simultaneously and how discount amounts are rounded for percentage vouchers.

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 per item are rounded when multiple vouchers are active simultaneously. Possible values: `sum` — the discount of each individual voucher is first 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 each rounding can introduce a small error, the overall saving deviates by a few cents from the `sum` result depending on the item price and voucher amount.

`checkout.directOrder` - Online order form

Allows quick capture of items by item number — for example for large or recurring orders. You define which columns are visible per row (e.g. item number, quantity). On request, the system remembers the most recently used row count 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 which product fields are searched in order 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 visible when first loaded. Default: 5
`itemNumberFields`	list (object)	Input fields per row for item number capture — defines columns / fields and labels (e.g. order, label, placeholder).
`maximalNumber`	int	Upper limit of allowed input rows in total. Default: 1000
`refreshedNumber`	int	Number of available rows added when clicking the “Add rows” button. Default: 5
`saveCountInSession`	bool	Stores 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 in the checkout are allowed. It checks the contents of the basket — for example properties such as size, colour or whether an additional field is filled — and, if not met, can display a hint or block the action. Typical use cases include mandatory accessories or preventing forbidden 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"
        }
      ]
    }
  ]
}

Parameter overview

Parameter	Type	Description
`id`	string	Unique identifier of the product dependency that you choose yourself. The `id` is referenced by the following validations: - shippingMethodValidation.productDependency (shipping methods) - paymentValidation.productDependency (payment methods)
`disabledText <Textbaustein>`	text	Hint / error message that is displayed when the conditions are not met. Shown in the frontend.
`dependencyGroups`	list (object)	Contains one or more rule groups.
`dependencies`	list (object)	List of individual conditions within a group. Each condition defines which field is checked, how it is checked and which comparison value (if any) is needed.
`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 (e.g. filled/empty, size comparison). (`filled`, `empty`, `value`, `notvalue`, `inlist`, `notinlist`, `prefix`, `notprefix`, `includedinlist`, `notincludedinlist`, `greater`, `smaller`, `matchsimplewildcard`, `notmatchsimplewildcard`)
`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 positions must satisfy the condition: `matchOnce` = at least one position. `matchAll` = all relevant positions. Default:`matchOnce`

`checkout.shippingMethod` - Shipping methods

Defines available shipping methods and their behaviour in the checkout. In addition to activation, name and order notes, you can configure price tiers by weight (weightCost) and by basket subtotal (basicCost). Through validations (validations) you can define conditions such as allowed countries, physical products only or other rules. In addition, description, image/icon and external link (e.g. carrier info) are possible. The result is 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": "<Textbaustein>",
  "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": "<Textbaustein>",
  "image": "https://cdn.example.com/shipping/dhl.png",
  "type": "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 / hint texts for the shipping method.
`validations`	multiService	List of validation / 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.
`type`		`standard` or `pickup`. `standard` denotes a “regular” delivery via a carrier such as DHL, UPS, etc. `pickup` indicates that it is “click and collect” and therefore a pickup at a store, market or branch. For the selection in the order process the `CheckoutStoreIdSelect` action is used. If no market has been selected, the market from the general selection is used by default.

`checkout.shipTrack` - Parcel tracking

Configures the connection to shipping providers for parcel tracking. The provider identifier (e.g. DHL, Hermes, UPS) and credentials (API user/token) as well as a language code for provider responses and labelling are stored here. Based on this data, tracking links and status information can be made available in the checkout or in the customer account and used automatically in notifications.

Example configuration `checkout.shippingMethod`

{
  "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 shipping tracking configuration.
`provider`	string	Provider identifier (currently only “`dhl`” is possible). Used to assign the tracking integration.
`username`	string	API username / credentials 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).

`checkout.fieldErrorVisibility` - Error display

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

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

Errors detected by the system itself (e.g. “required field empty”, “invalid postal code”):
These are provided via $wsCheckout.problems.* and can be fully controlled via the show*BeforeSubmit parameters.
Errors returned by the server (e.g. after clicking “Buy”):
Here the settings of the show*BeforeSubmit parameters only partially apply. For customer data and draft addresses, $wsCheckout.problems.* is not available; server errors are therefore filtered there via the show*BeforeSubmit parameters instead. In all other areas of the checkout (e.g. the payment method), server errors are always displayed immediately regardless of the configuration.

Example configuration checkout.fieldErrorVisibility

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

Parameter overview

Parameter	Type	Description
`showMissingBeforeSubmit`	bool	If `true`, “required field missing” fields are shown even before the customer clicks “Buy”. If `false`, they only appear after clicking “Buy”.
`showInvalidBeforeSubmit`	bool	If `true`, validation errors (e.g. invalid postal code, incorrect date format) are shown immediately after input. If `false`, they only appear after clicking “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 clicking “Buy”.

​checkout* - Basic structure

​Parameter overview

​checkout.checkout - Order 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

​Parameter overview

​checkout.shippingMethod - Shipping methods

​Example configuration checkout.shippingMethod

​Parameter overview

​checkout.shipTrack - Parcel tracking

​Example configuration checkout.shippingMethod

​Parameter overview

​checkout.fieldErrorVisibility - Error display

`checkout*` - Basic structure

Parameter overview

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

Parameter overview

`checkout.shippingMethod` - Shipping methods

Example configuration `checkout.shippingMethod`

Parameter overview

`checkout.shipTrack` - Parcel tracking

Example configuration `checkout.shippingMethod`

Parameter overview

`checkout.fieldErrorVisibility` - Error display