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.

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:

{
    "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.
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.

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, the rounding of voucher amounts under checkout.voucher, 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:

{
  "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. 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. Default: true
surcharge	object	Small-quantity surcharge for small baskets. See 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. Default: true
templatesAfterCheckout	list (string)	Templates that may still access the order data after order completion. See Templates after order completion. Default: []
fieldErrorVisibility	object	Defines from when field errors are displayed in checkout. See 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) 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) 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:

{
  "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:

{{ if $wsCheckout.sum.surchargeCost > 0 }}
   <tr>
      <td>Small-quantity surcharge</td>
      <td>{{= $wsCheckout.sum.surchargeCost | currency }}</td>
   </tr>
{{ /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:

{{ if $wsCheckout.isOrderBlockedByIneffectiveVoucher }}
   <p role="alert">
      A redeemed voucher does not take effect in this basket. Please check the
      minimum order value or remove the voucher.
   </p>
   <button type="submit" class="btn btn-warning" disabled>Submit order</button>
{{ else }}
   <button type="submit" class="btn btn-warning">Submit order</button>
{{ /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:

{
  "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:

{
  "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.* 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, $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:

{
  "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:

{
  "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:

{
  "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
disabledText	string	Notice / error message displayed when conditions are not satisfied. 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 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. This produces clearly named, rule-compliant shipping options with transparent price logic and optional restrictions.

Below is an example configuration for checkout.shippingMethod:

{
  "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:

{
  "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:

{
  "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.